@openlup/platform 0.26.0 → 0.28.0

package/src/commerce/server/commerceRuntimePort.ts

@@ -0,0 +1,75 @@
+import type { z } from "zod";
+import { CommerceRuntimeConflictError, CommerceRuntimePersistenceError } from "../runtimeErrors.js";
+import type { CommerceCheckoutRuntimeOrderPort } from "../contracts/runtimePorts.js";
+import type { RpcError } from "../contracts/omsTypes.js";
+import { safeCommerceDiagnosticValue } from "./commerceDiagnostics.js";
+const FINALIZE_RPC_NAME = "commerce_finalize_order_for_checkout";
+
+export interface ManagedCommerceRuntimeClient {
+  rpc(functionName: string, args: Record<string, unknown>): PromiseLike<{ data: unknown; error: RpcError | null }>;
+}
+
+export function createManagedCommerceRuntimeOrderPort<Request, Order extends { items: unknown[] }>(
+  client: ManagedCommerceRuntimeClient,
+  bindings: { finalizeArgs(request: Request): Record<string, unknown>; responseEnvelopeSchema: z.ZodType },
+): CommerceCheckoutRuntimeOrderPort<Request, Order> {
+  return {
+    async finalizeOrderForCheckout(request: Request): Promise<Order> {
+      const { data, error } = await client.rpc(FINALIZE_RPC_NAME, bindings.finalizeArgs(request));
+      if (error) throw mapRpcError(error);
+      return parseFinalizeResponse(data);
+    },
+  };
+  function parseFinalizeResponse(data: unknown): Order {
+    const parsed = bindings.responseEnvelopeSchema.safeParse(data);
+    if (!parsed.success || typeof data !== "object" || data === null) {
+      throw new CommerceRuntimePersistenceError("Commerce finalize response invalid");
+    }
+    const finalizedOrder = (data as { finalizedOrder?: unknown }).finalizedOrder;
+    if (!finalizedOrder || typeof finalizedOrder !== "object") {
+      throw new CommerceRuntimePersistenceError("Commerce finalize response invalid");
+    }
+    const order = finalizedOrder as Order;
+    if (!Array.isArray(order.items) || order.items.length === 0) {
+      throw new CommerceRuntimePersistenceError("Commerce finalize response missing order items");
+    }
+    return order;
+  }
+}
+
+export function mapRpcError(error: RpcError): Error {
+  // Diagnostic only: preserve constraint/cause signal without raw payload values.
+  console.error(
+    "commerce_runtime_finalize_rpc_error",
+    JSON.stringify({
+      code: error.code,
+      message: safeCommerceDiagnosticValue(error.message),
+      details: safeCommerceDiagnosticValue(error.details),
+      hint: safeCommerceDiagnosticValue(error.hint),
+    }),
+  );
+  const text = [error.message, error.details, error.hint].filter(Boolean).join(" ");
+  if (text.includes("acquisition_terms_changed")) {
+    return new CommerceRuntimeConflictError("Acquisition terms changed", {
+      code: error.code, reason: "acquisition_terms_changed",
+    });
+  }
+  if (text.includes("commerce_runtime_finalize_journey_consumed")) {
+    // The journey key already finalized a different request (order completed,
+    // possibly out-of-band via checkout recovery). The client must rotate its
+    // journey key — a retry under the same key can never succeed.
+    return new CommerceRuntimeConflictError("Commerce checkout journey already completed", {
+      code: error.code,
+      reason: "journey_consumed",
+    });
+  }
+  if (
+    error.code === "23505" ||
+    /commerce_runtime_finalize_.*(?:conflict|not_found|not_owned|mismatch|missing|requires|unknown|invalid|not_draft)/.test(
+      text,
+    )
+  ) {
+    return new CommerceRuntimeConflictError("Commerce order finalize conflict", { code: error.code });
+  }
+  return new CommerceRuntimePersistenceError("Commerce order finalize RPC failed", { code: error.code });
+}

package/src/commerce/server/commerceRuntimeService.ts

@@ -0,0 +1,229 @@
+import type { z } from "zod";
+import type { FinalizedCheckoutOrder, CommerceCheckoutRuntimeOrderPort, InventoryCheckoutReservationPort, CommerceRuntimeReadinessPort } from "../contracts/index.js";
+import { CommerceRuntimeConflictError } from "../runtimeErrors.js";
+import type { CheckoutRuntimeRequest, CheckoutRuntimeExecutionInput, CheckoutRuntimeExecutionResult, CheckoutRuntimeExecutionPort, CheckoutRuntimePaymentPort, CheckoutRuntimeResultRequest, CheckoutRuntimeResponse, CheckoutExecutionProvider } from "./checkoutRuntimeTypes.js";
+export function createCommerceRuntimeService<Request extends CheckoutRuntimeRequest, Order extends FinalizedCheckoutOrder<string>, Reservation, PaymentPort extends CheckoutRuntimePaymentPort, Execution extends CheckoutRuntimeExecutionResult, Transient, ExecutionPort extends CheckoutRuntimeExecutionPort<Execution, Transient, Request["providerFlow"], NonNullable<Request["paymentMethodAliasType"]>, NonNullable<Request["paymentMethodRecurringModel"]>>, PreparedPort, PreDispatch, Readiness, Response extends CheckoutRuntimeResponse, ResultRequest extends CheckoutRuntimeResultRequest, ResultResponse, PreparedProvider extends Request["paymentProvider"]>(bindings: {
+  defaultPaymentProvider: Request["paymentProvider"]; defaultProviderFlow: Request["providerFlow"];
+  preparedRecurringModel(request: Request): string | undefined;
+  contractVersion: string; resultResponseSchema: z.ZodType<ResultResponse>; defaultExecutionPort: ExecutionPort;
+  executionSubject(order: Order): object; paymentMetadataExtension(order: Order): object;
+  buildProviderAttemptIdentity(input: { provider: Request["paymentProvider"]; localExecutionIdempotencyKey: string; paymentIntentId: string; amountMinor: number; currency: string; mode: "one_time" | "subscription_cycle"; orderRef: string }): { providerIdempotencyKey: string; providerRequestFingerprint: string };
+  transientProviderInput(execution: Request["paymentExecution"]): Transient | null;
+  requiresPreparedProviderAttempt(provider: Request["paymentProvider"]): provider is PreparedProvider;
+  preparedProviderAttemptPort(port: PaymentPort, provider: Request["paymentProvider"]): PreparedPort;
+  executePreparedProviderAttempt(input: { paymentPort: PreparedPort; executionPort: ExecutionPort; provider: PreparedProvider; paymentIntentId: string; executionInput: CheckoutRuntimeExecutionInput<Transient, Request["providerFlow"], NonNullable<Request["paymentMethodAliasType"]>, NonNullable<Request["paymentMethodRecurringModel"]>>; prepareIdempotencyKey: string; finalizeIdempotencyKey: string; providerIdempotencyKey: string; providerRequestFingerprint: string; providerFlow: string; paymentMethodRef?: string | null; prepareRequestPayload: Record<string, unknown> }): Promise<{ execution: Execution; attempt: { paymentAttemptId: string; status: string } }>;
+  isPreDispatch(error: unknown): error is PreDispatch;
+  reopenExhaustedPreDispatchAttempt(input: { error: PreDispatch; paymentPort: PaymentPort; paymentExecutionIdempotencyKey: string; order: Order; reservations: Reservation[]; intent: { paymentIntentId: string; paymentId: string }; provider: Request["paymentProvider"] }): Promise<Response>;
+  preserveProviderDispatchUncertainty<T>(operation: () => Promise<T>, paymentAttemptId: string): Promise<T>;
+  recordPaymentAttempt(port: PaymentPort, input: { idempotencyKey: string; paymentIntentId: string; execution: Execution }): Promise<{ paymentAttemptId: string; status: string }>;
+  buildStartedRuntimeResponse(input: { paymentExecutionIdempotencyKey: string; order: Order; reservations: Reservation[]; intent: { paymentIntentId: string; paymentId: string; status: string }; execution: Execution; attempt: { paymentAttemptId: string; status: string }; continuationActionOrigin: "fresh_execution" | null; paymentPort: PaymentPort; readinessPort: CommerceRuntimeReadinessPort<Readiness> }): Promise<Response>;
+}) {
+  type CommerceRuntimeServiceDeps = {
+    orderPort: CommerceCheckoutRuntimeOrderPort<Request, Order>;
+    inventoryPort: InventoryCheckoutReservationPort<Order, "created", Reservation>;
+    paymentPort: PaymentPort; readinessPort: CommerceRuntimeReadinessPort<Readiness>;
+    executionPort?: ExecutionPort; resolveExecutionPort?: (provider: string) => ExecutionPort;
+  };
+
+function createService({
+  orderPort,
+  inventoryPort,
+  paymentPort,
+  readinessPort,
+  executionPort = bindings.defaultExecutionPort,
+  resolveExecutionPort,
+}: CommerceRuntimeServiceDeps) {
+  const pickExecutionPort = (providerKind: string): ExecutionPort =>
+    resolveExecutionPort ? resolveExecutionPort(providerKind) : executionPort;
+
+  const startRuntime = async (
+    request: Request,
+    resolvedExecutionPort?: ExecutionPort,
+  ): Promise<Response> => {
+    const paymentProvider = request.paymentProvider ?? bindings.defaultPaymentProvider;
+    const providerFlow = request.providerFlow ?? bindings.defaultProviderFlow;
+    const executionPortForRequest = resolvedExecutionPort ?? pickExecutionPort(paymentProvider);
+      const order = await orderPort.finalizeOrderForCheckout(request);
+      const reservations = await inventoryPort.reserveOrderItems({
+        idempotencyKey: `${request.idempotencyKey}:inventory`,
+        order,
+        paymentStatus: "created",
+        metadata: request.metadata,
+      });
+      const targetKind = order.mode === "subscription_cycle" ? "subscription_cycle" : "one_time_order";
+      const intent = await paymentPort.createIntent({
+        idempotencyKey: `${request.idempotencyKey}:payment-intent`,
+        targetKind,
+        orderId: order.orderId,
+        subscriptionId: order.subscriptionId,
+        subscriptionCycleId: order.subscriptionCycleId,
+        amountMinor: order.total.amountMinor,
+        currency: order.total.currency,
+        metadata: {
+          ...request.metadata,
+          source: "commerce.runtime.hidden.v0",
+          runtimeIdempotencyKey: request.idempotencyKey,
+          ...bindings.paymentMetadataExtension(order),
+        },
+      });
+      // Attempt-scoped, not journey-scoped: a retry after a terminal decline —
+      // and above all a switch to another provider — needs a fresh provider
+      // attempt identity on the SAME order. Sequence 0 keeps the historic key
+      // byte-identical.
+      const attemptSequence = request.paymentAttemptSequence ?? 0;
+      const paymentExecutionIdempotencyKey = attemptSequence > 0
+        ? `${request.idempotencyKey}:payment-execution:attempt:${attemptSequence}`
+        : `${request.idempotencyKey}:payment-execution`;
+      const providerAttemptIdentity = bindings.buildProviderAttemptIdentity({
+        provider: paymentProvider,
+        localExecutionIdempotencyKey: paymentExecutionIdempotencyKey,
+        paymentIntentId: intent.paymentIntentId,
+        amountMinor: order.total.amountMinor,
+        currency: order.total.currency,
+        mode: order.mode,
+        orderRef: order.orderRef,
+      });
+      const executionInput: CheckoutRuntimeExecutionInput<Transient, Request["providerFlow"], NonNullable<Request["paymentMethodAliasType"]>, NonNullable<Request["paymentMethodRecurringModel"]>> = {
+        idempotencyKey: paymentExecutionIdempotencyKey,
+        providerIdempotencyKey: providerAttemptIdentity.providerIdempotencyKey,
+        providerRequestFingerprint: providerAttemptIdentity.providerRequestFingerprint,
+        paymentIntentId: intent.paymentIntentId,
+        amountMinor: order.total.amountMinor,
+        currency: order.total.currency,
+        mode: order.mode,
+        orderRef: order.orderRef,
+        providerFlow,
+        clientId: order.clientId,
+        ...bindings.executionSubject(order),
+        orderId: order.orderId,
+        paymentMethodRef: request.paymentMethodRef,
+        paymentMethodAliasType: request.paymentMethodAliasType,
+        paymentMethodRecurringModel: request.paymentMethodRecurringModel,
+        payer: request.providerPayer,
+        // The host execution adapter owns reusable-method policy.
+        saveForFutureUse: request.saveForFutureUse,
+        returnContext: request.returnContext,
+        transientProviderInput: bindings.transientProviderInput(request.paymentExecution),
+      };
+
+      if (bindings.requiresPreparedProviderAttempt(paymentProvider)) {
+        const preparedPaymentPort = bindings.preparedProviderAttemptPort(paymentPort, paymentProvider);
+        const preparedExecution = await bindings.executePreparedProviderAttempt({
+          paymentPort: preparedPaymentPort,
+          executionPort: executionPortForRequest,
+          provider: paymentProvider,
+          paymentIntentId: intent.paymentIntentId,
+          executionInput,
+          prepareIdempotencyKey: `${paymentExecutionIdempotencyKey}:prepare-attempt`,
+          finalizeIdempotencyKey: `${paymentExecutionIdempotencyKey}:finalize-attempt`,
+          providerIdempotencyKey: providerAttemptIdentity.providerIdempotencyKey,
+          providerRequestFingerprint: providerAttemptIdentity.providerRequestFingerprint,
+          providerFlow,
+          paymentMethodRef: request.paymentMethodRef ?? null,
+          prepareRequestPayload: {
+            source: "commerce.runtime.provider-attempt.prepare.v0",
+            providerIdempotencyKey: providerAttemptIdentity.providerIdempotencyKey,
+            providerRequestFingerprint: providerAttemptIdentity.providerRequestFingerprint,
+            providerFlow,
+            paymentMethodRef: request.paymentMethodRef ?? null,
+            recurringModel: bindings.preparedRecurringModel(request),
+            // Audit only: recorded so a refusal can be attributed to an issuer
+            // later. It is not part of the execution object, so it cannot reach
+            // the provider request built below.
+            declaredBankId: request.declaredBankId ?? null,
+            amountMinor: order.total.amountMinor,
+            currency: order.total.currency,
+            orderRef: order.orderRef,
+            runtimeIdempotencyKey: request.idempotencyKey,
+          },
+        }).catch((error: unknown) => {
+          if (!(bindings.isPreDispatch(error))) throw error;
+          return bindings.reopenExhaustedPreDispatchAttempt({
+            error, paymentPort, paymentExecutionIdempotencyKey,
+            order, reservations, intent, provider: paymentProvider,
+          });
+        });
+        if ("runtime" in preparedExecution) return preparedExecution;
+        return bindings.preserveProviderDispatchUncertainty(() => bindings.buildStartedRuntimeResponse({
+          paymentExecutionIdempotencyKey,
+          order,
+          reservations,
+          intent,
+          execution: preparedExecution.execution,
+          attempt: preparedExecution.attempt,
+          continuationActionOrigin: "fresh_execution",
+          paymentPort,
+          readinessPort,
+        }), preparedExecution.attempt.paymentAttemptId);
+      }
+      const execution = await executionPortForRequest.execute(executionInput);
+      const attempt = await bindings.recordPaymentAttempt(paymentPort, {
+        idempotencyKey: `${request.idempotencyKey}:payment-attempt`,
+        paymentIntentId: intent.paymentIntentId,
+        execution,
+      });
+      return bindings.buildStartedRuntimeResponse({
+        paymentExecutionIdempotencyKey,
+        order,
+        reservations,
+        intent,
+        execution,
+        attempt,
+        continuationActionOrigin: null,
+        paymentPort,
+        readinessPort,
+      });
+  };
+
+  const applyPaymentResult = async (
+      request: ResultRequest,
+    ): Promise<ResultResponse> => {
+      const paymentResult = await paymentPort.applyResult(request);
+      if (paymentResult.orderId !== request.orderId) {
+        throw new CommerceRuntimeConflictError("Payment result order mismatch", {
+          requestOrderId: request.orderId,
+          paymentResultOrderId: paymentResult.orderId,
+          paymentIntentId: request.paymentIntentId,
+        });
+      }
+
+      // Interactive PSP declines remain payable on the same order/payment
+      // intent. Releasing their stock here creates a paid-without-reservation
+      // path on the next recovery attempt. Expiry and genuinely terminal
+      // failures still release through this single boundary.
+      const shouldRelease = request.resultStatus === "expired" ||
+        (request.resultStatus === "failed" && paymentResult.kind !== "recoverable_decline");
+      const reservationRelease = shouldRelease
+        ? {
+            attempted: true,
+            ...(await inventoryPort.releaseOrderReservations({
+              idempotencyKey: `${request.idempotencyKey}:inventory-release`,
+              orderId: request.orderId,
+              reason: `payment_${request.resultStatus}`,
+            })),
+          }
+        : { attempted: false, releasedCount: 0 };
+      const readiness = shouldRelease
+        ? null
+        : await readinessPort.evaluateOrderReadiness({
+            orderId: request.orderId,
+            fallbackOrderItemCount: null,
+            allOrderItemsHaveSku: true,
+          });
+
+      return bindings.resultResponseSchema.parse({
+        contractVersion: bindings.contractVersion,
+        paymentResult,
+        reservationRelease,
+        readiness,
+      });
+  };
+
+  return {
+    startRuntime,
+    applyPaymentResult,
+  };
+}
+
+return createService;
+}

package/src/commerce/server/commerceRuntimeStartResponse.ts

@@ -0,0 +1,76 @@
+import type { z } from "zod";
+import type { FinalizedCheckoutOrder, CommerceRuntimeReadinessPort } from "../contracts/index.js";
+import type { CheckoutRuntimeExecutionResult } from "./checkoutRuntimeTypes.js";
+export function createRuntimeStartResponse<Order extends FinalizedCheckoutOrder<string>, Reservation, PaymentPort, Execution extends CheckoutRuntimeExecutionResult, Readiness, Response>(bindings: {
+  contractVersion: string; responseSchema: z.ZodType<Response>;
+  runtimeResponseExtension(order: Order): object;
+  finalizeDeclinedAttempt(port: PaymentPort, input: { idempotencyKey: string; orderId: string; paymentIntentId: string; fallbackAttemptId: string; decline: NonNullable<Execution["providerDecline"]> }): Promise<{ paymentAttemptId: string; status: string }>;
+}) {
+
+async function buildStartedRuntimeResponse(input: {
+  paymentExecutionIdempotencyKey: string;
+  order: Order;
+  reservations: Reservation[];
+  intent: { paymentIntentId: string; paymentId: string; status: string };
+  execution: Execution;
+  attempt: { paymentAttemptId: string; status: string };
+  continuationActionOrigin: "fresh_execution" | null;
+  paymentPort: PaymentPort;
+  readinessPort: CommerceRuntimeReadinessPort<Readiness>;
+}): Promise<Response> {
+  let attempt = input.attempt;
+  if (input.execution.providerDecline) {
+    attempt = await bindings.finalizeDeclinedAttempt(input.paymentPort, {
+      idempotencyKey: `${input.paymentExecutionIdempotencyKey}:payment-declined`,
+      orderId: input.order.orderId,
+      paymentIntentId: input.intent.paymentIntentId,
+      fallbackAttemptId: attempt.paymentAttemptId,
+      decline: input.execution.providerDecline,
+    });
+  }
+  const readiness = await input.readinessPort.evaluateOrderReadiness({
+    orderId: input.order.orderId,
+    fallbackOrderItemCount: input.order.items.length,
+    allOrderItemsHaveSku: true,
+  });
+
+  return bindings.responseSchema.parse({
+    contractVersion: bindings.contractVersion,
+    runtime: {
+      orderId: input.order.orderId,
+      orderRef: input.order.orderRef,
+      mode: input.order.mode,
+      clientId: input.order.clientId,
+      ...bindings.runtimeResponseExtension(input.order),
+      shippingAddressId: input.order.shippingAddressId,
+      total: input.order.total,
+      finalizedReplayed: input.order.replayed,
+      reservations: input.reservations,
+      payment: {
+        paymentIntentId: input.intent.paymentIntentId,
+        paymentId: input.intent.paymentId,
+        paymentAttemptId: attempt.paymentAttemptId,
+        // finalizeDeclinedAttempt above already applied the canonical failed
+        // result to the durable intent/payment/attempt. Reflect that result
+        // instead of returning the stale pre-execution "created" snapshot.
+        status: input.execution.providerDecline ? "failed" : input.intent.status,
+        ...(input.execution.providerDecline?.mandateUnsupported ? { declineMandateUnsupported: true } : {}),
+        attemptStatus: attempt.status,
+        provider: input.execution.provider,
+        providerAttemptId: input.execution.providerAttemptId,
+        providerClientSecret: input.execution.clientSecret ?? null,
+        providerRedirectUrl: input.execution.redirectUrl ?? null,
+        providerNextActionKind: input.execution.nextActionKind ?? null,
+        continuationActionOrigin: input.continuationActionOrigin,
+      },
+      readiness,
+      nextAction: {
+        kind: "await_hidden_payment_result",
+        provider: input.execution.provider,
+      },
+    },
+  });
+}
+
+return { buildStartedRuntimeResponse };
+}

package/src/commerce/server/commerceStarterOfferGuard.ts

@@ -0,0 +1,200 @@
+import type { z } from "zod";
+import type { ConfiguratorIntent } from "../contracts/index.js";
+import type { CommerceQuotePort } from "../ports.js";
+import type { StarterTermsPort, StarterTermsRefusal } from "./starterTermsPort.js";
+import type { CheckoutQuoteSnapshot } from "./checkoutQuoteTypes.js";
+export interface StarterDeclaration {
+  intervalDays: number; delivery2DiscountBps: number;
+  acquisitionTerms?: { revision: string; delivery2DiscountBps: number };
+  steady: { cadenceDays: number; units: number };
+}
+export type StarterOfferGuardResult<Plan> = { kind: "absent" } | { kind: "rejected"; reason: string } | { kind: "minted"; plan: Plan };
+export function withStarterPackContext<Snapshot extends CheckoutQuoteSnapshot, Plan>(snapshot: Snapshot, plan: Plan | null): Snapshot {
+  if (!plan || !snapshot.quote.context) return snapshot;
+  return { ...snapshot, quote: { ...snapshot.quote, context: { ...snapshot.quote.context, starterPack: plan } } };
+}
+export function createStarterOfferGuard<Intent extends ConfiguratorIntent, Provisioned extends { clientId: string | null }, Request, Snapshot extends CheckoutQuoteSnapshot, Plan>(bindings: {
+  declaration(intent: Intent): StarterDeclaration | undefined;
+  defaultTermsPort: StarterTermsPort<Intent, Snapshot>;
+  defaultDiscountBps: number;
+  discountMinor(input: { bandSubtotalMinor: number; listAnchorTotalMinor: number; discountBps: number }): number | null;
+  planSchema: z.ZodType<Plan>;
+  aggregateBySku(entries: Intent["selectedVariants"]): Intent["selectedVariants"];
+  rescaleBasket(entries: Intent["selectedVariants"], units: number): Intent["selectedVariants"];
+  steadyIntent(intent: Intent, cadenceDays: number, units: number, variants: Intent["selectedVariants"]): Intent;
+  buildQuoteRequest(intent: Intent, provisioned: Provisioned): Request;
+}) {
+  type CreateQuoteResponse = Snapshot;
+  type StarterPackPlan = Plan;
+  type StarterOfferGuardInput = {
+    flagEnabled: boolean; intent: Intent; provisioned: Provisioned;
+    authoritativeQuote: Snapshot; quotePort: CommerceQuotePort<Request, Snapshot, import("../../pricing/index.js").CreateQuoteOptions>;
+    isFirstOrderEligible?: () => Promise<boolean>;
+    termsPort?: StarterTermsPort<Intent, Snapshot>; offerVersion?: string;
+  }
+
+
+type StarterOfferRejectionReason =
+  | "starter_offer_disabled"
+  | "starter_offer_wrong_mode"
+  | "starter_offer_not_first_order"
+  | "starter_offer_basket_too_small"
+  | "starter_offer_basket_not_admitted"
+  | "starter_offer_demand_unknown"
+  | "starter_offer_terms_drifted"
+  | "starter_offer_uncollectable_delivery_2"
+  | "starter_offer_steady_quote_failed"
+  | "starter_offer_plan_invalid";
+
+const TERMS_REFUSALS: Record<StarterTermsRefusal, StarterOfferRejectionReason> = {
+  basket_too_small: "starter_offer_basket_too_small",
+  basket_not_admitted: "starter_offer_basket_not_admitted",
+  demand_unknown: "starter_offer_demand_unknown",
+};
+
+const ACQUISITION_TEMPLATE_VERSION = 1;
+
+async function resolveStarterOfferGuard(
+  input: StarterOfferGuardInput,
+): Promise<StarterOfferGuardResult<Plan>> {
+  const declared = bindings.declaration(input.intent);
+  // Flag OFF and nothing declared is the overwhelmingly common case and must do
+  // exactly zero work — no quote, no read, no allocation.
+  if (!declared) return { kind: "absent" };
+  if (!input.flagEnabled) return { kind: "rejected", reason: "starter_offer_disabled" };
+  if (input.intent.mode !== "subscription") {
+    return { kind: "rejected", reason: "starter_offer_wrong_mode" };
+  }
+
+  // The terms of the effective basket, from the server's own quote. The default
+  // port is the arithmetic the client asks with (see `defaultStarterTermsPort`),
+  // so any disagreement below is a drifted ask, never a rounding difference.
+  const resolution = await (input.termsPort ?? bindings.defaultTermsPort).resolve({
+    intent: input.intent,
+    authoritativeQuote: input.authoritativeQuote,
+    ...(input.offerVersion ? { offerVersion: input.offerVersion } : {}),
+  });
+  if (resolution.kind === "refused") {
+    return { kind: "rejected", reason: TERMS_REFUSALS[resolution.reason] };
+  }
+  const {
+    intervalDays,
+    steadyCadenceDays: cadenceDays,
+    steadyUnits: steadyUnits,
+    graduationSizeConstraint,
+  } = resolution.terms;
+  const acquisition = input.authoritativeQuote.quote.context?.acquisitionTerms;
+  const delivery2DiscountBps = acquisition?.delivery2DiscountBps ?? bindings.defaultDiscountBps;
+  if (
+    (acquisition !== undefined && (declared.acquisitionTerms?.revision !== acquisition.revision ||
+      declared.acquisitionTerms.delivery2DiscountBps !== delivery2DiscountBps)) ||
+    declared.intervalDays !== intervalDays ||
+    declared.delivery2DiscountBps !== delivery2DiscountBps ||
+    declared.steady.cadenceDays !== cadenceDays ||
+    declared.steady.units !== steadyUnits
+  ) {
+    return { kind: "rejected", reason: "starter_offer_terms_drifted" };
+  }
+
+  if (!(await input.isFirstOrderEligible?.())) {
+    return { kind: "rejected", reason: "starter_offer_not_first_order" };
+  }
+
+  const bandSubtotalMinor = input.authoritativeQuote.quote.subtotalGross.amountMinor;
+  const discountMinor = bindings.discountMinor({
+    bandSubtotalMinor,
+    listAnchorTotalMinor: listAnchorTotalMinor(input.authoritativeQuote),
+    discountBps: delivery2DiscountBps,
+  });
+  if (discountMinor === null) {
+    return { kind: "rejected", reason: "starter_offer_uncollectable_delivery_2" };
+  }
+
+  const steadyQuote = await quoteSteadyPackage(input, steadyUnits, cadenceDays);
+  if (steadyQuote === null) {
+    return { kind: "rejected", reason: "starter_offer_steady_quote_failed" };
+  }
+
+  const parsed = bindings.planSchema.safeParse({
+    schemaVersion: "1",
+    starterIntervalDays: intervalDays,
+    basisTemplateVersion: ACQUISITION_TEMPLATE_VERSION,
+    delivery2: {
+      discountBps: delivery2DiscountBps,
+      discountMinor,
+      basisSubtotalMinor: bandSubtotalMinor,
+    },
+    graduation: {
+      cadenceDays,
+      sizeConstraint: graduationSizeConstraint ?? { kind: "unit_count", value: steadyUnits },
+      lines: steadyQuote.quote.lines.map((line, index) => ({
+        sku: line.sku,
+        qty: line.quantity,
+        sortOrder: index,
+        // Addons are never part of a graduation basket; the RPC deletes only
+        // non-addon template lines, so an existing addon survives untouched.
+        isAddon: false,
+        quoteLine: frozenQuoteLine(line),
+      })),
+    },
+  });
+  if (!parsed.success) return { kind: "rejected", reason: "starter_offer_plan_invalid" };
+  return { kind: "minted", plan: parsed.data };
+}
+
+
+function listAnchorTotalMinor(snapshot: CreateQuoteResponse): number {
+  const orderScoped = sumBaseUnit(snapshot.quote.pricingComponents);
+  if (orderScoped > 0) return orderScoped;
+  return snapshot.quote.lines.reduce(
+    (total, line) => total + sumBaseUnit(line.pricingComponents),
+    0,
+  );
+}
+
+function sumBaseUnit(
+  components: ReadonlyArray<{ componentType: string; amountMinor: number }> | undefined,
+): number {
+  if (!components) return 0;
+  return components
+    .filter((component) => component.componentType === "base_unit")
+    .reduce((total, component) => total + component.amountMinor, 0);
+}
+
+function frozenQuoteLine(line: CreateQuoteResponse["quote"]["lines"][number]): Record<string, unknown> {
+  const { pricingComponents: _dropped, ...rest } = line;
+  return { ...rest } as Record<string, unknown>;
+}
+
+async function quoteSteadyPackage(
+  input: StarterOfferGuardInput,
+  steadyUnits: number,
+  cadenceDays: number,
+): Promise<CreateQuoteResponse | null> {
+  const steadyVariants = bindings.rescaleBasket(
+    bindings.aggregateBySku(input.intent.selectedVariants),
+    steadyUnits,
+  );
+  // Fail closed on an unrepresentable basket (more distinct variants than units).
+  // Quoting it would mint a marker whose lines contradict the size it promises.
+  if (steadyVariants.reduce((total, v) => total + v.qty, 0) !== steadyUnits) return null;
+  const steadyIntent = bindings.steadyIntent(input.intent, cadenceDays, steadyUnits, steadyVariants);
+  try {
+    // A bound offer prices its steady basket from its own list, like the checkout quote.
+    const quoted = await input.quotePort.createQuote(
+      bindings.buildQuoteRequest(steadyIntent, input.provisioned),
+      {
+        ...(input.provisioned.clientId ? { clientId: input.provisioned.clientId } : {}),
+        ...(input.offerVersion ? { offerVersion: input.offerVersion } : {}),
+        ...(input.authoritativeQuote.quote.context?.pricingPolicy
+          ? { pricingPolicy: input.authoritativeQuote.quote.context.pricingPolicy } : {}),
+      },
+    );
+    return quoted.quote.lines.length > 0 ? quoted : null;
+  } catch {
+    return null;
+  }
+}
+
+return { resolveStarterOfferGuard };
+}