@openlup/platform 0.24.0 → 0.25.0

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/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>;
+};

package/dist/subscriptions/postgresCommandStore.js

@@ -0,0 +1,172 @@
+import { subscriptionRecord } from "./postgresRenewalStore.js";
+import { NATIVE_SUBSCRIPTION_CAPABILITIES } from "./index.js";
+const refusalCodes = new Set([
+    "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",
+]);
+function refusalReason(reason) {
+    return typeof reason === "string" && refusalCodes.has(reason)
+        ? reason : "subscription_command_invalid_input";
+}
+function commandResult(result) {
+    return result.status === "refused" || result.outcome === "refused"
+        ? { ...result, reason: refusalReason(result.reason) } : result;
+}
+/** N2 owns normalization, locking, quote acceptance, receipts and all writes.
+ * Preview is a separate persisted transaction; apply never executes payment. */
+export function createPostgresSubscriptionCommandStore(binding) {
+    return {
+        preview(input) { return invokeCommand(binding, input, true); },
+        apply(input) { return invokeCommand(binding, input, false); },
+    };
+}
+async function invokeCommand(binding, input, preview, futureTerms) {
+    if (input.action === "multi_cycle_prepaid")
+        return {
+            status: "refused", reason: NATIVE_SUBSCRIPTION_CAPABILITIES.multiCyclePrepaid.refusalCode,
+        };
+    return binding.withTransaction(async (executor) => {
+        const values = [input.actorId, input.clientId, input.idempotencyKey, input.subscriptionId, input.action, input.payload, input.now];
+        // Share N2's actor/key lock so a concurrent preview/apply cannot change
+        // the receipt between this read and native dispatch. Replay ends here,
+        // before any lifecycle function or other potentially writing call.
+        await executor.query("SELECT pg_advisory_xact_lock(hashtextextended($1::uuid::text||':'||$2::text,0))", [input.actorId, input.idempotencyKey]);
+        const stored = await executor.query(`WITH stored AS (
+      SELECT r.*, CASE WHEN $9::boolean THEN jsonb_set(r.command,'{payload}',
+        (r.command->'payload')-ARRAY['coreLines','addonLines','compositionConstraint']) ELSE r.command END AS requested_command
+      FROM public.subscription_command_receipts r WHERE r.actor_id=$1::uuid AND r.idempotency_key=$3::text
+        AND $7::timestamptz IS NOT NULL AND isfinite($7::timestamptz)
+        AND $3::text=btrim($3::text) AND char_length($3::text) BETWEEN 8 AND 180
+        AND $5::text IS NOT NULL AND jsonb_typeof($6::jsonb)='object'
+        AND (NOT $8::boolean OR NOT ($6::jsonb ? 'acceptedQuoteHash'))
+        AND EXISTS(SELECT 1 FROM public.subscriptions WHERE id=$4::uuid AND client_id=$2::uuid)
+    ), receipt AS (
+      SELECT *, CASE WHEN $8::boolean OR status='previewed' THEN
+        jsonb_set(requested_command,'{payload}',(requested_command->'payload')-'acceptedQuoteHash')=
+          jsonb_build_object('clientId',$2::uuid,'subscriptionId',$4::uuid,'action',$5::text,'payload',$6::jsonb-'acceptedQuoteHash')
+        ELSE requested_command=jsonb_build_object('clientId',$2::uuid,'subscriptionId',$4::uuid,'action',$5::text,'payload',$6::jsonb)
+        END AND ($8::boolean OR quote_hash IS NOT DISTINCT FROM ($6::jsonb->>'acceptedQuoteHash')) AS matches
+      FROM stored
+    ) SELECT command, CASE WHEN NOT matches THEN jsonb_build_object('status','refused','reason','subscription_command_idempotency_conflict')
+      WHEN $8::boolean OR status='refused' THEN result
+      WHEN status<>'previewed' THEN result||jsonb_build_object('status','replayed','originalStatus',status,'commandFingerprint',command_fingerprint)
+      END AS response FROM receipt`, [...values, preview, !!futureTerms]);
+        if (stored.rows[0]?.response)
+            return commandResult(subscriptionRecord(stored.rows[0].response));
+        if (futureTerms) {
+            if (stored.rows[0]) {
+                // A matching preview already bound the host translation. Apply that
+                // exact quote even if the host's mutable policy has since changed.
+                values[5] = { ...subscriptionRecord(subscriptionRecord(stored.rows[0].command).payload),
+                    acceptedQuoteHash: input.payload.acceptedQuoteHash };
+            }
+            else {
+                const terms = await futureTerms();
+                if ("outcome" in terms)
+                    return commandResult({ ...terms });
+                values[5] = { ...input.payload, ...terms };
+            }
+        }
+        let result;
+        if (!preview && !Object.hasOwn(input.payload, "acceptedQuoteHash")) {
+            // N2 owns every command's no-op decision. Keep only its terminal noop;
+            // other direct applies must retain their quote requirement without
+            // persisting a speculative quote or refusal from this preview probe.
+            await executor.query("SAVEPOINT subscription_command_noop");
+            const { rows } = await executor.query("SELECT public.subscription_command_preview($1::uuid,$2::uuid,$3::text,$4::uuid,$5::text,$6::jsonb,$7::timestamptz) AS response", values);
+            const candidate = commandResult(subscriptionRecord(rows[0]?.response));
+            if (candidate.status === "noop")
+                result = candidate;
+            else
+                await executor.query("ROLLBACK TO SAVEPOINT subscription_command_noop");
+            await executor.query("RELEASE SAVEPOINT subscription_command_noop");
+        }
+        if (!result) {
+            const name = preview ? "subscription_command_preview" : "subscription_command_apply";
+            const { rows } = await executor.query(`SELECT public.${name}($1::uuid,$2::uuid,$3::text,$4::uuid,$5::text,$6::jsonb,$7::timestamptz) AS response`, values);
+            result = commandResult(subscriptionRecord(rows[0]?.response));
+        }
+        if (preview || result.status === "refused")
+            return result;
+        const receipt = await executor.query(`SELECT command_fingerprint FROM public.subscription_command_receipts
+      WHERE actor_id=$1::uuid AND idempotency_key=$2::text`, [input.actorId, input.idempotencyKey]);
+        if (typeof receipt.rows[0]?.command_fingerprint !== "string")
+            throw new Error("subscription_command_receipt_missing");
+        return { ...result, commandFingerprint: receipt.rows[0].command_fingerprint };
+    });
+}
+/** 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 function createPostgresSubscriptionCommands(binding) {
+    function encode(command) {
+        // This serving adapter never pauses an active subscription. Existing native
+        // callers retain their separate, unchanged lifecycle contract.
+        if (command.action === "pause")
+            return { outcome: "refused", reason: "subscription_command_pause_forbidden" };
+        const { actor, subscriptionId, idempotencyKey, now, action, ...fields } = command;
+        let payload = { ...fields, actorKind: actor.kind };
+        let nativeAction = action === "skip" ? "skip_next_cycle" : action === "slide" ? "slide_next_cycle" : action;
+        if (command.action === "edit_future_terms") {
+            // Preserve the host carriers as well as their native translation in the
+            // actual-command fingerprint. The accepted hash is stripped for preview.
+            payload = { ...payload, requestedCoreLines: command.coreLines, requestedAddonLines: command.addonLines,
+                compositionConstraintRef: command.compositionConstraint };
+            delete payload.coreLines;
+            delete payload.addonLines;
+            delete payload.compositionConstraint;
+            // An empty typed hash means no quote; preserve native no-op replay/probing.
+            if (command.acceptedQuoteHash === "")
+                delete payload.acceptedQuoteHash;
+            nativeAction = "update_package_template";
+        }
+        return { actorId: actor.actorId, clientId: actor.clientId, subscriptionId, idempotencyKey, now, action: nativeAction, payload };
+    }
+    return {
+        capabilities: NATIVE_SUBSCRIPTION_CAPABILITIES,
+        async preview(command) {
+            const input = encode(command);
+            if ("outcome" in input)
+                return input;
+            delete input.payload.acceptedQuoteHash;
+            return invokeCommand(binding, input, true, () => binding.futureTerms(command));
+        },
+        async apply(command) {
+            const input = encode(command);
+            if ("outcome" in input)
+                return input;
+            const result = await invokeCommand(binding, input, false, command.action === "edit_future_terms" ? () => binding.futureTerms(command) : undefined);
+            if (result.status === "refused" || result.outcome === "refused")
+                return { outcome: "refused", reason: refusalReason(result.reason) };
+            if (result.status !== "applied" && result.status !== "replayed" && result.status !== "noop")
+                throw new Error("subscription_command_response_invalid");
+            return { actorId: command.actor.actorId, idempotencyKey: command.idempotencyKey,
+                commandFingerprint: String(result.commandFingerprint), outcome: result.status, subscriptionId: String(result.subscriptionId),
+                originalState: String(result.subscriptionStatus), nextCycleAt: result.nextCycleAt == null ? null : String(result.nextCycleAt),
+                revision: String(result.templateVersion), eventId: result.eventId == null ? null : String(result.eventId) };
+        },
+    };
+}

package/dist/subscriptions/postgresRetryStore.d.ts

@@ -53,6 +53,12 @@ export declare function createPostgresRetryStore(executor: SubscriptionQueryExec
     read(operationId: string): Promise<NativeRetryRow | null>;
     candidates(limit: number, now: string): Promise<NativeRetryRow[]>;
     applyFailure(operationId: string, key: string, input: NativeRetryFailure): Promise<NativeRetryRow>;
+    /** Read the immutable rung receipt against the current case. An interrupted
+     * apply still needs propagation; an already advanced case must not be rewritten. */
+    failureProgress(operationId: string, key: string): Promise<{
+        replayed: boolean;
+        caseAdvanced: boolean;
+    }>;
     openCase(operationId: string, template: string, recoveryPath: string | null): Promise<Record<string, unknown>>;
     authorizeRecovery(operationId: string, tokenId: string, methodRef: string, methodEvidenceRef: string, now: string): Promise<Record<string, unknown>>;
     scheduleRecovery(operationId: string, key: string, authorizationId: string, now: string): Promise<Record<string, unknown>>;

package/dist/subscriptions/postgresRetryStore.js

@@ -34,6 +34,17 @@ export function createPostgresRetryStore(executor) {
         async applyFailure(operationId, key, input) {
             return row(await invoke("subscription_retry_apply_failure", [operationId, key, input]));
         },
+        /** Read the immutable rung receipt against the current case. An interrupted
+         * apply still needs propagation; an already advanced case must not be rewritten. */
+        async failureProgress(operationId, key) {
+            const result = await executor.query(`SELECT true AS replayed,
+        (c.retry_attempt >= (r.result->>'retry_attempt')::integer OR o.state='recovered') AS case_advanced
+        FROM public.subscription_retry_obligations o
+        JOIN public.subscription_retry_receipts r ON r.obligation_id=o.id AND r.kind='failure' AND r.receipt_key=$2::text
+        LEFT JOIN public.subscription_dunning_cases c ON c.id=o.case_id
+        WHERE o.renewal_operation_id=$1::uuid`, [operationId, key]);
+            return { replayed: result.rows.length === 1, caseAdvanced: result.rows[0]?.case_advanced === true };
+        },
         async openCase(operationId, template, recoveryPath) {
             return subscriptionRecord(await invoke("subscription_retry_open_case", [operationId, template, recoveryPath]));
         },

package/dist/subscriptions/postgresStockWaitStore.d.ts

@@ -0,0 +1,62 @@
+import type { StockWaitCase, StockWaitDeficit, StockWaitFrozenCase, StockWaitRecoveryBinding } from "./contracts/stockWait.js";
+import type { RenewalSchedule } from "./contracts/renewal.js";
+import { type NativeRenewalCodec, type SubscriptionQueryExecutor } from "./postgresRenewalStore.js";
+export interface NativeStockWaitBinding {
+    executor: SubscriptionQueryExecutor;
+    withTransaction<T>(work: (executor: SubscriptionQueryExecutor) => Promise<T>): Promise<T>;
+    codec: NativeRenewalCodec;
+    workerId: string;
+}
+export interface NativeStockWaitAdmission {
+    waiting: boolean;
+    caseId: string | null;
+    response: Record<string, unknown>;
+}
+/** Each multi-statement mutation uses the host transaction. Payment execution is
+ * deliberately outside this store. SQL owns stock locks and subtransactions. */
+export declare function createPostgresStockWaitStore(options: NativeStockWaitBinding): {
+    readFrozen(input: RenewalSchedule): Promise<StockWaitFrozenCase | null>;
+    listNormalDue(input: {
+        limit: number;
+        asOf: string;
+    }): Promise<import("./contracts/renewal.js").RenewalDue[]>;
+    deficits(input: {
+        snapshot: import("./contracts/renewal.js").RenewalFrozenSnapshot;
+        operationId: string;
+        now: string;
+    }): Promise<StockWaitDeficit[]>;
+    admit(input: {
+        operationId: string;
+        claimToken: string;
+        snapshot: import("./contracts/renewal.js").RenewalFrozenSnapshot;
+        recovery?: StockWaitRecoveryBinding;
+        now: string;
+    }): Promise<NativeStockWaitAdmission>;
+    enqueue(caseId: string, kind: "started" | "resumed"): Promise<void>;
+    markResumed(orderId: string): Promise<StockWaitCase | null>;
+    listCandidates(input: {
+        limit: number;
+        asOf: string;
+    }): Promise<StockWaitFrozenCase[]>;
+    readFrozenCase(input: StockWaitRecoveryBinding): Promise<StockWaitCase | null>;
+    reserveAndTransition(input: {
+        caseId: string;
+        frozenFingerprint: string;
+        now: string;
+    }): Promise<StockWaitCase>;
+    recoverRefusedSchedule(input: {
+        operationId: string;
+        caseId: string;
+        claimGeneration: number;
+        frozenFingerprint: string;
+        scheduledAt: string;
+        now: string;
+    }): Promise<{
+        outcome: "recovered";
+        operation: import("./contracts/renewal.js").RenewalReadback;
+        replayed: boolean;
+    } | {
+        outcome: "refused";
+        reason: "not_stock_only" | "external_ownership" | "stale_snapshot" | "lease_active" | "inventory_unavailable";
+    }>;
+};