@openlup/platform 0.22.0 → 0.23.0

package/src/fulfillment/verifiedIngress.ts

@@ -1,20 +1,35 @@
-import type { FulfillmentObservation, FulfillmentObservationPort, FulfillmentRefusal } from "./contracts/index.js";
+import type { FulfillmentObservation, FulfillmentObservationCodecs, FulfillmentObservationPort, FulfillmentRefusal } from "./contracts/index.js";
+import { safeDiagnosticCode } from "./dispatchProjection.js";
 import { applyFulfillmentObservationEffects } from "./fulfillmentObservationEffects.js";
 import { observationStatusPolicy, projectObservation } from "./observationProjection.js";
 import { uniqueTrackingReferences } from "./providerTrackingReferences.js";
 
 type EffectInput = Parameters<typeof applyFulfillmentObservationEffects<FulfillmentObservation["fact"]["canonicalStatus"], "in_transit" | "delivered">>[0];
 type DispatchRef = { orderRef: string; fulfillmentRef: string; dispatchRef: string; externalRef: string | null };
+export interface FulfillmentIngressCounts { invalidTimestamps: number; rejectedCorrelationRefs: number; rejectedTrackingRefs: number; rejectedTrackingUrls: number }
+export type FulfillmentIngressResult = { counts: FulfillmentIngressCounts } & (
+  | { kind: "refused"; receiptId: null; refusal: FulfillmentRefusal; diagnostics?: { invalidTimestamp?: true; rejectedCorrelationRefs?: number } }
+  | { kind: "processed" | "ignored" | "superseded"; receiptId: string; observation: FulfillmentObservation; replayed: boolean; trackingRefs: number; trackingReadBacks: number; supersededCause?: string });
+/** Safe response classes only; the host owns HTTP and localized message text. */
+export function fulfillmentIngressHttpResult(result: FulfillmentIngressResult): { status: 200 | 400 | 403 | 503; messageClass: "accepted" | "bad_request" | "forbidden" | "upstream_unavailable" } {
+  if (result.kind !== "refused") return { status: 200, messageClass: "accepted" };
+  if (result.refusal.reason === "untrusted") return { status: 403, messageClass: "forbidden" };
+  if (result.refusal.reason === "disabled" || result.refusal.reason === "not_ready" || result.refusal.retryable)
+    return { status: 503, messageClass: "upstream_unavailable" };
+  return { status: 400, messageClass: "bad_request" };
+}
 /** Adapter verification owns auth-before-parse; the host owns durable replay. */
 export async function verifyAndNormalizeFulfillmentObservation(input: {
   enabled: boolean;
+  approveTrackingUrl?(url: string): boolean;
+  observationCodecs?: FulfillmentObservationCodecs;
   provider: FulfillmentObservationPort;
   verification: Parameters<FulfillmentObservationPort["verifyAndNormalize"]>[0];
   localPersistence: {
     /** G17: atomic insert by eventKey; retries keep the first stored firstReceivedAt. */
-    recordObservation(observation: FulfillmentObservation): Promise<{ replayed: boolean }>;
+    recordObservation(observation: FulfillmentObservation): Promise<{ replayed: boolean; receiptId?: string }>;
     /** Idempotent; only called after completion or a classified superseding conflict. */
-    markProcessed(eventKey: string, outcome: { status: "processed" | "ignored"; refusal?: FulfillmentRefusal }): Promise<void>;
+    markProcessed(eventKey: string, outcome: { status: "processed" | "ignored"; refusal?: FulfillmentRefusal; supersededCause?: string }): Promise<void>;
   };
   lifecycle: {
     findDispatchRef(observation: FulfillmentObservation): Promise<DispatchRef | null>;
@@ -23,19 +38,34 @@ export async function verifyAndNormalizeFulfillmentObservation(input: {
     effects: EffectInput["port"];
     keys: { stock(ref: string): string; handoff(ref: string): string; tracking(eventKey: string, number: string): string };
     issueAccountingInvoice?(ref: string): Promise<void>;
+    /** Return a machine identity, never exception prose. */
+    supersededCause?(error: unknown): string | null;
     classifyFailure(error: unknown): "stock_contention" | "state_conflict" | "other";
     annotateStockContention?(eventKey: string, fulfillmentRef: string): Promise<void>;
   };
-}): Promise<{ kind: "refused"; refusal: FulfillmentRefusal } | { kind: "processed" | "ignored" | "superseded"; observation: FulfillmentObservation; replayed: boolean; trackingRefs: number; trackingReadBacks: number }> {
-  if (!input.enabled) return { kind: "refused", refusal: { reason: "disabled", phase: "verify", retryable: false } };
+}): Promise<FulfillmentIngressResult> {
+  const counts: FulfillmentIngressCounts = { invalidTimestamps: 0, rejectedCorrelationRefs: 0, rejectedTrackingRefs: 0, rejectedTrackingUrls: 0 };
+  if (!input.enabled) return { kind: "refused", receiptId: null, counts, refusal: { reason: "disabled", phase: "verify", retryable: false } };
   const verified = await input.provider.verifyAndNormalize(input.verification);
-  if (verified.kind === "refused") return verified;
-  const observation = projectObservation(verified.observation);
+  if (verified.kind === "refused") {
+    if (verified.diagnostics?.invalidTimestamp) counts.invalidTimestamps++;
+    const rejected = verified.diagnostics?.rejectedCorrelationRefs;
+    if (typeof rejected === "number" && Number.isSafeInteger(rejected) && rejected > 0) counts.rejectedCorrelationRefs = rejected;
+    return { kind: "refused", receiptId: null, refusal: verified.refusal, counts,
+      ...(counts.invalidTimestamps || counts.rejectedCorrelationRefs ? { diagnostics: {
+        ...(counts.invalidTimestamps ? { invalidTimestamp: true as const } : {}),
+        ...(counts.rejectedCorrelationRefs ? { rejectedCorrelationRefs: counts.rejectedCorrelationRefs } : {}),
+      } } : {}) };
+  }
+  const observation = projectObservation(verified.observation, input.approveTrackingUrl, input.observationCodecs);
+  counts.rejectedTrackingRefs = observation.diagnostics?.admission?.rejectedTrackingRefs ?? 0;
+  counts.rejectedTrackingUrls = observation.diagnostics?.admission?.rejectedTrackingUrls ?? 0;
   const inbound = await input.localPersistence.recordObservation(observation);
+  const receiptId = inbound.receiptId ?? observation.eventKey;
   const ref = await input.lifecycle.findDispatchRef(observation);
   if (!ref) {
     await input.localPersistence.markProcessed(observation.eventKey, { status: "ignored", refusal: { reason: "local_missing", phase: "apply", retryable: false } });
-    return { kind: "ignored", observation, replayed: inbound.replayed, trackingRefs: 0, trackingReadBacks: 0 };
+    return { kind: "ignored", receiptId, counts, observation, replayed: inbound.replayed, trackingRefs: 0, trackingReadBacks: 0 };
   }
   const externalRef = observation.correlation.externalRef?.trim() || ref.externalRef?.trim();
   if (!externalRef) throw new TypeError("fulfillment_dispatch_acceptance_external_ref_missing");
@@ -71,10 +101,13 @@ export async function verifyAndNormalizeFulfillmentObservation(input: {
     try { await applyFulfillmentObservationEffects(effects, observationStatusPolicy); }
     catch (error) {
       if (input.lifecycle.classifyFailure(error) !== "state_conflict") throw error;
-      await input.localPersistence.markProcessed(observation.eventKey, { status: "processed" });
-      return { kind: "superseded", observation, replayed: inbound.replayed || statusEvidence.replayed, trackingRefs, trackingReadBacks };
+      const cause = input.lifecycle.supersededCause ? input.lifecycle.supersededCause(error)
+        : error && typeof error === "object" && "reason" in error ? error.reason : null;
+      const supersededCause = safeDiagnosticCode(cause) ?? "fulfillment_state_conflict";
+      await input.localPersistence.markProcessed(observation.eventKey, { status: "processed", supersededCause });
+      return { kind: "superseded", receiptId, counts, supersededCause, observation, replayed: inbound.replayed || statusEvidence.replayed, trackingRefs, trackingReadBacks };
     }
   }
   await input.localPersistence.markProcessed(observation.eventKey, { status: "processed" });
-  return { kind: "processed", observation, replayed: inbound.replayed || statusEvidence.replayed, trackingRefs, trackingReadBacks };
+  return { kind: "processed", receiptId, counts, observation, replayed: inbound.replayed || statusEvidence.replayed, trackingRefs, trackingReadBacks };
 }

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/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,60 @@
+/** 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;
+  /** Supplied separately for execution; P8 freezes it at first claim before provider I/O. */
+  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;
+}

package/src/invoicing/contracts/host.ts

@@ -0,0 +1,85 @@
+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). P8 freezes this seller at
+   * first 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>;
+  };
+}
+/** Future service composition inputs only; no constructor, worker or runtime route
+ * is supplied in P1. 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 } 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,98 @@
+import type { InvoiceHostPorts } from "./host.js";
+import type { InvoiceFacts } 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: InvoiceFacts;
+  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.
+ * Managed and native stores are bound to the selected provider at construction.
+ * 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>;
+  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.
+   * P8 reads the injected host seller before calling the 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 } | 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 retrySeconds for backoff; native ignores it.
+   */
+  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/index.ts

@@ -0,0 +1 @@
+export { readInvoiceCapabilities } from "./capabilities.js";