@openlup/platform 0.23.0 → 0.25.0

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/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);
+}

package/src/invoicing/continuity.ts

@@ -0,0 +1,15 @@
+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: Parameters<typeof collectInvoiceDuties>[0]) {
+  return {
+    async collect(): Promise<Awaited<ReturnType<typeof collectInvoiceDuties>> | { kind: "unavailable"; code: "retryable" }> {
+      try { return await collectInvoiceDuties(input); }
+      catch { return { kind: "unavailable", code: "retryable" }; }
+    },
+  };
+}

package/src/invoicing/contracts/facts.ts

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

package/src/invoicing/contracts/host.ts

@@ -12,8 +12,8 @@ import type { InvoiceStorePort } from "./store.js";
 export interface InvoiceHostPorts {
   facts: { read(orderId: string): Promise<{ readonly kind: "found"; readonly facts: InvoiceFacts } | { readonly kind: "unknown"; readonly code: "missing_facts" } | InvoiceUnsupported> };
   /** Read the current host seller for the next claim, never per duty. Null orderId
-   * means an unscoped claim (including corrections). P8 freezes this seller at
-   * first claim; revisionRef feeds the claim wrapper's revision argument.
+   * means an unscoped claim (including corrections). The durable wrapper freezes this seller at
+   * the first-ever claim; revisionRef feeds the claim wrapper's revision argument.
    */
   seller: { read(input: { readonly orderId: string | null }): Promise<{ readonly kind: "found"; readonly seller: InvoiceSeller; readonly revisionRef: string } | { readonly kind: "unknown"; readonly code: "unknown" } | InvoiceUnsupported> };
   /** Read-only projection of the final claimed M07 identity, never a refund writer.
@@ -71,8 +71,7 @@ export interface InvoiceHostPorts {
     resolveDownload(input: { readonly accountRef: string; readonly orderId: string; readonly documentRef: string }): Promise<{ readonly kind: "authorized"; readonly identity: InvoiceDocumentIdentity; readonly artifactRef: string; readonly fileName: string; readonly parentDocumentRef: string | null } | { readonly kind: "denied" } | { readonly kind: "unknown"; readonly code: "unknown" } | InvoiceUnsupported>;
   };
 }
-/** Future service composition inputs only; no constructor, worker or runtime route
- * is supplied in P1. Closures/credentials must never be serialized with options.
+/** Explicit service composition inputs; the host retains worker and route authority. Closures/credentials must never be serialized with options.
  */
 export interface InvoiceServicesOptions {
   readonly enabled?: boolean;

package/src/invoicing/contracts/index.ts

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

package/src/invoicing/contracts/store.ts

@@ -1,5 +1,5 @@
 import type { InvoiceHostPorts } from "./host.js";
-import type { InvoiceFacts } from "./facts.js";
+import type { InvoiceFacts, InvoiceClaimedFacts } from "./facts.js";
 import type { InvoiceIdentity, InvoiceDocumentIdentity, InvoiceProof, InvoiceUnsupported, InvoiceWriteResult, InvoiceReadbackResult } from "./provider.js";
 import type { InvoiceClearanceObservation, InvoiceArtifactResult, InvoiceDeliveryPort } from "./delivery.js";
 type InvoiceDutyStatus = "owed" | "blocked" | "ready" | "processing" | "unknown" | "issued" | "voided" | "unsupported" | "faulted";
@@ -14,7 +14,7 @@ export interface InvoiceClaim {
   readonly generation: number;
   readonly leaseUntil: string;
   readonly identity: InvoiceIdentity;
-  readonly facts: InvoiceFacts;
+  readonly facts: InvoiceClaimedFacts;
   readonly action: "create" | "readback";
   readonly correction: { readonly before: InvoiceFacts; readonly reason: string; readonly after: { readonly totalNetMinor: 0; readonly totalTaxMinor: 0; readonly totalGrossMinor: 0 } } | null;
 }
@@ -40,14 +40,15 @@ export interface InvoiceDutyReadback {
 }
 /** Every operation is one local transaction; commit before external I/O. Native
  * success atomically saves late identity and compensation; stale catch writes nothing.
- * Managed and native stores are bound to the selected provider at construction.
+ * Compatibility stores bind provider selection at construction; the structural
+ * native store accepts it per claim and persists the first provider on the duty.
  * No implementation, executor or migration is installed by these declarations.
  */
 export interface InvoiceStorePort {
   /** Never call inside a renewal money, dunning or dispatch transaction without
    * isolation: capture failure must not propagate; the sweep recovers.
    */
-  captureDuty(input: { readonly requestKey: string; readonly sourceKind: "paid" | "handoff"; readonly sourceId: string; readonly orderId: string; readonly occurredAt: string; readonly evidence: { readonly settlementIntentId: string; readonly amountMinor: number; readonly currency: string } | { readonly shipmentId: string; readonly handedOverAt: string } }): Promise<{ readonly dutyId: string; readonly status: InvoiceDutyStatus } | InvoiceUnsupported>;
+  captureDuty(input: { readonly requestKey: string; readonly sourceKind: "paid" | "handoff"; readonly sourceId: string; readonly orderId: string; readonly occurredAt: string; readonly evidence: { readonly settlementIntentId: string; readonly amountMinor: number; readonly currency: string } | { readonly shipmentId: string; readonly handedOverAt: string } }): Promise<{ readonly dutyId: string; readonly status: InvoiceDutyStatus } | { readonly kind: "conflict"; readonly code: "identity_mismatch" } | InvoiceUnsupported>;
   installFacts(input: { readonly dutyId: string; readonly facts: InvoiceFacts }): Promise<{ readonly dutyId: string; readonly status: InvoiceDutyStatus; readonly replayed?: boolean } | InvoiceUnsupported>;
   /** Pinned split facts lease: sweep and prepare commit separately; finishing
    * requires the same token and authoritative document/fact match. No host I/O
@@ -58,7 +59,7 @@ export interface InvoiceStorePort {
   finishFacts(input: { readonly dutyId: string; readonly token: string; readonly result: Omit<Exclude<Awaited<ReturnType<InvoiceStorePort["prepareFacts"]>>, InvoiceUnsupported>, "status"> & { readonly status: "owed" | "ready" | "issued" | "voided" | "unsupported" } }): Promise<{ readonly dutyId: string; readonly status: "owed" | "ready" | "issued" | "voided" | "unsupported" | "faulted" | "stale" } | InvoiceUnsupported>;
   readDuties(orderId: string): Promise<InvoiceDutyReadback | InvoiceUnsupported>;
   /** Filter order before locking/limit; never lease unrelated orders then filter.
-   * P8 reads the injected host seller before calling the first-claim SQL wrapper;
+   * P7 host composition reads the injected seller before the separate first-claim SQL wrapper;
    * its revisionRef supplies p_revision, without requiring a duty from the caller.
    */
   claim(input: { readonly limit: number; readonly visibilitySeconds: number; readonly providerRef: string; readonly orderId?: string | null }): Promise<readonly InvoiceClaim[] | InvoiceUnsupported>;
@@ -80,7 +81,7 @@ export interface InvoiceStorePort {
    * Missing means no M09 duty, never invoice absence: retain/retry the reversal
    * intent and route legacy documents to the incumbent path.
    */
-  requestReversal(input: { readonly requestKey: string; readonly orderId: string; readonly reason: "order_canceled" | "order_refunded"; readonly proof: InvoiceProof }): Promise<{ readonly kind: "missing" | "voided" | "pending_readback" | "correction_requested"; readonly dutyId?: string; readonly replayed?: boolean } | { readonly kind: "unsupported_recorded"; readonly dutyId?: string; readonly replayed?: boolean } | InvoiceUnsupported>;
+  requestReversal(input: { readonly requestKey: string; readonly orderId: string; readonly reason: "order_canceled" | "order_refunded"; readonly proof: InvoiceProof }): Promise<{ readonly kind: "missing" | "voided" | "pending_readback" | "correction_requested"; readonly dutyId?: string; readonly replayed?: boolean } | { readonly kind: "unsupported_recorded"; readonly dutyId?: string; readonly replayed?: boolean } | { readonly kind: "conflict"; readonly code: "identity_mismatch" } | InvoiceUnsupported>;
   /** Existing local-only request remains distinct from fiscal issuance. */
   requestLocalDocument(input: { readonly requestKey: string; readonly orderId: string; readonly providerRef: string }): Promise<{ readonly kind: "requested"; readonly documentId: string; readonly invoiceRef: string; readonly status: string; readonly replayed: boolean } | InvoiceUnsupported>;
   listClearanceTargets(limit: number): Promise<readonly { readonly documentId: string; readonly identity: InvoiceDocumentIdentity; readonly providerDocumentRef: string; readonly providerDocumentNumber: string | null; readonly state: InvoiceClearanceObservation["state"] }[] | InvoiceUnsupported>;
@@ -92,7 +93,10 @@ export interface InvoiceStorePort {
   claimDeliveries(input: { readonly limit: number; readonly visibilitySeconds: number; readonly requireClearance: boolean; readonly orderId?: string | null }): Promise<readonly { readonly token: string; readonly generation: number; readonly identity: InvoiceDocumentIdentity; readonly providerDocumentRef: string; readonly delivery: Omit<Parameters<InvoiceDeliveryPort["send"]>[0], "filename" | "content" | "contentType"> }[] | InvoiceUnsupported>;
   /** Native uncertain settlement passes p_receipt NULL and retains a non-null
    * receiptRef hint in p_evidence; managed uses it as the provider message id.
-   * Managed failed_before_send uses retrySeconds for backoff; native ignores it.
+   * Managed failed_before_send uses the retrySeconds RPC argument. Native
+   * failed_before_send carries { phase: 'before_send', retryable, retrySeconds }
+   * in p_evidence: whole seconds clamp to 60..86400, absent/invalid uses 900.
+   * retryable:false parks at infinity, with failed status and last_error visible.
    */
   settleDelivery(input: { readonly deliveryRef: string; readonly token: string; readonly generation: number; readonly providerDocumentRef: string; readonly retrySeconds: number; readonly result: Exclude<Awaited<ReturnType<InvoiceDeliveryPort["send"]>>, InvoiceUnsupported> }): Promise<{ readonly kind: "recorded" | "stale"; readonly replayed: boolean } | InvoiceUnsupported>;
 }

package/src/invoicing/contribution.ts

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