@openlup/platform 0.26.0 → 0.28.0

package/src/account-support/orderHistory.ts

@@ -0,0 +1,309 @@
+import { currentParcelPerOrder, rowsForParcel } from "@openlup/core/fulfillment";
+import {
+  deriveOrderMoney,
+  customerSafeEvidenceToken,
+  customerStepForTerminalOrder,
+  customerStepFromTimedSignals,
+  resolveProviderExceptionRecovery
+} from "../commerce/index.js";
+import type {
+  CanonicalOrderMoney,
+  CanonicalOrderMoneyLine,
+  OrderMoneyHeaderRow,
+  OrderMoneyItemRow,
+  ReleasedProviderExceptionHold,
+  ResolvedProviderExceptionRecovery
+} from "../commerce/contracts/index.js";
+import { resolveDeliverySelectionEvidence, summarizeDeliverySelection } from "../shipping/index.js";
+import type {
+  AccountOrderSummary,
+  AccountOrderDetailResponse,
+  AccountOrderList,
+  AccountOrderLine,
+  AccountFulfillmentSummary,
+  AccountInvoiceSummary,
+  AccountInvoiceDocument
+} from "./contracts/account.js";
+
+export const CUSTOMER_ORDERS_CONTRACT_VERSION = "customer.orders.v2" as const;
+export type CustomerOrderHistoryRow = Record<string, unknown>;
+type Row = CustomerOrderHistoryRow;
+type Tracking = Pick<AccountOrderSummary, "trackingReferences"
+  | "trackingNumbers"
+  | "trackingNumber"
+  | "trackingUrl"
+  | "carrierKind"
+  | "service"
+  | "trackingTimeline">;
+
+export interface CustomerOrderHistoryReadStore {
+  readCustomerOrders(clientId: string, hiddenStatuses: readonly string[], limit: number): Promise<Row[]>;
+  readCustomerOrder(clientId: string, orderId: string): Promise<Row | null>;
+  readOrderLines(orderId: string): Promise<Row[]>;
+  readPaymentStatuses(orderIds: string[]): Promise<Map<string, string>>;
+  readFulfillments(clientId: string, orderIds: string[]): Promise<Row[]>;
+  readTracking(orderIds: string[]): Promise<Map<string, Row[]>>;
+  readFulfillmentOperations(orderIds: string[]): Promise<Map<string, Row[]>>;
+  readStatusEvidence(orderIds: string[]): Promise<Map<string, Row[]>>;
+  readReleasedProviderExceptionHolds(orderIds: string[]): Promise<Map<string, ReleasedProviderExceptionHold[]>>;
+  readReleasedProviderExceptionEvidence(holds: Map<string, ReleasedProviderExceptionHold[]>): Promise<Map<string, Row[]>>;
+  readActiveHoldOrderIds(orderIds: string[]): Promise<Set<string>>;
+  readInvoiceSummaries(
+    orderIds: string[]
+  ): Promise<
+    Map<string, { invoice: AccountInvoiceSummary | null; invoiceDocuments: AccountInvoiceDocument[] }>
+  >;
+}
+
+/** Catalogue/captured-label policy is injected in its entirety, including private extension keys. */
+export interface CustomerOrderLinePresentationPort {
+  display(row: Row): Pick<AccountOrderLine, "title" | "variantName" | "productSlug" | "displayLabel" | "accentColor">;
+}
+
+export interface CustomerOrderHistoryProjectionPort {
+  automaticHoldSource: string;
+  automaticReleaseSource: string;
+  orderReference(orderId: string): string;
+  fulfillmentEvidence(input: {
+    trackingRefs: Row[];
+    statusEvidenceRows: Row[];
+    operationRows: Row[];
+    recovery?: ResolvedProviderExceptionRecovery
+  }): Tracking;
+  presentation: CustomerOrderLinePresentationPort;
+}
+
+export async function readCustomerOrderSummaries(
+  store: CustomerOrderHistoryReadStore,
+  clientId: string,
+  limit: number,
+  projection: CustomerOrderHistoryProjectionPort
+): Promise<AccountOrderList> {
+  const rows = await store.readCustomerOrders(clientId, ["cancelled", "expired"], limit);
+  const maps = await companions(store, clientId, rows.map(row => text(row.id)), projection);
+  return {
+    contractVersion: CUSTOMER_ORDERS_CONTRACT_VERSION,
+    orders: rows.map(row => summary(row, maps, projection))
+  };
+}
+
+export async function readCustomerOrderDetail(
+  store: CustomerOrderHistoryReadStore,
+  clientId: string,
+  orderId: string,
+  projection: CustomerOrderHistoryProjectionPort
+): Promise<AccountOrderDetailResponse | null> {
+  const row = await store.readCustomerOrder(clientId, orderId);
+  if (!row) return null;
+  const [lines, maps] = await Promise.all([store.readOrderLines(orderId), companions(store, clientId, [orderId], projection)]);
+  const money = deriveOrderMoney(toOrderMoneyHeader(row), lines.map(toOrderMoneyItem));
+  return {
+    contractVersion: CUSTOMER_ORDERS_CONTRACT_VERSION,
+    order: {
+      ...summary(row, maps, projection, money),
+      subtotal: customerOrderMoney(money.subtotal, money.currency),
+      discount: customerOrderMoney(money.productDiscount, money.currency),
+      shipping: customerOrderMoney(money.shippingEffective, money.currency),
+      tax: customerOrderMoney(money.tax, money.currency),
+      lines: mapCustomerOrderLines(lines, money.lines, money.currency, projection.presentation),
+      fulfillment: maps.fulfillment.get(orderId) ?? null
+    }
+  };
+}
+
+async function companions(
+  store: CustomerOrderHistoryReadStore,
+  clientId: string,
+  ids: string[],
+  projection: CustomerOrderHistoryProjectionPort
+) {
+  const [payments, parcels, tracking, operations, evidence, holds, active, invoices] = await Promise.all([
+    store.readPaymentStatuses(ids),
+    store.readFulfillments(clientId, ids),
+    store.readTracking(ids),
+    store.readFulfillmentOperations(ids),
+    store.readStatusEvidence(ids),
+    store.readReleasedProviderExceptionHolds(ids),
+    store.readActiveHoldOrderIds(ids),
+    store.readInvoiceSummaries(ids),
+  ]);
+  const released = await store.readReleasedProviderExceptionEvidence(holds);
+  for (const [id, rows] of released) {
+    const known = new Set((evidence.get(id) ?? []).map(row => text(row.id)));
+    evidence.set(id, [...(evidence.get(id) ?? []), ...rows.filter(row => !known.has(text(row.id)))]);
+  }
+  const recovery = new Map<string, ResolvedProviderExceptionRecovery>();
+  for (const parcel of parcels) {
+    const id = text(parcel.order_id);
+    if (!id) continue;
+    recovery.set(
+      id,
+      resolveProviderExceptionRecovery({
+        fulfillmentOrderId: nullableText(parcel.id),
+        releasedHolds: holds.get(id) ?? [],
+        automaticHoldSource: projection.automaticHoldSource,
+        automaticReleaseSource: projection.automaticReleaseSource,
+        statusEvidence: (evidence.get(id) ?? []).map(row => ({
+          id: nullableText(row.id),
+          fulfillmentOrderId: nullableText(row.fulfillment_order_id),
+          providerStatus: nullableText(row.provider_status),
+          localStatus: nullableText(row.local_status),
+          token: customerSafeEvidenceToken(nullableText(row.local_status), nullableText(row.provider_status)),
+          occurredAt: nullableText(row.occurred_at)
+        }))
+      })
+    );
+  }
+  const readTracking = (id: string, parcelId: string | null) => projection.fulfillmentEvidence({
+    trackingRefs: rowsForParcel(tracking.get(id) ?? [], parcelId),
+    statusEvidenceRows: evidence.get(id) ?? [],
+    operationRows: operations.get(id) ?? [],
+    recovery: recovery.get(id)
+  });
+  const fulfillment = new Map<string, AccountFulfillmentSummary>();
+  for (const [id, parcel] of currentParcelPerOrder(parcels)) {
+    const details = readTracking(id, text(parcel.id)), op = operations.get(id)?.[0];
+    fulfillment.set(
+      id,
+      {
+        fulfillmentOrderId: text(parcel.id) || null,
+        status: nullableText(parcel.status),
+        providerKind: nullableText(parcel.provider_kind) ?? details.trackingReferences[0]?.providerKind ?? null,
+        trackingNumber: details.trackingNumber,
+        trackingNumbers: details.trackingNumbers,
+        trackingReferences: details.trackingReferences,
+        lastEventType: nullableText(op?.operation_type) ?? details.trackingTimeline[0]?.eventType ?? null,
+        updatedAt: nullableText(parcel.updated_at) ?? nullableText(op?.occurred_at),
+        trackingTimeline: details.trackingTimeline
+      }
+    );
+  }
+  return { payments, evidence, recovery, active, invoices, fulfillment, readTracking };
+}
+
+function summary(
+  row: Row,
+  maps: Awaited<ReturnType<typeof companions>>,
+  projection: CustomerOrderHistoryProjectionPort,
+  money: CanonicalOrderMoney = deriveOrderMoney(toOrderMoneyHeader(row))
+): AccountOrderSummary {
+  const id = text(row.id),
+    parcel = maps.fulfillment.get(id),
+    tracking = maps.readTracking(id, parcel?.fulfillmentOrderId ?? null),
+    history = maps.invoices.get(id) ?? null,
+    invoice = history?.invoice ?? null;
+  const metadata = record(row.metadata);
+  const requested = nullableText(record(metadata.invoiceBuyerSnapshot).taxId) !== null
+    || nullableText(record(record(metadata.runtimeFinalize).invoiceBuyerSnapshot).taxId) !== null;
+  const customerFulfillmentStep = maps.active.has(id)
+    ? "exception"
+    : customerStepForTerminalOrder(text(row.status))
+    ?? customerStepFromTimedSignals(
+      [text(row.status), parcel?.status ?? null],
+      (maps.evidence.get(id) ?? []).map(value => ({
+        id: nullableText(value.id),
+        token: customerSafeEvidenceToken(nullableText(value.local_status), nullableText(value.provider_status)),
+        occurredAt: nullableText(value.occurred_at)
+      })),
+      maps.recovery.get(id)
+    );
+  return {
+    orderId: id,
+    orderRef: `order_${id}`,
+    orderNumber: nullableText(row.order_number) ?? projection.orderReference(id),
+    subscriptionId: nullableText(row.subscription_id),
+    status: text(row.status),
+    paymentStatus: maps.payments.get(id) ?? null,
+    fulfillmentStatus: parcel?.status ?? null,
+    customerFulfillmentStep,
+    total: customerOrderMoney(money.total, money.currency),
+    ...tracking,
+    deliverySelection: summarizeDeliverySelection(resolveDeliverySelectionEvidence({ orderMetadata: row.metadata }).selection),
+    invoice,
+    invoiceDocuments: history?.invoiceDocuments ?? [],
+    invoiceRequestStatus: invoice?.downloadAvailable ? "available" : history || requested ? "preparing" : "not_requested",
+    createdAt: text(row.created_at),
+    updatedAt: text(row.updated_at)
+  };
+}
+
+export function mapCustomerOrderLines(
+  rows: readonly Row[],
+  moneyLines: readonly CanonicalOrderMoneyLine[],
+  currency: string,
+  presentation: CustomerOrderLinePresentationPort
+): AccountOrderLine[] {
+  return rows.map((row, index) => {
+    const money = moneyLines[index],
+      total = money?.catalogTotal ?? Number(row.total_cents ?? 0),
+      list = lineListTotalMinor(record(row.product_snapshot)),
+      saving = list !== null && list > total;
+    return {
+      lineId: text(row.id),
+      skuId: nullableText(row.sku_id),
+      ...presentation.display(row),
+      quantity: Number(row.quantity),
+      unitPrice: customerOrderMoney(money?.catalogUnit ?? row.unit_price_cents, currency),
+      total: customerOrderMoney(total, currency),
+      listTotal: saving ? customerOrderMoney(list, currency) : null,
+      discount: saving ? customerOrderMoney(list - total, currency) : null
+    };
+  });
+}
+
+export function lineListTotalMinor(snapshot: Row): number | null {
+  const components = record(snapshot.quoteLine).pricingComponents;
+  if (!Array.isArray(components)) return null;
+  let result = 0, found = false;
+  for (const value of components) {
+    const component = record(value);
+    if (component.componentType === "base_unit") {
+      result += Number(component.amountMinor ?? 0);
+      found = true;
+    }
+  }
+  return found ? result : null;
+}
+
+export function customerOrderMoney(value: unknown, currency: string) {
+  return { amountMinor: Number(value ?? 0), currency };
+}
+
+export function toOrderMoneyHeader(row: Row): OrderMoneyHeaderRow {
+  return {
+    id: text(row.id),
+    currency: text(row.currency),
+    subtotal_cents: Number(row.subtotal_cents),
+    discount_cents: Number(row.discount_cents),
+    shipping_cents: Number(row.shipping_cents),
+    shipping_discount_cents: Number(row.shipping_discount_cents ?? 0),
+    tax_cents: Number(row.tax_cents),
+    total_cents: Number(row.total_cents)
+  };
+}
+
+export function toOrderMoneyItem(row: Row): OrderMoneyItemRow {
+  const number = (value: unknown) => typeof value === "number" ? value : null;
+  return {
+    id: text(row.id),
+    quantity: Number(row.quantity),
+    unit_price_cents: Number(row.unit_price_cents),
+    total_cents: Number(row.total_cents),
+    discount_allocated_cents: number(row.discount_allocated_cents),
+    effective_total_cents: number(row.effective_total_cents),
+    effective_net_cents: number(row.effective_net_cents),
+    vat_rate_bps: Number(row.vat_rate_bps)
+  };
+}
+
+function text(value: unknown): string {
+  return typeof value === "string" ? value : "";
+}
+
+function nullableText(value: unknown): string | null {
+  return typeof value === "string" && value ? value : null;
+}
+
+function record(value: unknown): Row {
+  return value && typeof value === "object" && !Array.isArray(value) ? value as Row : {};
+}

package/src/account-support/paymentMethodComposition.ts

@@ -0,0 +1,8 @@
+import type { MethodSetupInput, MethodSetupPort, MethodSetupResult } from "./contracts/index.js";
+
+/** M07 collection only; ready, replayed and unsupported remain the owner's result. */
+export function createPaymentMethodComposition<Handoff>(port: MethodSetupPort<Handoff>): {
+  execute(userId: string, request: MethodSetupInput): Promise<MethodSetupResult<Handoff>>;
+} {
+  return { execute(_userId, request) { return port.setupMethod(request); } };
+}

package/src/account-support/postgresOperatorAuthority.ts

@@ -0,0 +1,92 @@
+import type { NativeOperatorAuthorityPort } from "./contracts/index.js";
+import { nativeSubscriptionCommand, leadAbsorption, recoveryResult, operatorRecoveryMaterial,
+  type OperatorAuthorityOptions, CustomerSupportCommandRequiresHumanError, CustomerSupportOperatorInactiveError,
+  CustomerSupportCommandInvalidError, CustomerSupportCommandIdempotencyConflictError, OperatorSubscriptionAuthorityUnavailableError } from "./operatorAuthority.js";
+
+/** Narrow structural subset of a query executor; the host owns connection and transaction. */
+export interface OperatorQueryExecutor {
+  query(sql: string, values?: unknown[]): Promise<{ rows: Record<string, unknown>[] }>;
+}
+export interface OperatorTransactionExecutor {
+  run<T>(work: (executor: OperatorQueryExecutor) => Promise<T>): Promise<T>;
+}
+export const OPERATOR_AUTHORITY_UNAVAILABLE = {
+  outcome: "refused", refusalCode: "operator_subscription_authority_unavailable",
+} as const;
+/** Native SQLSTATE mapping preserves the existing direct adapter's opaque fallback. */
+function nativeCommandFailure(error: unknown, fallback: string): Error {
+  const raw = (error ?? {}) as { code?: unknown; message?: unknown };
+  const code = typeof raw.code === "string" ? raw.code : "";
+  const message = typeof raw.message === "string" ? raw.message : "";
+  if (message.includes("customer_support_command_requires_human")) return new CustomerSupportCommandRequiresHumanError();
+  if (code === "42501" || message.includes("communications_operator_inactive")) return new CustomerSupportOperatorInactiveError();
+  if (code === "22023" || /customer_support_(subscription_command|absorb_lead)_invalid/.test(message)) return new CustomerSupportCommandInvalidError();
+  if (code === "23505" || message.includes("customer_support_idempotency_conflict")) return new CustomerSupportCommandIdempotencyConflictError();
+  if (code === "42883" || /does not exist/i.test(message)) return new OperatorSubscriptionAuthorityUnavailableError();
+  return new Error(fallback);
+}
+export function createPostgresOperatorAuthority(lane: OperatorTransactionExecutor, options: OperatorAuthorityOptions): NativeOperatorAuthorityPort {
+  const operatorId = options.operatorId.trim();
+  if (!operatorId) throw new Error("customer_support_operator_required");
+  const check = (input: { operatorId: string }) => {
+    if (input.operatorId !== operatorId) throw new Error("customer_support_operator_scope_mismatch");
+  };
+  const call = async (sql: string, values: unknown[], fallback: string): Promise<unknown> => {
+    try {
+      return await lane.run(async executor => {
+        const { rows } = await executor.query(sql, values);
+        if (rows.length !== 1 || !("result" in rows[0]!)) throw new Error("customer_support_routine_response_invalid");
+        return rows[0]!.result;
+      });
+    } catch (error) {
+      throw nativeCommandFailure(error, fallback);
+    }
+  };
+  return {
+    async applySubscriptionAction(input) {
+      check(input);
+      if (input.subscriptionAction === "change_shipping_address") return OPERATOR_AUTHORITY_UNAVAILABLE;
+      const result = await call("SELECT public.customer_support_apply_subscription_action_v1($1,$2,$3,$4,$5,$6,$7) AS result", [
+        operatorId, input.subscriptionId, input.subscriptionAction, input.payload ?? {}, input.expectedVersion,
+        input.idempotencyKey, new Date(options.now()).toISOString(),
+      ], "customer_support_subscription_command_failed");
+      return nativeSubscriptionCommand(result);
+    },
+    async correctSubjectEmail(input) { check(input); return OPERATOR_AUTHORITY_UNAVAILABLE; },
+    async correctSubjectPhone(input) { check(input); return OPERATOR_AUTHORITY_UNAVAILABLE; },
+    async linkSubjectAccount(input) { check(input); return OPERATOR_AUTHORITY_UNAVAILABLE; },
+    async absorbLead(input) {
+      check(input);
+      const result = await call("SELECT public.customer_support_absorb_lead_v1($1,$2,$3,$4,$5,$6) AS result", [
+        operatorId, input.customerId, input.leadId, input.expectedLeadEmail, input.idempotencyKey, new Date(options.now()).toISOString(),
+      ], "customer_support_lead_absorption_failed");
+      return leadAbsorption(result);
+    },
+    async issueRecovery(input) {
+      check(input);
+      const material = await operatorRecoveryMaterial(input, options);
+      // Preserve recovery's special conflict mapping and opaque non-conflict failure.
+      let result: unknown;
+      try {
+        result = await lane.run(async executor => {
+          const { rows } = await executor.query("SELECT public.customer_support_issue_recovery($1,$2,$3,$4,$5,$6,$7,$8) AS result", [
+            operatorId, input.subjectId, input.caseId, input.idempotencyKey, material.payloadFingerprint,
+            material.tokenHash, material.expiresAt, material.recoveryPath,
+          ]);
+          if (rows.length !== 1 || !("result" in rows[0]!)) throw new Error("customer_support_routine_response_invalid");
+          return rows[0]!.result;
+        });
+      } catch (error) {
+        const raw = (error ?? {}) as { code?: unknown; message?: unknown };
+        if (typeof raw.message === "string" && raw.message.includes("customer_support_command_requires_human")) {
+          throw new CustomerSupportCommandRequiresHumanError();
+        }
+        if (raw.code === "23505" || (typeof raw.message === "string" && raw.message.includes("idempotency_conflict"))) {
+          return { outcome: "conflict", conflictCode: "idempotency_conflict" };
+        }
+        throw new Error("customer_support_recovery_failed");
+      }
+      return recoveryResult(result);
+    },
+  };
+}

package/src/account-support/selfService.ts

@@ -0,0 +1,83 @@
+import type { AccountSupportLaneUnavailable, SelfServiceCommandFacade, SelfServiceCommandFacadeInput } from "./contracts/index.js";
+
+const HOST_BINDING_REQUIRED: AccountSupportLaneUnavailable<"host_binding_required"> = Object.freeze({ supported: false, refusalCode: "host_binding_required" });
+
+/** Neutral per-request graph selection. The host supplies all owner implementations. */
+export function createSelfServiceCommandFacade<Request extends { subscriptionId: string; action: string }, PreviewRequest, Preview, Receipt,
+  ProfileRequest, ProfileResult, MethodRequest, MethodResult, CommerceRequest, CommerceResult, RecoveryRequest, RecoveryResult, ControlSnapshot = unknown>(
+  input: SelfServiceCommandFacadeInput<Request, PreviewRequest, Preview, Receipt,
+    ProfileRequest, ProfileResult, MethodRequest, MethodResult, CommerceRequest, CommerceResult, RecoveryRequest, RecoveryResult, ControlSnapshot>,
+): SelfServiceCommandFacade<Request, PreviewRequest, Preview, Receipt,
+  ProfileRequest, ProfileResult, MethodRequest, MethodResult, CommerceRequest, CommerceResult, RecoveryRequest, RecoveryResult, ControlSnapshot> {
+  const context = { ...input.context }, native = input.nativeLegacySubscription;
+  function requireMethods(lane: object | undefined, methods: string[]) {
+    if (lane !== undefined && (!lane || methods.some(method => typeof (lane as Record<string, unknown>)[method] !== "function"))) {
+      throw new Error("customer_self_service_lane_configuration_required");
+    }
+  }
+  requireMethods(input.managedSubscription, ["previewAction", "applyAction"]);
+  requireMethods(native, ["ownershipRefusal"]);
+  if (native) {
+    if (!native.explicitPause || !native.control) throw new Error("customer_self_service_lane_configuration_required");
+    requireMethods(native.explicitPause, ["applyAction"]);
+    requireMethods(native.control, ["applyAction", "previewAction", "hasSubscription", "getSnapshot"]);
+  }
+  requireMethods(input.nativeRawSubscription, ["preview", "apply"]);
+  requireMethods(input.nativeSubscription, ["preview", "apply"]);
+  requireMethods(input.profile, ["updateProfile"]);
+  requireMethods(input.paymentMethod, ["execute"]);
+  requireMethods(input.commerce, ["execute"]);
+  requireMethods(input.recovery, ["startPaymentRecovery"]);
+  if ((!input.paymentMethod && input.capabilities.paymentMethodSetup.supported)
+    || (!input.commerce && (input.capabilities.commerceRecovery.supported || input.capabilities.configuredPurchase.supported))
+    || (!(input.managedSubscription || native || input.nativeRawSubscription || input.nativeSubscription)
+      && (input.capabilities.subscriptions.genericBundleCommands.supported || input.capabilities.subscriptions.commandBoundReceipts.supported))) {
+    throw new Error("customer_self_service_lane_configuration_required");
+  }
+  if (input.capabilities.graph !== context.graph
+    || (input.managedSubscription && context.graph !== "managed")
+    || ((native || input.nativeRawSubscription || input.nativeSubscription) && context.graph !== "native")) {
+    throw new Error("customer_graph_mismatch");
+  }
+  function verify(principalId: string, clientId: string) {
+    if (principalId !== context.principalId || clientId !== context.clientId) throw new Error("customer_principal_mismatch");
+  }
+  const managed = input.managedSubscription, raw = input.nativeRawSubscription, typed = input.nativeSubscription;
+  const profile = input.profile, method = input.paymentMethod, commerce = input.commerce, recovery = input.recovery;
+  const methodUnavailable = input.capabilities.paymentMethodSetup.supported ? undefined : input.capabilities.paymentMethodSetup;
+  const commerceUnavailable = input.capabilities.commerceRecovery.supported ? undefined : input.capabilities.commerceRecovery;
+  return {
+    capabilities: input.capabilities,
+    managedSubscription: {
+      async previewAction(userId, request) { verify(userId, context.clientId); return managed ? managed.previewAction(userId, request) : HOST_BINDING_REQUIRED; },
+      async applyAction(userId, request) { verify(userId, context.clientId); return managed ? managed.applyAction(userId, request) : HOST_BINDING_REQUIRED; },
+    },
+    nativeLegacySubscription: {
+      async previewAction(userId, request) { verify(userId, context.clientId); return native ? native.control.previewAction(userId, request) : HOST_BINDING_REQUIRED; },
+      async applyAction(userId, request) {
+        verify(userId, context.clientId);
+        if (!native) return HOST_BINDING_REQUIRED;
+        if (request.action === "pause") return native.explicitPause.applyAction(userId, request);
+        if (request.action !== "update_bundle") return native.control.applyAction(userId, request);
+        const canonical = { ...request, subscriptionId: request.subscriptionId.toLowerCase() };
+        if (!await native.control.hasSubscription(userId, canonical.subscriptionId)) throw native.ownershipRefusal();
+        return native.control.applyAction(userId, canonical);
+      },
+    },
+    subscriptionControl: {
+      async getSnapshot(userId) { verify(userId, context.clientId); return native ? native.control.getSnapshot(userId) : HOST_BINDING_REQUIRED; },
+    },
+    nativeRawSubscription: {
+      async preview(command) { verify(command.actorId, command.clientId); return raw ? raw.preview(command) : HOST_BINDING_REQUIRED; },
+      async apply(command) { verify(command.actorId, command.clientId); return raw ? raw.apply(command) : HOST_BINDING_REQUIRED; },
+    },
+    nativeSubscription: {
+      async preview(command) { verify(command.actor.actorId, command.actor.clientId); return typed ? typed.preview(command) : HOST_BINDING_REQUIRED; },
+      async apply(command) { verify(command.actor.actorId, command.actor.clientId); return typed ? typed.apply(command) : HOST_BINDING_REQUIRED; },
+    },
+    profile: { async updateProfile(userId, request) { verify(userId, context.clientId); return profile ? profile.updateProfile(userId, request) : HOST_BINDING_REQUIRED; } },
+    paymentMethod: { async execute(userId, request) { verify(userId, context.clientId); return method ? method.execute(userId, request) : methodUnavailable!; } },
+    commerce: { async execute(userId, request) { verify(userId, context.clientId); return commerce ? commerce.execute(userId, request) : commerceUnavailable!; } },
+    recovery: { async startPaymentRecovery(userId, request) { verify(userId, context.clientId); return recovery ? recovery.startPaymentRecovery(userId, request) : HOST_BINDING_REQUIRED; } },
+  };
+}

package/src/account-support/subscriptionCommandCodec.ts

@@ -0,0 +1,48 @@
+import type { CustomerContext, LegacySubscriptionRequest, NativePreviewProjection, NativeSubscriptionCommand, NativeSubscriptionPreview, RawSubscriptionCommands, SubscriptionDriver } from "./contracts/index.js";
+
+/** Encode only verified identity and the host's resolved request; no verb aliases. */
+export function encodeNativeSubscriptionCommand<Action extends string, Payload extends Record<string, unknown>>(
+  context: CustomerContext, request: LegacySubscriptionRequest<Action, Payload>, now: string,
+): NativeSubscriptionCommand {
+  return { actorId: context.principalId, clientId: context.clientId, idempotencyKey: request.idempotencyKey,
+    subscriptionId: request.subscriptionId, action: request.action, payload: request.payload, now };
+}
+
+export function decodeNativeSubscriptionPreview<Preview>(result: Record<string, unknown>, project: (record: NativeSubscriptionPreview) => Preview): NativePreviewProjection<Preview> {
+  if (result.status !== "previewed") return { kind: "owner", result };
+  if (result.canApply !== true
+    || !Number.isSafeInteger(result.templateVersion) || Number(result.templateVersion) < 1
+    || typeof result.quoteHash !== "string" || !/^[a-f0-9]{64}$/.test(result.quoteHash)
+    || typeof result.quoteExpiresAt !== "string" || !Number.isFinite(Date.parse(result.quoteExpiresAt))
+    || !Number.isSafeInteger(result.currentTotalMinor) || Number(result.currentTotalMinor) < 0
+    || !Number.isSafeInteger(result.newTotalMinor) || Number(result.newTotalMinor) < 0
+    || !Array.isArray(result.lines) || result.lines.length === 0 || !result.lines.every(line =>
+      line !== null && typeof line === "object" && typeof line.variantId === "string"
+      && Number.isSafeInteger(line.quantity) && line.quantity > 0 && typeof line.isAddon === "boolean"
+      && Number.isSafeInteger(line.sortOrder) && line.sortOrder >= 0
+      && Number.isSafeInteger(line.unitPriceMinor) && line.unitPriceMinor >= 0 && typeof line.currency === "string")
+    || result.priceAgreementPolicy === null || typeof result.priceAgreementPolicy !== "object"
+    || !("kind" in result.priceAgreementPolicy) || result.priceAgreementPolicy.kind !== "lock_until_edit"
+    || !("proration" in result.priceAgreementPolicy) || result.priceAgreementPolicy.proration !== "none"
+    || !("cycleEffect" in result.priceAgreementPolicy) || result.priceAgreementPolicy.cycleEffect !== "future_unlocked_cycles_only") {
+    throw new Error("subscription_command_preview_invalid");
+  }
+  return { kind: "projected", preview: project(result as NativeSubscriptionPreview) };
+}
+
+/** Preview and apply are separate transactions. Apply never creates a quote. */
+export function createNativeSubscriptionDriver<Action extends string, Payload extends Record<string, unknown>, Preview>(input: {
+  owner: RawSubscriptionCommands;
+  now(): string;
+  previewProjection(record: NativeSubscriptionPreview): Preview;
+}): SubscriptionDriver<LegacySubscriptionRequest<Action, Payload>, NativePreviewProjection<Preview>, Record<string, unknown>> {
+  return {
+    async preview(context, request) {
+      const command = encodeNativeSubscriptionCommand(context, request, input.now());
+      const payload = { ...command.payload };
+      delete payload.acceptedQuoteHash;
+      return decodeNativeSubscriptionPreview(await input.owner.preview({ ...command, payload }), input.previewProjection);
+    },
+    apply(context, request) { return input.owner.apply(encodeNativeSubscriptionCommand(context, request, input.now())); },
+  };
+}

package/src/commerce/adapters/managed/commerceOmsControlPlane.ts

@@ -0,0 +1,80 @@
+import type { AdminOmsOrderListItem } from "../../oms/omsContracts.js";
+import {
+OMS_CONTROL_PLANE_VERSION,
+omsControlPlaneActions,
+omsControlPlaneDetailResponseSchema,
+omsControlPlaneListResponseSchema,
+type CommerceOmsControlPlanePort,
+type OmsControlPlaneOrder,
+} from "../../oms/omsControlPlane.js";
+import type { CommerceOmsReadPort } from "../../oms/omsPorts.js";
+
+export function createManagedCommerceOmsControlPlanePort(
+  managedPort: CommerceOmsReadPort,
+): CommerceOmsControlPlanePort {
+  return {
+    async listOrders(request) {
+      const result = await managedPort.listOrders({
+        page: request.page,
+        pageSize: request.pageSize,
+        status: request.status,
+        sort: "created_desc",
+      });
+      return omsControlPlaneListResponseSchema.parse({
+        contractVersion: OMS_CONTROL_PLANE_VERSION,
+        orders: result.orders.map(mapOrder),
+        totalCount: result.totalCount,
+        page: result.page,
+        pageSize: result.pageSize,
+      });
+    },
+    async getOrderDetail(request) {
+      const result = await managedPort.getOrderDetail({ orderId: request.orderId });
+      if (!result) return null;
+      const operation = (type: string) => {
+        if (type === "hold_created" || type === "hold_released") return type;
+        if (type === "order_cancelled_manual") return "order_cancelled" as const;
+        if (type === "order_marked_refunded") return "order_refunded" as const;
+        return null;
+      };
+      return omsControlPlaneDetailResponseSchema.parse({
+        contractVersion: OMS_CONTROL_PLANE_VERSION,
+        order: mapOrder(result.order),
+        holds: result.order.holds.map((hold) => ({
+          id: hold.id,
+          status: hold.status,
+          reason: hold.reason,
+          note: hold.note,
+          createdAt: hold.createdAt,
+          releasedAt: hold.releasedAt,
+        })),
+        operations: result.order.operations.flatMap((entry) => {
+          const action = operation(entry.type);
+          return action ? [{
+            id: entry.id,
+            action,
+            holdId: entry.holdId,
+            actorId: entry.actorUserId,
+            occurredAt: entry.occurredAt,
+          }] : [];
+        }),
+      });
+    },
+  };
+}
+
+function mapOrder(order: AdminOmsOrderListItem): OmsControlPlaneOrder {
+  return {
+    orderId: order.orderId,
+    status: order.status,
+    sourceKind: order.sourceKind ?? "storefront",
+    sourceOrderRef: order.sourceOrderRef ?? null,
+    money: order.total,
+    shipmentStatus: order.fulfillmentStatus,
+    activeHoldCount: order.activeHoldCount,
+    activeHoldReasons: order.activeHoldReasons,
+    actions: omsControlPlaneActions(order.status, order.activeHoldCount),
+    createdAt: order.createdAt,
+    updatedAt: order.updatedAt,
+  };
+}