@openlup/platform 0.24.0 → 0.26.0

package/README.md

@@ -10,16 +10,27 @@ Development preview. This package is part of the publishable set with core and o
 
 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.24.0` set, read the [adjacent-release migration and known
-limitations](CHANGELOG.md#0240) before selecting optional services.
-Install the complete native chain through position 80, including invoicing
-positions 77–79 and the first-claim seller revision forward; sparse SQL projections
-are not an install chain. Keep the older native-row migration precautions in the
-release notes when upgrading `0.22.0` data. 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) remains **EXPERIMENTAL, INCOMPLETE and DEFAULT-OFF**, not for
-adopter activation; G23/N1 host obligations remain pending.
+For the prepared `0.26.0` set, read the [adjacent-release migration and known
+limitations](CHANGELOG.md#0260) 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 `20261025090100` for attributed
+dunning attempt replay. `openDunningCase` requires nullable
+`failedPaymentAttemptId`; pass the durable applied attempt through renewal failure
+propagation, including replay. Fresh missing attribution refuses; never substitute
+a current or prepared attempt. Read the migration notes for the new overloads
+and existing donor schema/backfill mapping. Native attempt-replay parity remains
+registered and these managed forwards authorize no host activation.
+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.
@@ -27,7 +38,7 @@ 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.23.0` tarball. Preparation and offline
+Size comparison uses the published `0.25.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).
@@ -724,6 +735,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`;

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/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/subscriptions/commandExamples.d.ts

@@ -0,0 +1,6 @@
+import type { SubscriptionCommandContext, SubscriptionCommandPort } from "./contracts/commands.js";
+/** Neutral examples. The host authenticates and authorizes actor/client ownership first. */
+export declare function createSubscriptionCommandExamples(commands: SubscriptionCommandPort): {
+    customerSkip(context: SubscriptionCommandContext): Promise<import("./contracts/commands.js").SubscriptionCommandReceipt | import("./contracts/commands.js").SubscriptionCommandRefusal | import("./contracts/commands.js").SubscriptionUnsupported>;
+    operatorSlide(context: SubscriptionCommandContext, newNextCycleAt: string): Promise<import("./contracts/commands.js").SubscriptionCommandReceipt | import("./contracts/commands.js").SubscriptionCommandRefusal | import("./contracts/commands.js").SubscriptionUnsupported>;
+};

package/dist/subscriptions/commandExamples.js

@@ -0,0 +1,20 @@
+/** Neutral examples. The host authenticates and authorizes actor/client ownership first. */
+export function createSubscriptionCommandExamples(commands) {
+    const apply = (context, command) => {
+        if (context.actor.actorId.trim() === "" || context.actor.clientId.trim() === "")
+            throw new Error("subscription_command_actor_required");
+        return commands.apply(command);
+    };
+    return {
+        customerSkip(context) {
+            if (context.actor.kind !== "customer")
+                throw new Error("subscription_command_customer_required");
+            return apply(context, { ...context, action: "skip", reason: null, confirmedChargeTiming: true });
+        },
+        operatorSlide(context, newNextCycleAt) {
+            if (context.actor.kind !== "operator")
+                throw new Error("subscription_command_operator_required");
+            return apply(context, { ...context, action: "slide", newNextCycleAt, confirmedChargeTiming: true });
+        },
+    };
+}

package/dist/subscriptions/contracts/commands.d.ts

@@ -28,6 +28,7 @@ export type SubscriptionCommand = SubscriptionCommandContext & ({
     planDays: number;
     cadenceDays: number;
     expectedTemplateVersion: number;
+    /** Empty string means no quote (semantic no-op). */
     acceptedQuoteHash: string;
     confirmedChargeTiming: boolean;
     coreLines: readonly SubscriptionBundleLine[];
@@ -49,6 +50,12 @@ export interface SubscriptionCommandReceipt {
     revision: string;
     eventId: string | null;
 }
+export interface SubscriptionCommandRefusal {
+    outcome: "refused";
+    /** Stable machine code; never provider, PostgreSQL diagnostic or customer text.
+     * Unrecognized native or host diagnostics map to subscription_command_invalid_input. */
+    reason: "multi_cycle_prepaid_unsupported" | "subscription_command_addon_not_found" | "subscription_command_bundle_total_mismatch" | "subscription_command_charge_timing_not_confirmed" | "subscription_command_idempotency_conflict" | "subscription_command_invalid_composition_constraint" | "subscription_command_invalid_input" | "subscription_command_not_active" | "subscription_command_operation_busy" | "subscription_command_pause_forbidden" | "subscription_command_payment_blocked" | "subscription_command_preview_unsupported" | "subscription_command_renewal_terms_missing" | "subscription_command_unsupported_action" | "subscription_edit_catalog_unavailable" | "subscription_edit_invalid_lines" | "subscription_edit_invalid_request" | "subscription_edit_quote_expired" | "subscription_edit_quote_required" | "subscription_edit_stale_template" | "subscription_edit_window_closed" | "subscription_lifecycle_invalid_transition" | "subscription_lifecycle_invalid_skip" | "subscription_lifecycle_invalid_slide" | "subscription_lifecycle_payment_blocked";
+}
 export type SubscriptionUnsupportedCode = "multi_cycle_prepaid_unsupported" | "native_generic_bundle_commands_unsupported" | "native_command_bound_receipts_unsupported" | "native_prepared_attempt_store_unsupported";
 export interface SubscriptionUnsupported {
     supported: false;
@@ -88,7 +95,7 @@ export interface SubscriptionCapabilities {
 export interface SubscriptionCommandPort {
     readonly capabilities: SubscriptionCapabilities;
     /** Future term writes, actor/command receipt and events must commit atomically. */
-    apply(command: SubscriptionCommand): Promise<SubscriptionCommandReceipt | SubscriptionUnsupported>;
+    apply(command: SubscriptionCommand): Promise<SubscriptionCommandReceipt | SubscriptionCommandRefusal | SubscriptionUnsupported>;
 }
 export interface SubscriptionActivationPort {
     activate(input: {

package/dist/subscriptions/contracts/index.d.ts

@@ -1,6 +1,6 @@
 export type { RenewalSchedule, RenewalIdentity, RenewalAdmission, RenewalLine, RenewalCycleCorrelation, RenewalTemplateSnapshot, RenewalPricingSnapshot, RenewalOrderSnapshot, RenewalFrozenSnapshot, RenewalDue, RenewalOperationState, RenewalReadback, RenewalPaymentEvidence, RenewalTransactionUnits, RenewalReservationResult, RenewalPreparedSettlement, RenewalStorePort, RenewalSettlementPort, RenewalExecutionRequest, RenewalPaymentRail, RenewalResult } from "./renewal.js";
 export type { DunningCaseOpenInput, DunningCaseOpened, DunningCaseAdvanced, DunningRefusalCode, DunningCaseLifecyclePort, RenewalRetryState, RenewalRetryObligation, RenewalRecoveryAuthorization, RenewalFailureHandoffPort } from "./dunning.js";
-export type { StockWaitRecoveryBinding, StockWaitDeficit, StockWaitCase, StockWaitStorePort } from "./stockWait.js";
-export type { SubscriptionCommandContext, SubscriptionCommand, SubscriptionBundleLine, SubscriptionCommandReceipt, SubscriptionUnsupportedCode, SubscriptionUnsupported, SubscriptionCapabilities, SubscriptionCommandPort, SubscriptionActivationPort } from "./commands.js";
+export type { StockWaitRecoveryBinding, StockWaitDeficit, StockWaitCase, StockWaitFrozenCase, StockWaitStorePort } from "./stockWait.js";
+export type { SubscriptionCommandContext, SubscriptionCommand, SubscriptionBundleLine, SubscriptionCommandReceipt, SubscriptionCommandRefusal, SubscriptionUnsupportedCode, SubscriptionUnsupported, SubscriptionCapabilities, SubscriptionCommandPort, SubscriptionActivationPort } from "./commands.js";
 export type { SubscriptionLifecycleFact, SubscriptionLifecycleMessageDescriptor, SubscriptionLifecycleMessagePort } from "./messages.js";
 export type { SubscriptionRenewalOutcome, HostedRenewalDue, SubscriptionRenewalChargeResult, SubscriptionCycleSnapshotResult, SubscriptionCycleOrderInput, SubscriptionCycleOrderResult, SubscriptionReservationPreflightResult, SubscriptionRenewalPersistencePort, FailurePropagationKind, FailurePropagationContext, CycleRetryState, DunningCaseOpenOutcome, CycleChargeFailurePropagationPort, FailurePropagationResult, RenewalPrepareInput, RenewalAttemptResult, RenewalIntentResult, RenewalPaymentPort, RenewalExecutionPort, RenewalDeliveryAdmission, RenewalAllowedAdmission, RenewalDeliveryClient, RenewalFailureDeps, RenewalPreflightDeps, RenewalCycleDeps, RenewalExecutionContext, RenewalOutcomeContext, RenewalReplayContext, RenewalPreparedAttemptPrepareInput, RenewalPreparedAttemptPersistenceResult, RenewalPreparedAttemptFinalizeInput, RenewalPreparedAttemptPersistencePort } from "./renewal.js";

package/dist/subscriptions/contracts/renewal.d.ts

@@ -129,9 +129,11 @@ export interface CycleChargeFailurePropagationPort {
         };
     }): Promise<{
         replayed: boolean;
+        paymentAttemptId?: string | null;
     }>;
     readCycleRetryState(cycleId: string): Promise<CycleRetryState>;
     openDunningCase(input: {
+        failedPaymentAttemptId: string | null;
         idempotencyKey: string;
         cycleId: string;
         subscriptionId: string;

package/dist/subscriptions/contracts/stockWait.d.ts

@@ -12,8 +12,11 @@ export interface StockWaitDeficit {
     displayName: string;
     size: string | null;
     required: number;
+    /** This operation's own reserved units. */
     reserved: number;
+    /** Free ATP, excluding this operation's own reservation. */
     available: number;
+    /** Required units minus both reserved and available units. */
     missing: number;
 }
 export interface StockWaitCase extends RenewalSchedule {
@@ -36,6 +39,14 @@ export interface StockWaitCase extends RenewalSchedule {
     resumedNoticeKey: string;
     noticeEligible: boolean;
 }
+/** Discovery can precede the durable waiting case; never invent a case ID. */
+export interface StockWaitFrozenCase extends RenewalSchedule {
+    operationId: string;
+    case: StockWaitCase | null;
+    frozenSnapshot: RenewalFrozenSnapshot;
+    frozenFingerprint: string;
+    binding: StockWaitRecoveryBinding;
+}
 /** All-line reserve/reacquire and the wait transition share a DB transaction.
  * A shortage rolls back the subtransaction, retaining previous commitments;
  * record the wait outside that failed subtransaction. Technical failure is unknown.
@@ -44,7 +55,7 @@ export interface StockWaitStorePort {
     listCandidates(input: {
         limit: number;
         asOf: string;
-    }): Promise<StockWaitCase[]>;
+    }): Promise<StockWaitFrozenCase[]>;
     readFrozenCase(input: StockWaitRecoveryBinding): Promise<StockWaitCase | null>;
     reserveAndTransition(input: {
         caseId: string;

package/dist/subscriptions/index.d.ts

@@ -6,12 +6,10 @@ export declare const NATIVE_SUBSCRIPTION_CAPABILITIES: Readonly<{
         refusalCode: "multi_cycle_prepaid_unsupported";
     }>;
     readonly genericBundleCommands: Readonly<{
-        supported: false;
-        refusalCode: "native_generic_bundle_commands_unsupported";
+        supported: true;
     }>;
     readonly commandBoundReceipts: Readonly<{
-        supported: false;
-        refusalCode: "native_command_bound_receipts_unsupported";
+        supported: true;
     }>;
     readonly preparedAttemptStore: Readonly<{
         supported: false;
@@ -37,3 +35,23 @@ export { createPostgresRetryStore } from "./postgresRetryStore.js";
 export type { NativeRetryFailure, NativeRetryRequest, NativeRetryPositive, NativeRetryPreparation, NativeRetryRow } from "./postgresRetryStore.js";
 export { createPostgresRetryLifecycleBinding } from "./postgresRetryStore.js";
 export type { NativeRetryLifecycleBinding } from "./postgresRetryStore.js";
+export { createPostgresSubscriptionCommandStore, createPostgresSubscriptionCommands } from "./postgresCommandStore.js";
+export type { NativeSubscriptionCommand, NativeSubscriptionCommandBinding } from "./postgresCommandStore.js";
+export { createPostgresStockWaitStore } from "./postgresStockWaitStore.js";
+export type { NativeStockWaitBinding, NativeStockWaitAdmission } from "./postgresStockWaitStore.js";
+/** Managed SQL is exposed for service-role hosts; no StockWaitStorePort or
+ * NewPurchaseStockReadPort TypeScript adapter is composed for this graph.
+ * SQL behavior is proved by the managed pgTAP/real-PostgreSQL witnesses.
+ */
+export declare const MANAGED_SUBSCRIPTION_STOCK_CAPABILITIES: Readonly<{
+    readonly graph: "managed";
+    readonly stockRecovery: "unavailable";
+    readonly stockWaitSurface: "sql";
+    readonly stockAvailabilitySurface: "sql";
+    readonly defaultEnabled: false;
+}>;
+export { runRenewalBatchRows } from "./automaticRenewalExecution.js";
+export type { SubscriptionLifecycleFact } from "./contracts/messages.js";
+export { subscriptionLifecycleTemplate, createSubscriptionLifecycleMessages } from "./lifecycleMessages.js";
+export { createSubscriptionCommandExamples } from "./commandExamples.js";
+export { createSubscriptionServices } from "./services.js";

package/dist/subscriptions/index.js

@@ -2,10 +2,12 @@ export { renewalIdentity } from "./renewalIdentity.js";
 export const NATIVE_SUBSCRIPTION_CAPABILITIES = Object.freeze({
     graph: "native",
     multiCyclePrepaid: Object.freeze({ supported: false, refusalCode: "multi_cycle_prepaid_unsupported" }),
-    genericBundleCommands: Object.freeze({ supported: false, refusalCode: "native_generic_bundle_commands_unsupported" }),
-    commandBoundReceipts: Object.freeze({ supported: false, refusalCode: "native_command_bound_receipts_unsupported" }),
+    genericBundleCommands: Object.freeze({ supported: true }),
+    commandBoundReceipts: Object.freeze({ supported: true }),
     preparedAttemptStore: Object.freeze({ supported: false, refusalCode: "native_prepared_attempt_store_unsupported" }),
-    retryRecovery: "selected", stockRecovery: "unavailable",
+    retryRecovery: "selected",
+    // Native N3 adapters exist; selection requires passing real-PG evidence.
+    stockRecovery: "unavailable",
     deliveryAdmission: "required", executorCount: 1, defaultEnabled: false,
 });
 export { executeRenewalCycle, prepareRenewalAttempt, checkRenewalDeliveryAdmission } from "./renewalCycleMechanism.js";
@@ -15,3 +17,20 @@ export { runAutomaticSubscriptionRenewals, runOneAutomaticSubscriptionRenewal, c
 export { createPostgresRenewalStore } from "./postgresRenewalStore.js";
 export { createPostgresRetryStore } from "./postgresRetryStore.js";
 export { createPostgresRetryLifecycleBinding } from "./postgresRetryStore.js";
+export { createPostgresSubscriptionCommandStore, createPostgresSubscriptionCommands } from "./postgresCommandStore.js";
+export { createPostgresStockWaitStore } from "./postgresStockWaitStore.js";
+/** Managed SQL is exposed for service-role hosts; no StockWaitStorePort or
+ * NewPurchaseStockReadPort TypeScript adapter is composed for this graph.
+ * SQL behavior is proved by the managed pgTAP/real-PostgreSQL witnesses.
+ */
+export const MANAGED_SUBSCRIPTION_STOCK_CAPABILITIES = Object.freeze({
+    graph: "managed",
+    stockRecovery: "unavailable",
+    stockWaitSurface: "sql",
+    stockAvailabilitySurface: "sql",
+    defaultEnabled: false,
+});
+export { runRenewalBatchRows } from "./automaticRenewalExecution.js";
+export { subscriptionLifecycleTemplate, createSubscriptionLifecycleMessages } from "./lifecycleMessages.js";
+export { createSubscriptionCommandExamples } from "./commandExamples.js";
+export { createSubscriptionServices } from "./services.js";

package/dist/subscriptions/lifecycleMessages.d.ts

@@ -0,0 +1,9 @@
+import type { SubscriptionLifecycleMessageDescriptor, SubscriptionLifecycleMessagePort } from "./contracts/messages.js";
+export declare function subscriptionLifecycleTemplate(eventType: string, retryAttempt?: number | null): string | null;
+/** M04 owns delivery, consent, rendering and durable replay. M10 never synthesizes a pause. */
+export declare function createSubscriptionLifecycleMessages(delivery: SubscriptionLifecycleMessagePort): {
+    deliver(input: Omit<SubscriptionLifecycleMessageDescriptor, "templateSlug">): Promise<{
+        notificationId: string;
+        replayed: boolean;
+    }>;
+};

package/dist/subscriptions/lifecycleMessages.js

@@ -0,0 +1,38 @@
+/** Matches M5 and the existing M04 lifecycle templates. A mapping is not a send. */
+const templates = Object.freeze({
+    "subscription.created": "subscription-welcome",
+    "subscription.activation_action_required": "subscription-activation-action-required",
+    "subscription.cancelled": "subscription-cancelled",
+    "subscription.paused": "subscription-paused",
+    "subscription.resumed": "subscription-resumed",
+    "subscription.pause_reminder_due": "subscription-pause-reminder",
+    "subscription.delivery_rescheduled": "subscription-delivery-rescheduled",
+    "subscription.cycle_skipped": "subscription-cycle-skipped",
+    "subscription.address_changed": "subscription-address-changed",
+    "subscription.package_changed": "subscription-package-changed",
+    "subscription.renewal_upcoming": "subscription-renewal-upcoming",
+    "subscription_stock_wait.started": "subscription-stock-wait-started",
+    "subscription_stock_wait.resumed": "subscription-stock-wait-resumed",
+    payment_expired: "subscription-payment-expired",
+    payment_recovered: "subscription-payment-recovered", winback_eligible: "subscription-winback",
+    stock_wait_started: "subscription-stock-wait-started", stock_wait_resumed: "subscription-stock-wait-resumed",
+});
+export function subscriptionLifecycleTemplate(eventType, retryAttempt) {
+    // Installed dunning SQL uses rung 3 for every value other than exactly 1 or 2.
+    if (eventType === "payment_failed")
+        return `subscription-payment-failed-${retryAttempt === 1 ? 1 : retryAttempt === 2 ? 2 : 3}`;
+    return Object.hasOwn(templates, eventType) ? templates[eventType] : null;
+}
+/** M04 owns delivery, consent, rendering and durable replay. M10 never synthesizes a pause. */
+export function createSubscriptionLifecycleMessages(delivery) {
+    return {
+        deliver(input) {
+            const templateSlug = subscriptionLifecycleTemplate(input.fact.kind, input.fact.kind === "payment_failed" ? input.fact.retryAttempt : null);
+            if (!templateSlug)
+                throw new Error("subscription_lifecycle_message_unsupported");
+            if (input.messageKey !== input.fact.idempotencyKey)
+                throw new Error("subscription_lifecycle_message_identity_mismatch");
+            return delivery.enqueue({ ...input, templateSlug });
+        },
+    };
+}

package/dist/subscriptions/paymentOutcomes.js

@@ -7,7 +7,7 @@ export async function readAndApplyProviderOutcome(deps, operation, prepared, rai
         throw new Error("subscription_renewal_provider_amount_mismatch");
     if (observed.currency !== null && observed.currency.toUpperCase() !== money.currency.toUpperCase())
         throw new Error("subscription_renewal_provider_currency_mismatch");
-    if (observed.status === "pending" || observed.status === "unknown")
+    if (observed.status !== "succeeded" && observed.status !== "failed")
         return automaticRenewalResult(operation, "awaiting_provider", `provider_${observed.status}`);
     if (observed.operationId !== operation.operationId || observed.requestFingerprint !== operation.operationFingerprint
         || observed.externalAttemptRef !== externalAttemptRef || !observed.verifiedEvidenceRef || !observed.eventKey

package/dist/subscriptions/postgresCommandStore.d.ts

@@ -0,0 +1,44 @@
+import type { SubscriptionCommand, SubscriptionCommandPort, SubscriptionCommandRefusal } from "./contracts/commands.js";
+import { type SubscriptionQueryExecutor } from "./postgresRenewalStore.js";
+export interface NativeSubscriptionCommand {
+    actorId: string;
+    clientId: string;
+    idempotencyKey: string;
+    subscriptionId: string;
+    action: string;
+    payload: Record<string, unknown>;
+    now: string;
+}
+export interface NativeSubscriptionCommandBinding {
+    /** The callback must use one connection and commit/rollback the complete unit. */
+    withTransaction<T>(work: (executor: SubscriptionQueryExecutor) => Promise<T>): Promise<T>;
+    /** Validate address ownership and refuse address mutation; resolve SKUs and
+     * composition policy using trusted host evidence. No current-cycle write. */
+    futureTerms(command: Extract<SubscriptionCommand, {
+        action: "edit_future_terms";
+    }>): Promise<{
+        coreLines: readonly {
+            variantId: string;
+            qty: number;
+        }[];
+        addonLines: readonly {
+            variantId: string;
+            qty: number;
+        }[];
+        compositionConstraint: Record<string, unknown>;
+    } | SubscriptionCommandRefusal>;
+}
+/** N2 owns normalization, locking, quote acceptance, receipts and all writes.
+ * Preview is a separate persisted transaction; apply never executes payment. */
+export declare function createPostgresSubscriptionCommandStore(binding: Pick<NativeSubscriptionCommandBinding, "withTransaction">): {
+    preview(input: NativeSubscriptionCommand): Promise<Record<string, unknown>>;
+    apply(input: NativeSubscriptionCommand): Promise<Record<string, unknown>>;
+};
+/** Trusted customer/operator authorization precedes this adapter. The native
+ * result's subscriptionStatus is the state recorded by the original execution,
+ * including on replay; it is not a fresh read of mutable subscription state. */
+export declare function createPostgresSubscriptionCommands(binding: NativeSubscriptionCommandBinding): SubscriptionCommandPort & {
+    preview(command: Extract<SubscriptionCommand, {
+        action: "edit_future_terms";
+    }>): Promise<Record<string, unknown> | SubscriptionCommandRefusal>;
+};