@openlup/platform 0.22.0 → 0.24.0

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

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

package/src/invoicing/contracts/companyLookup.ts

@@ -0,0 +1,13 @@
+import type { InvoiceProof, InvoiceUnsupported } from "./provider.js";
+/** Injected registry seam. Host owns identifier validation, freshness and fallback;
+ * lookup evidence never overwrites checkout truth or becomes a renewal prerequisite.
+ * Carrier: accountingControlContracts lookup fields, generalized per A5 fit probe.
+ */
+export interface InvoiceCompanyLookupPort {
+  lookup(input: { readonly identifier: { readonly scheme: string; readonly value: string; readonly country?: string }; readonly asOf: string; readonly sourceRef: string }): Promise<
+    | { readonly kind: "found" | "partial"; readonly identifier: { readonly scheme: string; readonly value: string; readonly country?: string }; readonly legalName: string | null; readonly registrationIds: readonly { readonly scheme: string; readonly value: string }[]; readonly address: { readonly line1: string; readonly postalCode: string; readonly city: string; readonly country: string } | null; readonly taxRegistrations: readonly { readonly scheme: string; readonly status: "active" | "not_registered" | "exempt" | "unknown" }[]; readonly sourceRef: string; readonly proof: InvoiceProof }
+    | { readonly kind: "not_found"; readonly identifier: Parameters<InvoiceCompanyLookupPort["lookup"]>[0]["identifier"]; readonly sourceRef: string; readonly proof: InvoiceProof }
+    | { readonly kind: "unknown"; readonly sourceRef: string; readonly code: "unknown" }
+    | InvoiceUnsupported
+  >;
+}

package/src/invoicing/contracts/delivery.ts

@@ -0,0 +1,24 @@
+import type { InvoiceDocumentIdentity, InvoiceProof, InvoiceUnsupported } from "./provider.js";
+/** Durable opaque references; signed URLs and downloaded bytes are transient. */
+export type InvoiceArtifactResult =
+  | { readonly kind: "found"; readonly identity: InvoiceDocumentIdentity; readonly artifact: { readonly kind: "pdf" | "structured_document" | "clearance_receipt"; readonly ref: string; readonly owner: "provider" | "host_storage"; readonly mediaType: string; readonly proof: InvoiceProof } }
+  | { readonly kind: "absent"; readonly identity: InvoiceDocumentIdentity; readonly evidence: InvoiceProof & { readonly exact: true; readonly complete: true; readonly scope: { readonly identity: InvoiceDocumentIdentity; readonly kind: "pdf" | "structured_document" | "clearance_receipt"; readonly artifactRef: string | null } } }
+  | { readonly kind: "unknown"; readonly identity: InvoiceDocumentIdentity; readonly code: "unknown" }
+  | InvoiceUnsupported;
+/** Observation only; unsupported is never not_required. No clearance submission. */
+export type InvoiceClearanceObservation = { readonly proof: InvoiceProof } & (
+  | { readonly state: "accepted"; readonly reference: string }
+  | { readonly state: "not_submitted" | "pending" | "rejected" | "not_required" | "unsupported"; readonly reference: string | null }
+);
+export interface InvoiceDeliveryPort {
+  /** Host M04 content/transport; provider acceptance is not inbox delivery.
+   * Preserve delivery/request keys, recipient, filename and bytes. Validate PDF
+   * type, size and signature before send; uncertain send must never repeat sending.
+   */
+  send(input: { readonly deliveryRef: string; readonly requestKey: string; readonly attemptCount: number; readonly documentRef: string; readonly orderId: string; readonly orderRef: string; readonly invoiceRef: string; readonly providerDocumentRef: string; readonly clientRef: string | null; readonly recipient: string; readonly source: string | null; readonly providerDocumentNumber: string | null; readonly filename: string; readonly content: Uint8Array; readonly contentType: string }): Promise<
+    | { readonly kind: "provider_accepted"; readonly receiptRef: string; readonly proof: InvoiceProof }
+    | { readonly kind: "failed_before_send"; readonly retryable: boolean; readonly code: "retryable" | "invalid_artifact" }
+    | { readonly kind: "uncertain"; readonly code: "uncertain_delivery"; readonly receiptRef: string | null }
+    | InvoiceUnsupported
+  >;
+}

package/src/invoicing/contracts/facts.ts

@@ -0,0 +1,71 @@
+/** Frozen host facts; no catalogue, registry or country-policy reread on retry.
+ * Carrier: donor providerPorts snapshot and invoiceContracts LocalInvoiceSnapshot;
+ * native invoicing_install_facts adds dates/refs/policyVersion and explicit totals.
+ */
+export interface InvoiceSeller {
+  readonly name: string;
+  readonly address: { readonly line1: string; readonly postalCode: string; readonly city: string };
+  readonly taxIdentifier: { readonly scheme: string; readonly value: string };
+  readonly registrationIds?: readonly { readonly scheme: string; readonly value: string }[];
+  readonly bankAccount: string | null;
+  /** Opaque host routing reference, interpreted only by the selected adapter. */
+  readonly routingRef: string | null;
+}
+export interface InvoiceBuyer {
+  readonly name: string;
+  readonly email: string | null;
+  readonly taxIdentifier: { readonly scheme: string; readonly value: string } | null;
+  readonly companyName: string | null;
+  readonly address: { readonly line1: string | null; readonly postalCode: string | null; readonly city: string | null; readonly country: string | null } | null;
+}
+/** Safe integer minor amounts; taxRateBps is a rate, never a fiscal-support claim.
+ * Preserve array order and quantityUnit; no inferred shipping residual or FX.
+ */
+export interface InvoiceLine {
+  readonly description: string;
+  readonly quantity: number;
+  readonly quantityUnit?: string;
+  readonly unitNetMinor: number;
+  readonly unitGrossMinor: number;
+  readonly totalNetMinor: number;
+  readonly totalTaxMinor: number;
+  readonly totalGrossMinor: number;
+  readonly taxRateBps: number;
+  readonly taxRateLabel?: string;
+  readonly positionKind: "item" | "delivery" | null;
+  readonly catalogTotalGrossMinor: number | null;
+  readonly discountAllocatedMinor: number | null;
+  readonly shippingGrossMinor: number | null;
+  readonly shippingDiscountMinor: number | null;
+}
+export interface InvoiceFacts {
+  readonly factRevision: string;
+  readonly policyVersion: string;
+  readonly refs: { readonly orderId: string; readonly orderRef: string; readonly invoiceRef: string };
+  readonly dates: { readonly issueDate: string; readonly sellDate: string; readonly handedOverAt: string | null; readonly paymentCompletedAt: string | null };
+  /** Host-defined kind selected through the identifier/tax seam, never guessed. */
+  readonly documentKind: string;
+  readonly clearanceRequired: boolean;
+  readonly currency: string;
+  readonly buyer: InvoiceBuyer;
+  /** 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;
+  readonly lines: readonly InvoiceLine[];
+  readonly totalNetMinor: number;
+  readonly totalTaxMinor: number;
+  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

@@ -0,0 +1,84 @@
+import type { InvoiceFacts, InvoiceSeller } from "./facts.js";
+import type { InvoiceDocumentIdentity, InvoiceProof, InvoiceProviderPort, InvoiceUnsupported } from "./provider.js";
+import type { InvoiceArtifactResult, InvoiceClearanceObservation, InvoiceDeliveryPort } from "./delivery.js";
+import type { InvoiceCompanyLookupPort } from "./companyLookup.js";
+import type { InvoiceSettlementPort } from "./settlement.js";
+import type { InvoiceCapabilities } from "./capabilities.js";
+import type { InvoiceStorePort } from "./store.js";
+/** Host facts, fiscal routing, M07 reads, storage, registry, M04 delivery and M12
+ * history are required selections. Every missing native capability refuses before
+ * any write; an owed duty remains observable. This interface grants no authority.
+ */
+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). 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.
+   * Missing nullable money is unavailable, never fabricated zero or mismatch.
+   */
+  money: { read(input: { readonly intentRef: string; readonly providerRef: string; readonly providerPaymentRef: string | null; readonly expectedMoney: { readonly amountMinor: number; readonly currency: string } }): Promise<
+    | { readonly kind: "observed"; readonly status: "succeeded" | "failed" | "pending"; readonly amountMinor: number | null; readonly currency: string | null; readonly proof: InvoiceProof }
+    | { readonly kind: "absent"; readonly evidence: InvoiceProof & { readonly exact: true; readonly complete: true; readonly scope: Parameters<InvoiceHostPorts["money"]["read"]>[0] } }
+    | { readonly kind: "unknown" | "unavailable"; readonly code: "money_unavailable" }
+    | InvoiceUnsupported
+  > };
+  artifacts: {
+    read(input: { readonly identity: InvoiceDocumentIdentity; readonly kind: "pdf" | "structured_document" | "clearance_receipt" }): Promise<InvoiceArtifactResult>;
+    /** Ownership must already be authorized; response bytes are not a storage receipt. */
+    download(input: { readonly identity: InvoiceDocumentIdentity; readonly artifactRef: string }): Promise<{ readonly kind: "downloaded"; readonly content: Uint8Array; readonly contentType: string } | { readonly kind: "unknown"; readonly code: "unknown" } | InvoiceUnsupported>;
+    persist(input: { readonly identity: InvoiceDocumentIdentity; readonly kind: "pdf" | "structured_document" | "clearance_receipt"; readonly content: Uint8Array; readonly contentType: string }): Promise<Exclude<InvoiceArtifactResult, { kind: "absent" }>>;
+  };
+  /** Host identifier/tax/rounding policy; refs must match the selected descriptor.
+   * No jurisdictional default is supplied. Carrier: TaxIdRoutingPort and injected
+   * canonical tax safety in accountingProviderSnapshot.
+   */
+  fiscal: { verify(input: { readonly facts: InvoiceFacts; readonly policies: InvoiceCapabilities["policies"] }): Promise<{ readonly kind: "verified"; readonly documentKind: string; readonly clearanceRequired: boolean; readonly proof: InvoiceProof } | { readonly kind: "refused"; readonly code: "blocked" | "money_mismatch" } | { readonly kind: "unknown"; readonly code: "unknown" } | InvoiceUnsupported> };
+  registry: InvoiceCompanyLookupPort;
+  delivery: InvoiceDeliveryPort;
+  clearance: { observe(input: { readonly identity: InvoiceDocumentIdentity; readonly providerDocumentRef: string }): Promise<{ readonly kind: "observed"; readonly observation: InvoiceClearanceObservation } | { readonly kind: "unknown"; readonly code: "unknown" } | InvoiceUnsupported> };
+  settlement: InvoiceSettlementPort;
+  policy: {
+    /** Carrier: channelInvoicePolicyGate and the approved explicit operator skip.
+     * Suppression receipts have no fabricated document ID. Host persists attribution.
+     * Executor decides before installFacts: suppressed orders get no local document.
+     * Readback consumers merge recorded receipts with duty readback.
+     * Transient read failures return unknown without recording a receipt.
+     */
+    decide(input: { readonly requestKey: string; readonly lookup: { readonly by: "order"; readonly orderId: string } | { readonly by: "fulfillmentOrder"; readonly fulfillmentOrderRef: string } }): Promise<
+      | { readonly kind: "issue"; readonly policyVersion: string }
+      | { readonly kind: "policy_suppressed"; readonly outcome: "channel_issues" | "no_document"; readonly policyVersion: string; readonly requestKey: string }
+      | { readonly kind: "operator_skipped"; readonly outcome: "operator_skip"; readonly actorRef: string; readonly reason: string; readonly requestKey: string }
+      | { readonly kind: "unknown"; readonly code: "unknown" }
+      | InvoiceUnsupported
+    >;
+    receipts(orderId: string): Promise<readonly (Extract<Awaited<ReturnType<InvoiceHostPorts["policy"]["decide"]>>, { kind: "policy_suppressed" | "operator_skipped" }> & { readonly recordedAt: string })[] | { readonly kind: "unknown"; readonly code: "unknown" } | InvoiceUnsupported>;
+  };
+  /** Authenticate and authorize ownership before reading artifacts. Safe projection
+   * only: no buyer/seller payload, raw provider errors, signed URL or arbitrary meta.
+   * Found is a complete owned projection; incomplete reads return unknown.
+   * Carrier: donor document history + customer download ticket owner/lineage.
+   */
+  accountHistory: {
+    read(input: { readonly accountRef: string; readonly orderId: string }): Promise<
+      | { readonly kind: "found"; readonly accountRef: string; readonly orderId: string; readonly documents: readonly { readonly documentRef: string; readonly invoiceRef: string; readonly parentDocumentRef: string | null; readonly role: "original" | "correction" | "replacement"; readonly status: string; readonly issuedAt: string | null; readonly clearance: { readonly state: InvoiceClearanceObservation["state"]; readonly reference: string | null } | null; readonly documentKind: string | null; readonly artifact: "invoice" | "correction"; readonly providerDocumentNumber: string | null; readonly totalGrossMinor: number | null; readonly currency: string; readonly emailState: "not_requested" | "pending" | "provider_accepted" | "failed"; readonly isCurrent: boolean; readonly createdAt: string; readonly downloadAvailable: boolean }[] }
+      | { readonly kind: "denied" }
+      | { readonly kind: "unknown"; readonly code: "unknown" }
+      | InvoiceUnsupported
+    >;
+    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>;
+  };
+}
+/** 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;
+  readonly selection: { readonly providerRef: string } | null;
+  readonly capability: InvoiceCapabilities | null;
+  readonly provider: InvoiceProviderPort | null;
+  readonly store: InvoiceStorePort | null;
+  readonly host: InvoiceHostPorts;
+  readiness(): Promise<{ readonly kind: "ready" } | InvoiceUnsupported>;
+}

package/src/invoicing/contracts/index.ts

@@ -0,0 +1,16 @@
+/** @consumer Frozen fact provider and installed declaration consumer. */
+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. */
+export type { InvoiceArtifactResult, InvoiceClearanceObservation } from "./delivery.js";
+/** @consumer Host payout item recorder and resolver. */
+export type { InvoiceSettlementResult, InvoiceSettlementPort, InvoiceSettlementItem } from "./settlement.js";
+/** @consumer Explicit host selection and readInvoiceCapabilities. */
+export type { InvoiceCapabilities } from "./capabilities.js";
+/** @consumer Injected registry adapter (A5). */
+export type { InvoiceCompanyLookupPort } from "./companyLookup.js";
+/** @consumer Managed/native persistence adapter and operator duty readback; no implementation supplied. */
+export type { InvoiceStorePort, InvoiceDutyReadback } from "./store.js";
+/** @consumer Host composition and offline port-fit witnesses. */
+export type { InvoiceHostPorts, InvoiceServicesOptions } from "./host.js";

package/src/invoicing/contracts/provider.ts

@@ -0,0 +1,78 @@
+import type { InvoiceFacts } from "./facts.js";
+/** Original host key bytes, immutable revision and exact lookup scope travel together.
+ * Carrier: providerPorts create options + approved exact-lookup envelope (fit probe).
+ */
+export interface InvoiceIdentity {
+  readonly providerRef: string;
+  readonly requestKey: string;
+  /** Persisted create identity from claim, distinct from original host request key. */
+  readonly providerCreateIdentity: string;
+  readonly factRevision: string;
+  readonly orderRef: string;
+  readonly invoiceRef: string;
+  readonly operation: "issue" | "full_reversal" | "remote_void";
+  readonly correctionRef: string | null;
+  readonly parentProviderDocumentRef: string | null;
+}
+/** Document rows and donor delivery/history carriers need no issue-duty metadata.
+ * @consumer Host artifacts, clearance, delivery and authorized download adapters.
+ */
+export interface InvoiceDocumentIdentity {
+  readonly providerRef: string;
+  readonly documentRef: string;
+  readonly providerDocumentRef: string | null;
+  readonly orderRef: string;
+  readonly invoiceRef: string;
+  readonly parentProviderDocumentRef: string | null;
+}
+/** A closed diagnostic allowlist in the neutral contract. Codes only.
+ * @consumer A4 bridge and provider/store adapters. */
+export type InvoiceDiagnosticCode =
+  | "faulted" | "missing_facts" | "legacy_facts_unproved" | "retryable" | "blocked"
+  | "unsupported" | "unknown" | "absent" | "host_binding_required"
+  | "selection_required" | "disabled" | "identity_mismatch" | "parent_mismatch"
+  | "money_mismatch" | "money_unavailable" | "invalid_artifact" | "uncertain_delivery";
+/** Missing binding or capability: nothing written.
+ * @consumer Host and provider adapters. */
+export interface InvoiceUnsupported {
+  readonly kind: "unsupported";
+  readonly code: "host_binding_required" | "unsupported";
+  readonly retryable: false;
+  readonly effectMayHaveSucceeded: false;
+}
+/** Evidence references/fingerprints are adapter-filtered; never raw payloads or errors.
+ * @consumer Host recorder, operator readback and adapters. */
+export interface InvoiceProof {
+  readonly evidenceRef: string;
+  readonly fingerprint: string;
+  readonly observedAt: string;
+}
+/** Refused proves a definite provider refusal with no effect; post-request adapter
+ * or transport faults are unknown, even when no acknowledgement was received.
+ */
+export type InvoiceWriteResult =
+  | { readonly kind: "issued"; readonly identity: InvoiceIdentity; readonly providerDocumentRef: string; readonly providerDocumentNumber: string | null; readonly proof: InvoiceProof; readonly replayed: boolean }
+  | { readonly kind: "refused"; readonly identity: InvoiceIdentity; readonly code: Extract<InvoiceDiagnosticCode, "blocked" | "retryable" | "missing_facts" | "identity_mismatch" | "parent_mismatch" | "money_mismatch">; readonly retryable: boolean; readonly effectMayHaveSucceeded: false }
+  | { readonly kind: "unknown"; readonly identity: InvoiceIdentity; readonly code: "unknown"; readonly effectMayHaveSucceeded: true }
+  | InvoiceUnsupported;
+/** Exact scope is the full identity, including operation, parent and revision.
+ * Incomplete/truncated/failed lookup is unknown. Only exact complete absence can
+ * authorize another create; found is proof, never a nullable lookup shortcut.
+ */
+export type InvoiceReadbackResult =
+  | { readonly kind: "found"; readonly identity: InvoiceIdentity; readonly providerDocumentRef: string; readonly providerDocumentNumber: string | null; readonly proof: InvoiceProof }
+  | { readonly kind: "absent"; readonly identity: InvoiceIdentity; readonly evidence: InvoiceProof & { readonly exact: true; readonly complete: true; readonly scope: InvoiceIdentity } }
+  | { readonly kind: "unknown"; readonly identity: InvoiceIdentity; readonly code: "unknown" }
+  | InvoiceUnsupported;
+/** Correction bridge: positive immutable BEFORE facts, explicit zero AFTER,
+ * stable correctionRef and parent proof. Retry requires exact recovery before I/O.
+ * Carrier: donor createFullCorrection options and accountingProviderSnapshot.
+ * @consumer A4 conforming correction bridge and issue/readback adapters.
+ */
+export interface InvoiceProviderPort {
+  issue(input: { readonly identity: InvoiceIdentity & { readonly operation: "issue"; readonly correctionRef: null; readonly parentProviderDocumentRef: null }; readonly facts: InvoiceFacts; readonly recoveryLookupRequired: boolean }): Promise<InvoiceWriteResult>;
+  correct(input: { readonly identity: InvoiceIdentity & { readonly operation: "full_reversal"; readonly correctionRef: string; readonly parentProviderDocumentRef: string }; readonly before: InvoiceFacts; readonly after: { readonly totalNetMinor: 0; readonly totalTaxMinor: 0; readonly totalGrossMinor: 0 }; readonly reason: string; readonly recoveryLookupRequired: boolean }): Promise<InvoiceWriteResult>;
+  read(input: InvoiceIdentity): Promise<InvoiceReadbackResult>;
+  /** Remote void stays cut; always refuse before I/O, never substitute local void. */
+  void(input: InvoiceIdentity & { readonly operation: "remote_void" }): Promise<InvoiceUnsupported>;
+}

package/src/invoicing/contracts/settlement.ts

@@ -0,0 +1,39 @@
+import type { InvoiceProof, InvoiceUnsupported } from "./provider.js";
+/** One immutable balance item, never unique by batch+payment alone.
+ * Carrier: accountingControlContracts settlement + payout balance transaction ID.
+ * Null links and bankReceivedAt are facts; settlement is not an invoice gate.
+ * @consumer Host payout item recorder.
+ */
+export interface InvoiceSettlementItem {
+  readonly requestKey: string;
+  readonly providerRef: string;
+  readonly batchRef: string;
+  readonly itemRef: string;
+  readonly providerPaymentRef: string;
+  readonly paymentIntentRef: string | null;
+  readonly paymentRef: string | null;
+  readonly invoiceRef: string | null;
+  readonly grossMinor: number;
+  readonly feeMinor: number;
+  readonly netMinor: number;
+  readonly currency: string;
+  readonly status: "matched" | "unmatched" | "mismatch" | "bank_pending";
+  readonly bankReceivedAt: string | null;
+  readonly proof: InvoiceProof;
+}
+type ItemScope = Pick<InvoiceSettlementItem, "providerRef" | "batchRef" | "itemRef" | "providerPaymentRef">;
+export type InvoiceSettlementResult =
+  | { readonly kind: "found"; readonly scope: ItemScope; readonly paymentIntentRef: string | null; readonly paymentRef: string | null; readonly invoiceRef: string | null; readonly proof: InvoiceProof }
+  | { readonly kind: "absent"; readonly scope: ItemScope; readonly evidence: InvoiceProof & { readonly exact: true; readonly complete: true; readonly scope: ItemScope } }
+  | { readonly kind: "recorded"; readonly itemRef: string; readonly settlementItemRef: string; readonly replayed: boolean }
+  | { readonly kind: "conflict"; readonly itemRef: string; readonly code: "identity_mismatch" | "money_mismatch" }
+  | { readonly kind: "unknown"; readonly itemRef: string; readonly code: "unknown" }
+  | InvoiceUnsupported;
+/** Host recorder/resolver owns richer item identity. Unsupported before any write
+ * when a native batch/payment row cannot represent distinct items or nullable links.
+ * @consumer Host payout item recorder/resolver.
+ */
+export interface InvoiceSettlementPort {
+  record(item: InvoiceSettlementItem): Promise<Exclude<InvoiceSettlementResult, { kind: "found" | "absent" }>>;
+  resolve(input: ItemScope): Promise<Exclude<InvoiceSettlementResult, { kind: "recorded" | "conflict" }>>;
+}

package/src/invoicing/contracts/store.ts

@@ -0,0 +1,102 @@
+import type { InvoiceHostPorts } from "./host.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";
+/** Native duty/lease fields map to the pinned invoicing_* fixtures. Managed hosts
+ * translate their outboxId/attemptCount fences; never claim transaction equality.
+ */
+export interface InvoiceClaim {
+  readonly dutyId: string;
+  readonly documentId: string;
+  readonly requestId: string;
+  readonly token: string;
+  readonly generation: number;
+  readonly leaseUntil: string;
+  readonly identity: InvoiceIdentity;
+  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;
+}
+/** Exact camel-case shape returned by invoicing_duty_readback. This is not
+ * payment truth's accountingRequested; empty duties never assert invoice absence.
+ * @consumer Operator owed-duty readback.
+ */
+export interface InvoiceDutyReadback {
+  readonly orderId: string;
+  readonly captureFaults: readonly { readonly sourceId: string; readonly state: "retryable" | "faulted" | "resolved"; readonly attempts: number; readonly availableAt: string }[];
+  readonly duties: readonly {
+    readonly dutyId: string;
+    readonly parentDutyId: string | null;
+    readonly documentId: string | null;
+    readonly state: "owed" | "blocked" | "claimed" | "unknown" | "issued" | "voided" | "unsupported" | "faulted";
+    readonly attempts: number;
+    readonly factAttempts: number;
+    readonly diagnosticCode: "faulted" | "missing_facts" | "legacy_facts_unproved" | "retryable" | "blocked" | "unsupported" | "unknown" | "absent" | null;
+    readonly createdAt: string;
+    readonly availableAt: string;
+    readonly leaseUntil: string | null;
+  }[];
+}
+/** Every operation is one local transaction; commit before external I/O. Native
+ * success atomically saves late identity and compensation; stale catch writes nothing.
+ * 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 } | { 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
+   * under the duty lock, and unsupported never silently drops an owed duty.
+   */
+  sweep(limit: number): Promise<{ readonly collected: number; readonly claims: readonly { readonly dutyId: string; readonly token: string }[] } | InvoiceUnsupported>;
+  prepareFacts(input: { readonly dutyId: string; readonly token: string }): Promise<{ readonly status: "owed" | "ready" | "issued" | "voided" | "unsupported" | "stale"; readonly documentId?: string; readonly requestId?: string; readonly code?: "retryable" | "legacy_facts_unproved" } | InvoiceUnsupported>;
+  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.
+   * 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>;
+  preflight(input: { readonly claim: InvoiceClaim; readonly amountMinor: number | null; readonly currency: string | null } & (
+    | { readonly status: "succeeded" | "failed" | "pending" | "unknown" | "unavailable"; readonly proof: InvoiceProof | null }
+    | { readonly status: "absent"; readonly evidence: Extract<Awaited<ReturnType<InvoiceHostPorts["money"]["read"]>>, { kind: "absent" }>["evidence"] }
+  )): Promise<{ readonly kind: "ready" | "blocked" | "mismatch" | "unavailable" | "stale" } | InvoiceUnsupported>;
+  finish(input: { readonly claim: InvoiceClaim; readonly result: Extract<InvoiceWriteResult, { kind: "issued" }> | Extract<InvoiceReadbackResult, { kind: "found" }> }): Promise<{ readonly kind: "issued"; readonly replayed: boolean } | { readonly kind: "stale" } | InvoiceUnsupported>;
+  /** Retryable requires a definite refusal (effectMayHaveSucceeded:false) or a
+   * pre-I/O failure and phase before_send. Every other failure maps to unknown.
+   * Native result kinds other than stale/voided map to recorded.
+   */
+  fail(input: { readonly claim: InvoiceClaim; readonly retrySeconds: number } & (
+    | { readonly kind: "absent"; readonly evidence: Extract<InvoiceReadbackResult, { kind: "absent" }> }
+    | { readonly kind: "retryable"; readonly phase: "before_send"; readonly proof: InvoiceProof | null }
+    | { readonly kind: "blocked" | "unsupported" | "unknown"; readonly proof: InvoiceProof | null }
+  )): Promise<{ readonly kind: "recorded" | "voided" | "stale" } | InvoiceUnsupported>;
+  /** Native post-write unsupported maps to unsupported_recorded, retaining duty/replay.
+   * 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 } | { 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>;
+  /** Native maps clearance state unsupported to observation kind unsupported;
+   * provider_mismatch returns InvoiceUnsupported before recording anything.
+   */
+  recordObservation(input: { readonly requestKey: string; readonly documentId: string; readonly eventRef: string; readonly eventKind: "clearance" | "artifacts" | "unsupported" | "provider_mismatch"; readonly identity: InvoiceDocumentIdentity; readonly providerDocumentRef: string; readonly providerDocumentNumber: string | null; readonly clearance: InvoiceClearanceObservation | null; readonly artifacts: readonly Extract<InvoiceArtifactResult, { kind: "found" }>["artifact"][]; readonly observedAt: string; readonly payloadHash: string; readonly source: "provider_api" | "provider_webhook" | "manual_reconciliation" }): Promise<{ readonly replayed: boolean } | InvoiceUnsupported>;
+  /** Verify M04 binding before claiming; document rows need no M09 issue duty. */
+  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 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])),
+  };
+}

package/src/invoicing/correction.ts

@@ -0,0 +1,56 @@
+import type { InvoiceWriteResult } from "./contracts/provider.js";
+
+/** Durable correction identity, recovery and claim fencing from the donor worker.
+ * Hosts project immutable BEFORE facts and bind a conforming recovery provider.
+ * @consumer server/domains/accounting/accountingJobService.ts
+ */
+export async function runInvoiceCorrectionJob<Claim extends {
+  outboxId: string; attemptCount: number; providerInvoiceId: string;
+  correctionReason: string; payload: Record<string, unknown>;
+}, Snapshot, Result extends Pick<Extract<InvoiceWriteResult, { kind: "issued" }>, "providerDocumentRef" | "providerDocumentNumber">>(input: {
+  createEnabled: boolean;
+  providerEnabled: boolean;
+  claim(): Promise<readonly Claim[]>;
+  project(claim: Claim): Snapshot;
+  /** Resolve accepted/recovered receipts only; unknown is never an ACK or absence. */
+  create(snapshot: Snapshot, options: {
+    correctionReason: string; correctedProviderInvoiceId: string;
+    correctionRef: string; recoveryLookupRequired: boolean;
+  }): Promise<Result>;
+  finish(claim: Claim, result: Result): Promise<unknown>;
+  isClaimFenceError(error: unknown): boolean;
+  fail(claim: Claim, error: unknown, retrySeconds: number): Promise<unknown>;
+}) {
+  if (!input.createEnabled) return skipped("create_disabled");
+  if (!input.providerEnabled) return skipped("provider_disabled");
+  const claims = await input.claim();
+  let updated = 0;
+  let failures = 0;
+  for (const claim of claims) {
+    try {
+      const correctionRef = `accounting-correction:${claim.outboxId}`;
+      if (claim.payload.providerCreateIdentity !== correctionRef) {
+        throw new Error("accounting_correction_recovery_identity_missing");
+      }
+      const snapshot = input.project(claim);
+      const result = await input.create(snapshot, {
+        correctionReason: claim.correctionReason,
+        correctedProviderInvoiceId: claim.providerInvoiceId,
+        correctionRef,
+        recoveryLookupRequired: claim.attemptCount > 1,
+      });
+      await input.finish(claim, result);
+      updated += 1;
+    } catch (error) {
+      failures += 1;
+      if (input.isClaimFenceError(error)) continue;
+      try {
+        await input.fail(claim, error, Math.min(3600, 300 * Math.max(1, claim.attemptCount)));
+      } catch (failureError) {
+        if (!input.isClaimFenceError(failureError)) throw failureError;
+      }
+    }
+  }
+  return { ok: failures === 0, checked: claims.length, updated, skipped: false, failures };
+}
+function skipped(reason: string) { return { ok: true, checked: 0, updated: 0, skipped: true, reason, failures: 0 }; }