@openlup/platform 0.22.0 → 0.24.0

package/dist/fulfillment/verifiedIngress.d.ts

@@ -1,4 +1,4 @@
-import type { FulfillmentObservation, FulfillmentObservationPort, FulfillmentRefusal } from "./contracts/index.js";
+import type { FulfillmentObservation, FulfillmentObservationCodecs, FulfillmentObservationPort, FulfillmentRefusal } from "./contracts/index.js";
 import { applyFulfillmentObservationEffects } from "./fulfillmentObservationEffects.js";
 type EffectInput = Parameters<typeof applyFulfillmentObservationEffects<FulfillmentObservation["fact"]["canonicalStatus"], "in_transit" | "delivered">>[0];
 type DispatchRef = {
@@ -7,20 +7,54 @@ type DispatchRef = {
     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 declare function fulfillmentIngressHttpResult(result: FulfillmentIngressResult): {
+    status: 200 | 400 | 403 | 503;
+    messageClass: "accepted" | "bad_request" | "forbidden" | "upstream_unavailable";
+};
 /** Adapter verification owns auth-before-parse; the host owns durable replay. */
 export declare 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;
+            receiptId?: string;
         }>;
         /** Idempotent; only called after completion or a classified superseding conflict. */
         markProcessed(eventKey: string, outcome: {
             status: "processed" | "ignored";
             refusal?: FulfillmentRefusal;
+            supersededCause?: string;
         }): Promise<void>;
     };
     lifecycle: {
@@ -36,17 +70,10 @@ export declare function verifyAndNormalizeFulfillmentObservation(input: {
             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;
-}>;
+}): Promise<FulfillmentIngressResult>;
 export {};

package/dist/fulfillment/verifiedIngress.js

@@ -1,19 +1,44 @@
+import { safeDiagnosticCode } from "./dispatchProjection.js";
 import { applyFulfillmentObservationEffects } from "./fulfillmentObservationEffects.js";
 import { observationStatusPolicy, projectObservation } from "./observationProjection.js";
 import { uniqueTrackingReferences } from "./providerTrackingReferences.js";
+/** Safe response classes only; the host owns HTTP and localized message text. */
+export function fulfillmentIngressHttpResult(result) {
+    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) {
+    const counts = { invalidTimestamps: 0, rejectedCorrelationRefs: 0, rejectedTrackingRefs: 0, rejectedTrackingUrls: 0 };
     if (!input.enabled)
-        return { kind: "refused", refusal: { reason: "disabled", phase: "verify", retryable: false } };
+        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 } : {}),
+                    ...(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)
@@ -57,10 +82,13 @@ export async function verifyAndNormalizeFulfillmentObservation(input) {
         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/dist/invoicing/accountingCanonicalProviderLines.d.ts

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

package/dist/invoicing/accountingCanonicalProviderLines.js

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

package/dist/invoicing/accountingLineAllocation.d.ts

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

package/dist/invoicing/accountingLineAllocation.js

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

package/dist/invoicing/adapterConformance.d.ts

@@ -0,0 +1,42 @@
+import type { InvoiceCapabilities, InvoiceIdentity, InvoiceWriteResult, InvoiceReadbackResult, InvoiceArtifactResult, InvoiceHostPorts, InvoiceServicesOptions } from "./contracts/index.js";
+type Provider = NonNullable<InvoiceServicesOptions["provider"]>;
+type Fixture<Input, Result> = {
+    readonly input: Input;
+    readonly expected: Result;
+};
+interface Subject {
+    readonly subjectId: string;
+    readonly capability: InvoiceCapabilities;
+    readonly provider: Provider;
+    readonly host?: InvoiceHostPorts;
+    /** Adapter-owned offline fixtures; count writes across every injected transport. */
+    readonly readWriteCount: () => number;
+    readonly sensitiveValues: readonly string[];
+    readonly fixtures: {
+        readonly issue: readonly (Fixture<Parameters<Provider["issue"]>[0], InvoiceWriteResult> & {
+            readonly replay?: boolean;
+        })[];
+        readonly correction: readonly (Fixture<Parameters<Provider["correct"]>[0], InvoiceWriteResult> & {
+            readonly replay?: boolean;
+        })[];
+        readonly readback: readonly Fixture<InvoiceIdentity, InvoiceReadbackResult>[];
+        readonly void: readonly Fixture<Parameters<Provider["void"]>[0], Awaited<ReturnType<Provider["void"]>>>[];
+        readonly artifact?: readonly Fixture<Parameters<InvoiceHostPorts["artifacts"]["read"]>[0], InvoiceArtifactResult>[];
+        readonly clearance?: readonly Fixture<Parameters<InvoiceHostPorts["clearance"]["observe"]>[0], Awaited<ReturnType<InvoiceHostPorts["clearance"]["observe"]>>>[];
+        readonly settlement?: readonly Fixture<Parameters<InvoiceHostPorts["settlement"]["record"]>[0], Awaited<ReturnType<InvoiceHostPorts["settlement"]["record"]>>>[];
+        readonly companyLookup?: readonly Fixture<Parameters<InvoiceHostPorts["registry"]["lookup"]>[0], Awaited<ReturnType<InvoiceHostPorts["registry"]["lookup"]>>>[];
+    };
+}
+/** @consumer Offline provider bridge tests and installed cold consumer. Runner-
+ * agnostic contract evidence only; adapters own fixtures, transport and I/O counts.
+ * Throws closed failure codes. It neither certifies live fiscal readiness nor logs
+ * provider results, secrets, buyer facts or raw adapter errors.
+ */
+export declare function runInvoiceAdapterConformance(subjects: readonly Subject[]): Promise<{
+    readonly subjects: readonly {
+        readonly subjectId: string;
+        readonly providerRef: string;
+        readonly cases: readonly string[];
+    }[];
+}>;
+export {};