@openlup/platform 0.23.0 → 0.25.0

package/src/communications/contracts/subscriptionPaymentExpired.ts

@@ -21,8 +21,9 @@ export interface SubscriptionPaymentExpiredEmailVars {
    */
   cause?: PaymentFailureCustomerCause | null;
   /**
-   * Recovery-link URL for the case's `resume_subscription` token. When present
-   * the template renders the resume CTA; when absent it keeps the support-led
+   * Recovery-link URL for the case's payment-recovery token. Current exhaustion
+   * uses `repair_payment`; legacy expired cases may carry `resume_subscription`.
+   * When present the template renders the recovery CTA; otherwise it keeps the support-led
    * wording, because a button with no destination is worse than no button.
    */
   recoveryUrl?: string | null;
@@ -51,7 +52,7 @@ export function createSubscriptionPaymentExpiredContentFactory(input: {
     const causeSentence = subscriptionPaymentCauseSentence(locale, vars.cause ?? "unknown");
     const detail = [
       // Leads the box for the same reason as in the failed notice: it answers the
-      // question the paused subscription raises, before the figures.
+      // question the unsuccessful payment raises, before the figures.
       ...(causeSentence ? [causeSentence] : []),
       ...(recoveryUrl
         ? [

package/src/communications/contracts/subscriptionPaymentFailed.ts

@@ -19,9 +19,10 @@ export interface SubscriptionPaymentFailedEmailVars {
   recoveryUrl?: string | null;
   /**
    * Pre-formatted calendar day of the scheduled next charge, in the merchant's
-   * zone (e.g. "11.08.2026"). The dunning row that selects THIS template always
-   * carries a scheduled retry, so in production this is present; null keeps the
-   * pre-date sentence rather than printing a placeholder date.
+   * zone (e.g. "11.08.2026"). Present only when a retry is actually scheduled:
+   * a first-rung hard decline selects this template with no next retry, and
+   * `retryScheduled: false` renders the no-retry copy. null/absent keeps the
+   * sentence without a date rather than printing a placeholder date.
    */
   nextRetryDateLabel?: string | null;
   /** Card scheme as stored on the method's consent snapshot, e.g. "visa". */
@@ -72,11 +73,10 @@ export function createSubscriptionPaymentFailedContentFactory(input: {
     // also why it is PREPENDED and never appended — the retry sentence must stay
     // last (see below).
     const causeSentence = subscriptionPaymentCauseSentence(locale, vars.cause ?? "unknown");
-    // Only an explicit `false` turns the promises off. Absent means "no producer
-    // told us", and the only rail that exists always schedules a retry, so absent
-    // must keep rendering today's copy rather than the safer-sounding new copy:
-    // telling a customer no attempt is coming when one is would push them to
-    // cancel a subscription that was about to recover on its own.
+    // Only an explicit `false` turns the retry promises off. Absence preserves
+    // the legacy rendering default; it does not prove a retry is scheduled.
+    // Producers must pass the actual schedule fact when retries have stopped,
+    // including class termination or exhaustion.
     const retryScheduled = vars.retryScheduled !== false;
     const detail = [
       ...(causeSentence ? [causeSentence] : []),

package/src/composition/index.ts

@@ -20,3 +20,4 @@ export { createCatalogContribution, type CatalogContributionInput } from "./cata
 export { createInventoryContribution } from "./inventoryContribution.js";
 export { createShippingContribution } from "./shippingContribution.js";
 export { createFulfillmentContribution } from "./fulfillmentContribution.js";
+export { createSubscriptionContribution } from "./subscriptionContribution.js";

package/src/composition/subscriptionContribution.ts

@@ -0,0 +1,25 @@
+import type { Contribution, RequiredSchema } from "@openlup/core/readiness";
+
+/** One selected subscription job; no second scheduler or automatic registration. */
+export function createSubscriptionContribution(input: {
+  version: string;
+  requiredSchema: RequiredSchema;
+  run: (() => Promise<unknown>) | null;
+  cadenceSeconds: number;
+}) {
+  if (!Number.isFinite(input.cadenceSeconds) || input.cadenceSeconds <= 0) throw new Error("subscription_cadence_invalid");
+  const schedules = input.run ? [{ id: "subscriptions-renewal", cadenceSeconds: input.cadenceSeconds, run: input.run }] : [];
+  const contribution: Contribution = {
+    manifest: {
+      name: "@openlup/platform", version: input.version, kind: "rail",
+      module: { id: "subscriptions", kind: "capability", provides: ["./subscriptions", "./subscriptions/contracts"], dependsOn: [] },
+      emits: [], handles: [], schedules: schedules.map(({ id, cadenceSeconds }) => ({ id, cadenceSeconds })),
+      env: [], requiredPorts: ["run"], routes: [], requiredSchema: input.requiredSchema,
+    }, handlers: [], schedules, routes: [],
+  };
+  return {
+    contributions: [contribution],
+    ports: input.run ? { "@openlup/platform/subscriptions:run": input.run } : {},
+    triggers: Object.fromEntries(schedules.map(schedule => [`@openlup/platform/subscriptions:${schedule.id}`, schedule.run])),
+  };
+}

package/src/fulfillment/contracts/dispatch.ts

@@ -44,6 +44,10 @@ export interface DispatchEvidence {
 export interface FulfillmentOperationError {
   redactedFieldCount?: number;
   code: string; status: number | null; retryable: boolean; mayHaveSucceeded: boolean;
+  /** Whether provider submission was attempted; absent means unknown, never proven false. */
+  submissionAttempted?: boolean;
+  /** Whether the HTTP response body was read, including empty or malformed JSON; absent means no body-read evidence. */
+  responseBodyRead?: boolean;
   /** Machine cause only; never an arbitrary exception message. */
   cause?: string;
 }

package/src/fulfillment/dispatchProjection.ts

@@ -24,6 +24,8 @@ export function operationError(error: Omit<FulfillmentOperationError, "cause"> &
     value => /^ack(?::[A-Za-z0-9_]{1,96}){0,2}$/u.test(value) ? value.slice(0,180) : null) : null;
   return { code, status: Number.isInteger(error.status) && error.status! >= 100 && error.status! <= 599 ? error.status : null,
     retryable: error.retryable === true, mayHaveSucceeded: error.mayHaveSucceeded === true,
+    ...(typeof error.submissionAttempted === "boolean" ? { submissionAttempted: error.submissionAttempted } : {}),
+    ...(typeof error.responseBodyRead === "boolean" ? { responseBodyRead: error.responseBodyRead } : {}),
     ...(cause ? { cause } : {}), ...(privacy.redactedFieldCount ? { redactedFieldCount: privacy.redactedFieldCount } : {}) };
 }
 // The fulfillment opaque-ID rule; never accept free-form metadata as a reference.
@@ -77,9 +79,9 @@ export function dispatchEvidence(evidence: DispatchEvidence): DispatchEvidence {
   };
 }
 /** Shadow has a local command identity; it never invokes a provider or resolves credentials. */
-export function shadowDispatchEvidence(request: FulfillmentDispatchRequest): DispatchEvidence {
+export function shadowDispatchEvidence(request: FulfillmentDispatchRequest, commandFingerprint?: string): DispatchEvidence {
   if (!request.selection.providerRef || !request.lines.length || request.lines.some(line => !Number.isSafeInteger(line.quantity) || line.quantity <= 0)) throw new Error("dispatch_shadow_command_invalid");
-  return dispatchEvidence({ commandFingerprint: createHash("sha256").update(JSON.stringify(request)).digest("hex"),
+  return dispatchEvidence({ commandFingerprint: commandFingerprint ?? createHash("sha256").update(JSON.stringify(request)).digest("hex"),
     contactRevision: request.contactRevision, providerRef: request.selection.providerRef,
     carrierRef: request.selection.carrierRef, serviceRef: request.selection.serviceRef,
     transcript: { itemCount: request.lines.length, items: request.lines.map(line => ({ skuRef: line.skuRef, quantity: line.quantity,

package/src/fulfillment/omnipack/client.ts

@@ -153,35 +153,42 @@ async function requestJson(
 
   for (let attempt = 1; attempt <= attempts; attempt += 1) {
     let submitted = false;
+    let responseBodyRead: boolean | undefined;
+    const dispatchFacts = () => operation === "createOrder" ? { submissionAttempted: submitted,
+      ...(responseBodyRead !== undefined ? { responseBodyRead } : {}) } : {};
     try {
       const base = new URL(config.baseUrl);
       const url = new URL(path, base);
       if (url.origin !== base.origin || url.username || url.password || url.protocol !== "https:") throw new Error("Invalid fulfillment path");
       const response = await fetchWithTimeout(fetchImpl, url, config, init, () => { submitted = true; });
-      if (response.ok) return await readJsonBody(response);
+      responseBodyRead = false;
+      const body = await readJsonBody(response).then(value => { responseBodyRead = true; return value; }).catch(error => {
+        if (response.ok) throw error;
+        return null;
+      });
+      if (response.ok) return body;
 
       const retryable = method === "GET" && isRetryableStatus(response.status);
       // A failed body read cannot erase the rejection status already received.
-      const body = await readJsonBody(response).catch(() => null);
-      lastError = new OmnipackProviderError({
+      lastError = Object.assign(new OmnipackProviderError({
         operation,
         status: response.status,
         code: refuseRedirectRetry && response.status >= 300 && response.status < 400 ? "redirect_refused" : readProviderErrorCode(body) ?? `http_${response.status}`,
         retryable,
         mayHaveSucceeded: mayPostHaveSucceeded(method, response.status),
-      });
+      }), dispatchFacts());
       if (!retryable || attempt === attempts) throw lastError;
     } catch (error) {
       const retryable = method === "GET" && attempt < attempts;
       lastError = submitted && error instanceof OmnipackProviderError
         ? error
-        : new OmnipackProviderError({
+        : Object.assign(new OmnipackProviderError({
           operation,
           status: null,
           code: diagnoseRedirectFailure && isRedirectRefusal(error) ? "redirect_refused" : "network_error",
           retryable,
           mayHaveSucceeded: submitted && mayPostHaveSucceeded(method, null),
-        });
+        }), dispatchFacts());
       if (!retryable || (refuseRedirectRetry && lastError.code === "redirect_refused")) throw lastError;
     }
   }

package/src/fulfillment/omnipack/index.ts

@@ -239,10 +239,13 @@ export function createOmnipackFulfillmentAdapter(config: OmnipackFulfillmentAdap
             return { kind: "refused", refusal: refusal("unsupported_event", "normalize") };
           const original = payload as Record<string, unknown>;
           // Validate calendar fields here only; keep compact offsets and local
-          // timestamps accepted by the base parser, without rewriting key bytes.
+          // timestamps and minute precision accepted by the base parser,
+          // without rewriting key bytes.
           if (original.occurredAt !== undefined && original.occurredAt !== null
             && (typeof original.occurredAt !== "string" || !timestamp(original.occurredAt)
-              || !z.iso.datetime({ offset: true, local: true }).safeParse(original.occurredAt.replace(/([+-]\d{2})(\d{2})$/u, "$1:$2")).success))
+              || !z.iso.datetime({ offset: true, local: true })
+                .or(z.iso.datetime({ offset: true, local: true, precision: -1 }))
+                .safeParse(original.occurredAt.replace(/([+-]\d{2})(\d{2})$/u, "$1:$2")).success))
             return { kind: "refused", refusal: refusal("malformed", "normalize"), diagnostics: { invalidTimestamp: true } };
           const rejectedCorrelationRefs = [original.orderId, original.providerOrderId, original.orderNumber, original.fulfilmentNumber]
             .filter(value => value !== undefined && value !== null && (typeof value !== "string" || !correlationReference(value, config.observationCodecs))).length;

package/src/fulfillment/providerDispatchWorker.ts

@@ -14,6 +14,8 @@ export async function runFulfillmentDispatchWorker(input: {
     acceptance(fulfillmentRef: string): { providerAttemptKey: string; labelKey: string };
   };
   config: { mode: DispatchRecord["mode"]; batchLimit: number };
+  /** Pure local shadow fingerprint: a lowercase 64-hex SHA-256 digest of the adopter's canonical command bytes. Invalid output or a throw refuses before evidence writes. Never return raw command/PII. Used across shadow claim/readback/attempt; shadow never begins, and live preparation must produce the same identity. */
+  shadowCommandFingerprint?: (request: FulfillmentDispatchRequest) => string;
   now?: () => Date;
 }) {
   const privacy = durableStrings();
@@ -56,8 +58,19 @@ export async function runFulfillmentDispatchWorker(input: {
       for (let remapCount = 0; ; remapCount += 1) {
         const request = { ...mappedCandidate, requestKey };
         stage = "dispatch_command_prepare_failed";
+        let shadowFingerprint: string | undefined;
+        if (input.config.mode === "shadow" && input.shadowCommandFingerprint) {
+          let value: unknown;
+          let cause: "adopter_fingerprint_invalid" | "adopter_fingerprint_failed" | undefined;
+          try { value = input.shadowCommandFingerprint(request); }
+          catch { cause = "adopter_fingerprint_failed"; }
+          if (!cause && typeof value === "string" && /^[a-f0-9]{64}$/.test(value)) shadowFingerprint = value;
+          else cause ??= "adopter_fingerprint_invalid";
+          if (cause) return { ...result, ok: false, failures: result.failures + 1, reason: cause,
+            refusal: { reason: "malformed" as const, phase: "prepare" as const, retryable: false as const, cause }, ...diagnostics() };
+        }
         const prepared = input.config.mode === "shadow"
-          ? { kind: "prepared" as const, evidence: shadowDispatchEvidence(request) }
+          ? { kind: "prepared" as const, evidence: shadowDispatchEvidence(request, shadowFingerprint) }
           : await input.provider!.prepare(request);
         if (prepared.kind === "refused") {
           result.ok = false; result.failures += 1; result.reason ??= privacy.token(prepared.refusal.reason) ?? "redacted"; continue candidateLoop;

package/src/inventory/index.ts

@@ -20,3 +20,5 @@ export { forecastSubscriptionInventoryShortages, buildSubscriptionInventoryForec
 export { calculateSubscriptionForecastSkus, calculateSubscriptionForecastTotals } from "./subscriptionForecastCalculation.js";
 export { INVENTORY_MIGRATIONS } from "./sql.js";
 export { createInventoryBindings, type InventoryBindingDependencies, type InventoryBindings } from "./bindings.js";
+export { createPostgresStockAvailability } from "./postgresStockAvailability.js";
+export type { NativeStockPromise } from "./postgresStockAvailability.js";

package/src/inventory/postgresStockAvailability.ts

@@ -0,0 +1,54 @@
+import type { NewPurchaseStockRow } from "./contracts/newPurchaseStock.js";
+import type { NewPurchaseStockReadPort } from "./newPurchaseStockAvailability.js";
+
+interface StockQueryExecutor {
+  query(text: string, values?: unknown[]): Promise<{ rows: Record<string, unknown>[] }>;
+}
+export interface NativeStockPromise {
+  availableQuantity: number; forSaleQuantity: number; hardHoldQuantity: number;
+  safetyQuantity: number; softSubscriptionDemandQuantity: number; channelExposureQuantity: number;
+}
+function object(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("inventory_stock_response_invalid");
+  return value as Record<string, unknown>;
+}
+function quantity(value: unknown): number {
+  if ((typeof value !== "number" && typeof value !== "string") || String(value).trim() === "") throw new Error("inventory_stock_quantity_invalid");
+  const n = Number(value);
+  if (!Number.isSafeInteger(n) || n < 0) throw new Error("inventory_stock_quantity_invalid");
+  return n;
+}
+/** Native read-only ATP. The fixed 14-day priority cannot be waived by a new
+ * purchase caller. Only the fenced native SQL allocator uses the renewal exemption. */
+export function createPostgresStockAvailability(executor: StockQueryExecutor, options: { sourceKey: string; now: () => string }): {
+  readPort: NewPurchaseStockReadPort;
+  availableToPromise(sku: string, asOf: string): Promise<NativeStockPromise>;
+} {
+  return {
+    async availableToPromise(sku, asOf) {
+      const row = object((await executor.query(`SELECT public.inventory_available_to_promise(
+        $1::text,$2::text,$3::timestamptz,false) AS response`, [options.sourceKey, sku, asOf])).rows[0]?.response);
+      return { availableQuantity: quantity(row.available_quantity), forSaleQuantity: quantity(row.for_sale_quantity),
+        hardHoldQuantity: quantity(row.hard_hold_quantity), safetyQuantity: quantity(row.safety_quantity),
+        softSubscriptionDemandQuantity: quantity(row.soft_subscription_demand_quantity), channelExposureQuantity: quantity(row.channel_exposure_quantity) };
+    },
+    readPort: {
+      async read(input) {
+        if (input.horizonDays !== 14 || input.excludeOrderId !== null) throw new Error("native_stock_read_options_unsupported");
+        if (!input.skus.length) return new Map();
+        const value = (await executor.query(`SELECT public.inventory_new_purchase_stock_read(
+          $1::text,$2::jsonb,$3::timestamptz) AS response`, [options.sourceKey, JSON.stringify(input.skus), options.now()])).rows[0]?.response;
+        if (!Array.isArray(value)) throw new Error("inventory_stock_response_invalid");
+        return new Map(value.map(value => {
+          const row = object(value);
+          if (typeof row.sku !== "string" || !["provider", "missing"].includes(String(row.source)) || typeof row.stale !== "boolean") throw new Error("inventory_stock_response_invalid");
+          const result: NewPurchaseStockRow = { sku: row.sku, catalogSkuId: row.catalogSkuId == null ? null : String(row.catalogSkuId),
+            source: row.source as "provider" | "missing", providerForSale: row.providerForSale == null ? null : quantity(row.providerForSale),
+            activeHolds: quantity(row.activeHolds), safetyStock: quantity(row.safetyStock), available: quantity(row.available), stale: row.stale,
+            renewalDemand: quantity(row.renewalDemand), availableForNewPurchases: quantity(row.availableForNewPurchases), excludedOrderHolds: quantity(row.excludedOrderHolds) };
+          return [result.sku, result];
+        }));
+      },
+    },
+  };
+}

package/src/invoicing/accountingCanonicalProviderLines.ts

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

package/src/invoicing/accountingLineAllocation.ts

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