@openlup/platform 0.23.0 → 0.25.0

package/README.md

@@ -1,25 +1,51 @@
 # @openlup/platform
 
+Invoicing exports explicit `createInvoiceServices`, `InvoiceServices` and inert
+`createInvoiceContribution` through `/invoicing`, with no new composition entry.
+`claimInvoiceSellerRevision` reads an injected selection before claim; the pinned
+SQL wrappers persist it for eligible obligations. `InvoiceSellerRevision` is also
+available from the type-only contracts entry. Legacy obligations keep fallback.
+
 Development preview. This package is part of the publishable set with core and outbox; preparation does not establish a registry release or a stable API. Its repository-directory publish command refuses publication; the authorized package-release workflow owns publication.
 
 It holds the runnable server substrate an OpenLup application composes: the Node HTTP runtime, BFF dispatch, scheduling and job leases, blob storage, data gateways, the node-postgres migration runner and bundle composition. Ports and their contracts stay in `@openlup/core/platform-runtime`.
 
-For the prepared `0.23.0` set, read the [adjacent-release migration and known
-limitations](CHANGELOG.md#0230) before selecting the opt-in parity seams.
-Install the complete native chain through position 76; follow the `0.22.0`
-native-row migration notes. Native delivery alignment stays off or shadow until
-a host composes its automatic-renewal runner with G23 admission.
-M10 subscription renewal/retry (P1 exports, forward controls, P2 stores/executor,
-native N1 SQL landed) and M09 invoicing selection/type-only contracts (no SQL)
-are **EXPERIMENTAL, INCOMPLETE and DEFAULT-OFF**, not for adopter activation.
-No runner is activated; G23/N1 host obligations remain pending.
+For the prepared `0.25.0` set, read the [adjacent-release migration and known
+limitations](CHANGELOG.md#0250) before selecting optional services.
+Install the complete native chain through position 86, including N2 commands,
+N3 stock wait, the ATP seam/allocator and late-payment/retry-selection forwards;
+sparse SQL projections are not an install chain. Native runtime roles need the
+ATP/exposure EXECUTE and underlying SELECT grants described in the release notes.
+Managed hosts apply the complete prefix through `20261024185100` for stock-wait
+and refund-evidence functions. Preserve captured obligations and receipts on rollback.
+M10 subscription services and contributions remain **EXPERIMENTAL and DEFAULT-OFF**.
+Hosts explicitly supply readiness, execution, commands, mandatory G23 admission,
+a population lease and M04 delivery. Factories activate no serving work. The inert
+native reference composes renewal, dunning and stock wait; managed TypeScript
+stock recovery, native multi-cycle prepaid and M07 prepared-attempt-store
+capabilities retain their named unsupported boundaries. Follow the older native-row
+migration precautions when upgrading `0.22.0` data.
+M09 invoicing remains **EXPERIMENTAL and DEFAULT-OFF**, available for explicit
+provider/capability selection and ready host composition, including issue,
+correction, independent duties, delivery/read-side and seller revision helpers.
+Adopters must not activate unselected or unready invoicing; installation and
+inert contributions register no runner, worker, route or schedule.
 M06 managed-host proof classes remain pending in the
 [M06 parity ledger](../../docs/platform/plans/oss-m06-stock-reservations-delivery.md#parity-pending-rows).
-Size comparison uses the published `0.22.0` tarball. Preparation and offline
+Size comparison uses the published `0.24.0` tarball. Preparation and offline
 adapter evidence grant no publication or provider-account certification.
 
 Longer module recipes live in the [platform package reference](../../docs/platform/PLATFORM_PACKAGE_REFERENCE.md).
 
+The prepared set requires Zod `^4.6.6` for GHSA-mrhx-c7xc-m3w5.
+Public quote requests retain their collection limits and valid-input behavior;
+oversized collections now fail with the size error before accumulating invalid
+element errors. Package API and installed-consumer checks remain required.
+The observation adapter explicitly retains minute-precision timestamps
+alongside seconds/fractions, compact offsets and local timestamps. Calendar
+validation still rejects impossible dates; validation never rewrites the raw
+timestamp used in the webhook's idempotency key.
+
 ## Package surface
 
 `release-gates.json` declares kind `rail`: this foundation provides runtime infrastructure over core ports, matching the architecture's rail responsibility. Its experimental entries each bind a declaration snapshot and package-owned smoke tests. The API checker reads this same inventory.
@@ -45,7 +71,7 @@ Longer module recipes live in the [platform package reference](../../docs/platfo
 | `./payments` | Experimental prepared-attempt ordering with injected persistence, execution and failure policy; contracts at `./payments/contracts`. |
 | `./fulfillment`, `./fulfillment/contracts` | [Experimental fulfillment services, contracts and status canon](../../docs/platform/ARCHITECTURE_AND_EXTENSIONS.md#fulfillment-contracts). |
 | `./subscriptions`, `./subscriptions/contracts` | Default-off, incomplete; [experimental subscription contracts and renewal port](../../docs/platform/ARCHITECTURE_AND_EXTENSIONS.md#subscription-contracts). |
-| `./invoicing`, `./invoicing/contracts` | Default-off, incomplete invoicing selection and type-only contracts; no SQL or activation. |
+| `./invoicing`, `./invoicing/contracts` | Default-off invoicing contracts and independent duty collection; no provider activation. |
 | `./inventory` | Experimental schemas/ports, handlers, native stores, projection, injected forecast and SQL descriptor; `./inventory/contracts` DTOs. |
 | `./catalog` | Experimental neutral catalog schemas, drafts, reads, media source packs and publication ports |
 | `./catalog/contracts` | Dependency-free catalog DTOs, media resolver, authority and canonicalization helpers |
@@ -703,6 +729,30 @@ The initial binding preserves case-before-outcome ordering with atomic bookkeepi
 N1's same-obligation recovery repairs the native decline stall (F16); it does not
 supply M07 prepared-store parity or activate a runner.
 
+With N1 then N2 installed, `createPostgresSubscriptionCommandStore` and
+`createPostgresSubscriptionCommands` support native generic bundle commands and
+command-bound receipts. Preview persists a quote; apply atomically updates future
+terms, event and receipt with no proration or current-cycle repricing. Hosts own
+authorization, address validation, SKU/composition translation and the transaction
+connection. Prepaid remains unsupported; the serving adapter refuses pause.
+
+Native N3 plus the ATP seam/allocator and X/Y suffix provide
+`createPostgresStockWaitStore` and `createPostgresStockAvailability` (the latter
+at `./inventory`). Hosts supply transactions, clock, source and the existing
+wire codec. Candidate discovery preserves uncaptured frozen operations; shortage
+creates a durable wait, and elapsed stock-only refusals may reacquire on the same
+identity with a new claim generation. Resumed means paid realization admitted.
+The fixed 14-day soft priority is distinct from durable advance reservations.
+The unbound descriptor keeps stock recovery unavailable. The opt-in native M10
+reference composition selects it after composed PostgreSQL proof; managed
+TypeScript recovery remains unavailable.
+
+`createSubscriptionServices`, lifecycle-message and neutral command facades are
+in `./subscriptions`; `createSubscriptionContribution` is in `./composition`.
+They are default-off and describe one host executor/job. The
+[composed module recipe](../../docs/platform/ARCHITECTURE_AND_EXTENSIONS.md#composed-subscription-module)
+owns explicit selection, frozen mandate/replay, M04 delivery and M12 boundaries.
+
 ## Invoicing contracts
 
 Experimental `@openlup/platform/invoicing` exposes `readInvoiceCapabilities`;
@@ -710,4 +760,65 @@ Experimental `@openlup/platform/invoicing` exposes `readInvoiceCapabilities`;
 Frozen facts, correction recovery, exact absence, owed duties and host-only fiscal,
 artifact, delivery, payout and owned-history seams are described in the
 [invoicing reference](../../docs/platform/PLATFORM_PACKAGE_REFERENCE.md#invoicing-contracts).
-No store, worker, adapter, route or activation is supplied by this contract step.
+The contract entry supplies no executor or activation.
+`createNativeUnsupportedInvoicePorts` supplies inert typed refusals for every
+host, store and provider seam. `runInvoiceAdapterConformance` checks adapter-owned
+offline fixtures; its sanitized evidence does not establish live fiscal readiness.
+
+Issue helpers in `invoicing` preserve claim/preflight/projection/fresh-money/
+create/fenced-finalize order. Hosts bind compatibility payloads, seller/date/tax
+policy, captions, event descriptors and key scopes. Canonical and legacy line
+checks share the unchanged donor allocation; handoff helpers register no job or
+executor. Eight issue/line/payment/handoff cases join the existing package smoke
+selection. Continuity cutover and activation remain separate.
+
+Correction and reversal workers preserve durable identity, recovery and fenced
+outcomes through host callbacks. The reference host requires a conforming
+correction bridge; the legacy vendor method stays unselected. Reversal handlers pass
+through the RPC action (`voided`, `correction_requested`, `corrected`, `no_invoice`). The required package
+selection includes correction/reversal witnesses in `test/invoicing/contracts.test.ts`.
+See the [invoicing design](../../docs/platform/plans/oss-m09-invoicing.md#p3-correction-and-reversal-boundary)
+for managed migration and reconciliation limits.
+
+See the [M09 forward owner](../../docs/platform/DATA_AND_MIGRATIONS.md#m09-invoicing-forward-design-and-control-approval) for the registered managed-correction limit and follow-up.
+
+`createPostgresInvoiceStore` uses a caller-owned structural executor for native
+owed duties, split fact leases, claims and fenced issue/correction results.
+Missing host facts refuse before writes; clearance remains host work. Delivery
+requires an explicit host envelope projection and M04 transport. `INVOICING_MIGRATIONS` separates native child-document and managed
+base-row correction storage. Install the complete native catalogue, not its
+seven sparse byte-identical SQL assets. The local-only Postgres adapter consumes
+this store without claiming fiscal parity or registering a worker. The
+[invoicing architecture owner](../../docs/platform/ARCHITECTURE_AND_EXTENSIONS.md#invoicing-contracts)
+describes reversal recovery, capture faults and cutover fencing.
+`collectInvoiceDuties` and `createIndependentInvoiceDutyBinding` collect retained
+paid/handoff duties through separately committed store phases. Hosts invoke them
+outside payment and fulfillment work; missing facts remain owed. The pinned
+payment-decoupling SQL is a sparse catalogue projection, requiring the full P4
+native chain. See the architecture owner for continuity and activation limits.
+
+`runNativeInvoiceIssueJob` supplies the native create/readback binding over
+explicit local/fresh money and provider ports. Fresh non-ready results settle
+before returning; stale results write no failure. No scheduler or default
+composition is registered. Operator DDL/ACL limits of the unchanged M07 readback
+remain registered in the architecture owner.
+
+For bounded duty discovery before facts exist, including cursor continuation past
+unavailable facts, follow the [invoicing architecture owner](../../docs/platform/ARCHITECTURE_AND_EXTENSIONS.md#invoicing-contracts).
+
+The invoicing read side adds `runInvoiceDeliveryJob`, `assertInvoicePdf`,
+`invoicePdfFilename`, `syncAcceptedInvoiceDocuments`,
+`syncInvoicePayoutSettlements`, `resolveInvoiceDocumentHistory` and
+`createInvoiceReadModel`. Hosts supply authorization, storage, M04 transport,
+terminal/backoff callbacks or the native store, and safe native history projection. See the
+[read-helper recipe](../../docs/platform/PLATFORM_PACKAGE_REFERENCE.md#invoicing-read-helpers).
+
+`createInvoiceServices` and `createInvoiceContribution` compose the existing
+helpers through `/invoicing`, with explicit selection, default-off and readiness
+before execution. Native collection, issue, delivery, document/payout sync and
+history use their module implementations; host facades may bind factories where
+transport or query projection is host-owned. No executor is installed.
+`claimInvoiceSellerRevision` selects a seller before leasing. The optional native
+store seller binding and managed wrappers persist its first-ever claim revision;
+legacy fallback and forward-only migration limits are owned by the
+[M09 migration section](../../docs/platform/DATA_AND_MIGRATIONS.md#m09-invoicing-forward-design-and-control-approval).

package/dist/communications/contracts/subscriptionPaymentExpired.d.ts

@@ -14,8 +14,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;

package/dist/communications/contracts/subscriptionPaymentExpired.js

@@ -8,7 +8,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/dist/communications/contracts/subscriptionPaymentFailed.d.ts

@@ -12,9 +12,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". */

package/dist/communications/contracts/subscriptionPaymentFailed.js

@@ -14,11 +14,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/dist/composition/index.d.ts

@@ -5,3 +5,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/dist/composition/index.js

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

package/dist/composition/subscriptionContribution.d.ts

@@ -0,0 +1,18 @@
+import type { Contribution, RequiredSchema } from "@openlup/core/readiness";
+/** One selected subscription job; no second scheduler or automatic registration. */
+export declare function createSubscriptionContribution(input: {
+    version: string;
+    requiredSchema: RequiredSchema;
+    run: (() => Promise<unknown>) | null;
+    cadenceSeconds: number;
+}): {
+    contributions: Contribution[];
+    ports: {
+        "@openlup/platform/subscriptions:run": () => Promise<unknown>;
+    } | {
+        "@openlup/platform/subscriptions:run"?: undefined;
+    };
+    triggers: {
+        [k: string]: () => Promise<unknown>;
+    };
+};

package/dist/composition/subscriptionContribution.js

@@ -0,0 +1,19 @@
+/** One selected subscription job; no second scheduler or automatic registration. */
+export function createSubscriptionContribution(input) {
+    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 = {
+        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/dist/fulfillment/contracts/dispatch.d.ts

@@ -90,6 +90,10 @@ export interface FulfillmentOperationError {
     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/dist/fulfillment/dispatchProjection.d.ts

@@ -19,7 +19,7 @@ export declare function durableStrings(priorCount?: number): {
 /** Copy only the durable allowlist, including when an adapter object has extra runtime properties. */
 export declare function dispatchEvidence(evidence: DispatchEvidence): DispatchEvidence;
 /** Shadow has a local command identity; it never invokes a provider or resolves credentials. */
-export declare function shadowDispatchEvidence(request: FulfillmentDispatchRequest): DispatchEvidence;
+export declare function shadowDispatchEvidence(request: FulfillmentDispatchRequest, commandFingerprint?: string): DispatchEvidence;
 export declare function dispatchResult(result: FulfillmentDispatchResult): FulfillmentDispatchResult;
 export declare function acceptedProviderProof(record: DispatchRecord | null): record is DispatchRecord & {
     externalRef: string;

package/dist/fulfillment/dispatchProjection.js

@@ -22,6 +22,8 @@ export function operationError(error) {
     const cause = typeof error.cause === "string" ? privacy.token(error.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.
@@ -78,10 +80,10 @@ export function dispatchEvidence(evidence) {
     };
 }
 /** Shadow has a local command identity; it never invokes a provider or resolves credentials. */
-export function shadowDispatchEvidence(request) {
+export function shadowDispatchEvidence(request, commandFingerprint) {
     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/dist/fulfillment/omnipack/client.js

@@ -58,24 +58,32 @@ async function requestJson(fetchImpl, config, operation, path, init, refuseRedir
     let lastError = null;
     for (let attempt = 1; attempt <= attempts; attempt += 1) {
         let submitted = false;
+        let responseBodyRead;
+        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; });
+            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 await readJsonBody(response);
+                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;
         }
@@ -83,13 +91,13 @@ async function requestJson(fetchImpl, config, operation, path, init, refuseRedir
             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/dist/fulfillment/omnipack/index.js

@@ -242,10 +242,13 @@ export function createOmnipackFulfillmentAdapter(config) {
                         return { kind: "refused", refusal: refusal("unsupported_event", "normalize") };
                     const original = payload;
                     // 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/dist/fulfillment/providerDispatchWorker.d.ts

@@ -16,8 +16,46 @@ export declare function runFulfillmentDispatchWorker(input: {
         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;
 }): Promise<{
+    redactedFieldCount: number;
+    ok: boolean;
+    failures: number;
+    reason: "adopter_fingerprint_invalid" | "adopter_fingerprint_failed";
+    refusal: {
+        reason: "malformed";
+        phase: "prepare";
+        retryable: false;
+        cause: "adopter_fingerprint_invalid" | "adopter_fingerprint_failed";
+    };
+    skipped: boolean;
+    checked: number;
+    updated: number;
+    mode: "shadow" | "stage" | "live";
+    replayed: number;
+    providerCalls: number;
+    readBacks: number;
+} | {
+    redactedFieldCount?: undefined;
+    ok: boolean;
+    failures: number;
+    reason: "adopter_fingerprint_invalid" | "adopter_fingerprint_failed";
+    refusal: {
+        reason: "malformed";
+        phase: "prepare";
+        retryable: false;
+        cause: "adopter_fingerprint_invalid" | "adopter_fingerprint_failed";
+    };
+    skipped: boolean;
+    checked: number;
+    updated: number;
+    mode: "shadow" | "stage" | "live";
+    replayed: number;
+    providerCalls: number;
+    readBacks: number;
+} | {
     redactedFieldCount: number;
     ok: boolean;
     skipped: boolean;

package/dist/fulfillment/providerDispatchWorker.js

@@ -53,8 +53,26 @@ export async function runFulfillmentDispatchWorker(input) {
             for (let remapCount = 0;; remapCount += 1) {
                 const request = { ...mappedCandidate, requestKey };
                 stage = "dispatch_command_prepare_failed";
+                let shadowFingerprint;
+                if (input.config.mode === "shadow" && input.shadowCommandFingerprint) {
+                    let value;
+                    let cause;
+                    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", phase: "prepare", retryable: false, cause }, ...diagnostics() };
+                }
                 const prepared = input.config.mode === "shadow"
-                    ? { kind: "prepared", evidence: shadowDispatchEvidence(request) }
+                    ? { kind: "prepared", evidence: shadowDispatchEvidence(request, shadowFingerprint) }
                     : await input.provider.prepare(request);
                 if (prepared.kind === "refused") {
                     result.ok = false;

package/dist/inventory/index.d.ts

@@ -12,3 +12,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/dist/inventory/index.js

@@ -9,3 +9,4 @@ export { forecastSubscriptionInventoryShortages, buildSubscriptionInventoryForec
 export { calculateSubscriptionForecastSkus, calculateSubscriptionForecastTotals } from "./subscriptionForecastCalculation.js";
 export { INVENTORY_MIGRATIONS } from "./sql.js";
 export { createInventoryBindings } from "./bindings.js";
+export { createPostgresStockAvailability } from "./postgresStockAvailability.js";

package/dist/inventory/postgresStockAvailability.d.ts

@@ -0,0 +1,24 @@
+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;
+}
+/** 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 declare function createPostgresStockAvailability(executor: StockQueryExecutor, options: {
+    sourceKey: string;
+    now: () => string;
+}): {
+    readPort: NewPurchaseStockReadPort;
+    availableToPromise(sku: string, asOf: string): Promise<NativeStockPromise>;
+};
+export {};

package/dist/inventory/postgresStockAvailability.js

@@ -0,0 +1,48 @@
+function object(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("inventory_stock_response_invalid");
+    return value;
+}
+function quantity(value) {
+    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, options) {
+    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 = { sku: row.sku, catalogSkuId: row.catalogSkuId == null ? null : String(row.catalogSkuId),
+                        source: row.source, 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/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;
+}>;