@openlup/platform 0.22.0 → 0.24.0

package/src/invoicing/accountingCanonicalProviderLines.ts

@@ -0,0 +1,134 @@
+import type { InvoiceLine } from "./contracts/facts.js";
+import { allocateDiscountedGrossTotals } from "./accountingLineAllocation.js";
+
+export function mapCanonicalIssueLines(
+  linesSnapshot: unknown[],
+  chargedTotalGrossMinor: number,
+  chargedTotalNetMinor: number,
+  defaultLabel: string,
+): Array<Pick<InvoiceLine, "quantity" | "unitGrossMinor" | "unitNetMinor" | "totalGrossMinor" | "totalNetMinor"> & { name: string; vatRate: string }> {
+  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: unknown, field: string): number {
+  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: unknown, field: string): number {
+  const number = requiredNonnegativeInteger(value, field);
+  if (number === 0) throw new Error(`accounting_invoice_canonical_${field}_invalid`);
+  return number;
+}
+
+function netFromGross(gross: number, vatRateBps: number): number {
+  return Math.round(gross * 10_000 / (10_000 + vatRateBps));
+}
+
+function canonicalVatRate(vatRateBps: number): string {
+  return normalizeVatRate(String(vatRateBps / 100));
+}
+
+function normalizeVatRate(value: string): string {
+  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: unknown): string | null {
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+
+function numberValue(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}

package/src/invoicing/accountingLineAllocation.ts

@@ -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: number[], chargedTotal: number): number[] {
+  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: number[], chargedTotal: number): number[] {
+  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/src/invoicing/adapterConformance.ts

@@ -0,0 +1,249 @@
+import type { InvoiceCapabilities, InvoiceDocumentIdentity, 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"]>>>[];
+  };
+}
+class ContractFailure extends Error {}
+function requireFact(value: unknown, code: string): asserts value {
+  if (!value) throw new ContractFailure(`INVOICE_CONFORMANCE:${code}`);
+}
+function same(a: unknown, b: unknown): boolean {
+  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 as Record<string, unknown>)[key], (b as Record<string, unknown>)[key]));
+}
+function keys(value: object, allowed: readonly string[]): void {
+  requireFact(value !== null && typeof value === "object", "proof_required");
+  requireFact(Object.keys(value).every(key => allowed.includes(key)), "unexpected_field");
+}
+function proof(value: { evidenceRef: string; fingerprint: string; observedAt: string }, extra: readonly string[] = []): void {
+  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: InvoiceIdentity | InvoiceDocumentIdentity, expected: InvoiceIdentity | InvoiceDocumentIdentity): void {
+  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: unknown, subject: Subject): void {
+  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: InvoiceWriteResult | InvoiceReadbackResult | Awaited<ReturnType<Provider["void"]>>, expected: InvoiceIdentity, operation: "write" | "read" | "void"): void {
+  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: "artifact" | "clearance" | "settlement" | "companyLookup", input: unknown, value: unknown): void {
+  const result = value as Record<string, unknown>;
+  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 as Exclude<InvoiceArtifactResult, { kind: "unsupported" }>, request = input as Parameters<InvoiceHostPorts["artifacts"]["read"]>[0];
+    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 as Awaited<ReturnType<InvoiceHostPorts["clearance"]["observe"]>>;
+    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 as Parameters<InvoiceHostPorts["settlement"]["record"]>[0];
+    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 as Exclude<Awaited<ReturnType<InvoiceHostPorts["registry"]["lookup"]>>, { kind: "unsupported" }>;
+    keys(result, ["kind", "identifier", "legalName", "registrationIds", "address", "taxRegistrations", "sourceRef", "proof", "code"]);
+    const request = input as Parameters<InvoiceHostPorts["registry"]["lookup"]>[0];
+    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: readonly Subject[]): Promise<{ readonly subjects: readonly { readonly subjectId: string; readonly providerRef: string; readonly cases: readonly string[] }[] }> {
+  const evidence: { subjectId: string; providerRef: string; cases: string[] }[] = [];
+  try {
+    requireFact(subjects.length > 0, "subject_required");
+    for (const subject of subjects) {
+      const { capability: caps, provider, fixtures } = subject;
+      const cases: string[] = [];
+      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"] as const) {
+        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 as Parameters<Provider["issue"]>[0]) : () => provider.correct(row.input as Parameters<Provider["correct"]>[0]);
+          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 as Parameters<Provider["correct"]>[0];
+            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 as Parameters<Provider["issue"]>[0], recoveryLookupRequired: true }) : await provider.correct({ ...row.input as Parameters<Provider["correct"]>[0], 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<string, string>();
+      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"] as const) {
+        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 as Parameters<InvoiceHostPorts["artifacts"]["read"]>[0])
+            : operation === "clearance" ? await subject.host.clearance.observe(row.input as Parameters<InvoiceHostPorts["clearance"]["observe"]>[0])
+              : operation === "settlement" ? await subject.host.settlement.record(row.input as Parameters<InvoiceHostPorts["settlement"]["record"]>[0])
+                : await subject.host.registry.lookup(row.input as Parameters<InvoiceHostPorts["registry"]["lookup"]>[0]);
+          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 as Parameters<InvoiceHostPorts["settlement"]["record"]>[0];
+            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/src/invoicing/artifacts.ts

@@ -0,0 +1,19 @@
+const MAX_INVOICE_PDF_BYTES = 25 * 1024 * 1024;
+
+/** Validate transient bytes; this is neither storage proof nor delivery proof. */
+export function assertInvoicePdf(pdf: { content: Uint8Array; contentType: string }): void {
+  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: string, fallback = "invoice"): string {
+  const safe = (value: string) => value.normalize("NFKD")
+    .replace(/[^A-Za-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 100);
+  return `${safe(reference) || safe(fallback) || "invoice"}.pdf`;
+}

package/src/invoicing/bindings.ts

@@ -0,0 +1,80 @@
+import type { InvoiceServicesOptions } from "./contracts/host.js";
+import type { InvoiceUnsupported } from "./contracts/provider.js";
+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";
+
+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 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> {
+  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 } as const;
+  const readiness: InvoiceServices<Result>["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() as Promise<Result>;
+      // 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 }) as Promise<Result>;
+      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),
+      }) as Promise<Result>;
+      if (operation === "documentSync" && jobs?.documentSync) return syncAcceptedInvoiceDocuments(jobs.documentSync) as Promise<Result>;
+      if (operation === "settlementSync" && jobs?.settlementSync) return syncInvoicePayoutSettlements({ ...jobs.settlementSync, settlement: host.settlement }) as Promise<Result>;
+      if (operation === "history" && jobs?.history) return createInvoiceReadModel({ accountHistory: host.accountHistory }).history(jobs.history) as Promise<Result>;
+      return unsupported;
+    },
+  };
+}

package/src/invoicing/capabilities.ts

@@ -0,0 +1,9 @@
+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 function readInvoiceCapabilities(input: { readonly enabled?: boolean; readonly selection: { readonly providerRef: string } | null; readonly capability: InvoiceCapabilities | null }): InvoiceCapabilitySelection {
+  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/src/invoicing/channelPolicy.ts

@@ -0,0 +1,50 @@
+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>;
+}
+
+const ISSUE: ChannelInvoiceDecision = { issue: true, action: "issue", detail: {} };
+
+function refusal(action: ChannelInvoiceAction): ChannelInvoiceDecision {
+  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: OrderInvoicePolicyReader | undefined,
+  lookup: InvoicePolicyLookup,
+): Promise<ChannelInvoiceDecision> {
+  if (!reader) return ISSUE;
+  const action = await reader.readOrderInvoicePolicy(lookup);
+  return action === "issue" ? ISSUE : refusal(action);
+}