@openlup/platform 0.26.0 → 0.27.0

package/src/commerce/server/outboxShipmentExceptionEmailHandler.ts

@@ -0,0 +1,73 @@
+import type { CommerceEmailRuntime } from "./emailRuntime.js";
+import { z } from "zod";
+import { COMMERCE_SHIPMENT_EXCEPTION_EVENT_TYPE } from "../outboxEventSchemas.js";
+import type {
+  OutboxEventRow,
+  OutboxHandler,
+  OutboxHandlerOutcome,
+} from "../outboxDispatchContracts.js";
+import {
+  OUTBOX_SHIPMENT_EXCEPTION_TEMPLATE_SLUG,
+  type OrderRecipientPort,
+  type TransactionalEmailPort,
+} from "../outboxOrderDraftEmailPorts.js";
+
+export { OUTBOX_SHIPMENT_EXCEPTION_TEMPLATE_SLUG };
+
+const HANDLER_TIMEOUT_MS = 10_000;
+
+export const outboxShipmentExceptionEmailDescriptor = Object.freeze({
+  eventType: COMMERCE_SHIPMENT_EXCEPTION_EVENT_TYPE, timeoutMs: HANDLER_TIMEOUT_MS,
+});
+
+const payloadSubsetSchema = z
+  .object({
+    orderUuid: z.guid(),
+    orderId: z.string().min(1),
+    customerNotification: z.literal("shipment_exception").optional(),
+  })
+  .passthrough();
+
+export function createOutboxShipmentExceptionEmailHandler<Locale extends string>(deps: {
+  runtime: Pick<CommerceEmailRuntime<Locale>, "mapSendOutcome" | "parseOutboxPayload" | "resolveLocale">;
+  emailPort: TransactionalEmailPort<Locale>;
+  recipientPort: OrderRecipientPort;
+}): OutboxHandler {
+  return {
+    ...outboxShipmentExceptionEmailDescriptor,
+    async handle(row: OutboxEventRow, signal: AbortSignal): Promise<OutboxHandlerOutcome> {
+      const parsed = deps.runtime.parseOutboxPayload(payloadSubsetSchema, row.payload);
+      if (parsed.ok === false) {
+        return parsed.outcome;
+      }
+
+      if (parsed.data.customerNotification !== "shipment_exception") {
+        return { kind: "processed", detail: { skipped: "internal_fulfillment_hold" } };
+      }
+
+      const recipient = await deps.recipientPort.resolve(parsed.data.orderUuid, signal);
+      if (recipient === null) {
+        return { kind: "processed", detail: { skipped: "recipient_unresolved" } };
+      }
+
+      const alreadySent = await deps.emailPort.findExistingSend(
+        OUTBOX_SHIPMENT_EXCEPTION_TEMPLATE_SLUG,
+        row.id,
+      );
+      if (alreadySent) {
+        return { kind: "processed", detail: { dedupe: "email_already_sent" } };
+      }
+
+      const outcome = await deps.emailPort.sendShipmentExceptionNotice({
+        to: recipient.email,
+        firstName: recipient.firstName,
+        orderId: parsed.data.orderId,
+        outboxEventId: row.id,
+        locale: deps.runtime.resolveLocale(recipient.country ?? null),
+        signal,
+      });
+
+      return deps.runtime.mapSendOutcome(outcome);
+    },
+  };
+}

package/src/commerce/server/referenceCheckoutHandler.ts

@@ -0,0 +1,87 @@
+import type { z } from "zod";
+import type { HttpRequest, HttpResponse } from "../../http/index.js";
+import type { BffResponder } from "../../bff/index.js";
+import { REFERENCE_CHECKOUT_V1 } from "../checkoutCommandSchemas.js";
+import { CommerceRuntimeConflictError, CommerceRuntimePersistenceError } from "../runtimeErrors.js";
+interface ReferenceRuntime { runtime: { orderId: string; clientId: string; finalizedReplayed: boolean; total: { amountMinor: number; currency: string }; payment: { paymentIntentId: string; paymentAttemptId: string | null; status: string; attemptStatus: string | null } } }
+interface ReferenceSettlement { paymentResult: { status: string; replayed: boolean } }
+
+export function createReferenceCheckoutHandler<Command, Runtime extends ReferenceRuntime, Settlement extends ReferenceSettlement, Response>({
+  startCheckout,
+  checkRateLimit,
+  checkRiskBlocklist,
+  admitProfile, responder, requestSchema, responseSchema,
+}: {
+  startCheckout(command: Command): Promise<{ runtime: Runtime; settlement: Settlement | null; persistence: { replayed: boolean } }>;
+  checkRateLimit(req: HttpRequest, command: Command): Promise<{ allowed: boolean }>;
+  checkRiskBlocklist?(req: HttpRequest, command: Command): Promise<{ blocked: boolean }>;
+  admitProfile(command: Command): boolean; responder: BffResponder;
+  requestSchema: z.ZodType<{ command: Command }>; responseSchema: z.ZodType<Response>;
+}) {
+  const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = responder;
+  return async function handler(req: HttpRequest, res: HttpResponse): Promise<void> {
+    if (req.method !== "POST") {
+      sendMethodNotAllowed(res, ["POST"]);
+      return;
+    }
+
+    const request = requestSchema.safeParse(req.body ?? {});
+    if (!request.success) {
+      sendBffError(res, "BAD_REQUEST", "Invalid reference checkout request", {
+        details: request.error.flatten(),
+      });
+      return;
+    }
+
+    try {
+      if (!admitProfile(request.data.command)) {
+        sendBffError(res, "BAD_REQUEST", "Checkout command does not match the active reference profile");
+        return;
+      }
+      if (!(await checkRateLimit(req, request.data.command)).allowed) {
+        sendBffError(res, "RATE_LIMITED", "Reference checkout rate limit exceeded");
+        return;
+      }
+      if (checkRiskBlocklist && (await checkRiskBlocklist(req, request.data.command)).blocked) {
+        sendBffError(res, "FORBIDDEN", "Reference checkout cannot be completed");
+        return;
+      }
+
+      // Settlement is owned by the shared paid-order service, not by this
+      // handler: it is present exactly when that service settled the attempt,
+      // and absent when the runtime is still awaiting or already refused it.
+      const result = await startCheckout(request.data.command);
+      const settled = result.settlement;
+      const response = responseSchema.safeParse({
+        version: REFERENCE_CHECKOUT_V1,
+        orderId: result.runtime.runtime.orderId,
+        clientId: result.runtime.runtime.clientId,
+        paymentIntentId: result.runtime.runtime.payment.paymentIntentId,
+        paymentAttemptId: result.runtime.runtime.payment.paymentAttemptId,
+        paymentStatus: settled?.paymentResult.status ?? result.runtime.runtime.payment.status,
+        paymentAttemptStatus: settled
+          ? "succeeded"
+          : result.runtime.runtime.payment.attemptStatus,
+        replayed: result.persistence.replayed ||
+          result.runtime.runtime.finalizedReplayed ||
+          (settled?.paymentResult.replayed ?? false),
+        total: result.runtime.runtime.total,
+      });
+      if (!response.success) {
+        sendBffError(res, "INVALID_RESPONSE", "Reference checkout returned invalid response");
+        return;
+      }
+      sendBffSuccess(res, response.data, { contractVersion: REFERENCE_CHECKOUT_V1 });
+    } catch (error) {
+      if (error instanceof CommerceRuntimeConflictError) {
+        sendBffError(res, "CONFLICT", error.message, { details: error.details });
+        return;
+      }
+      if (error instanceof CommerceRuntimePersistenceError) {
+        sendBffError(res, "UPSTREAM_UNAVAILABLE", "Reference checkout persistence failed");
+        return;
+      }
+      sendBffError(res, "UPSTREAM_UNAVAILABLE", "Reference checkout failed");
+    }
+  };
+}

package/src/commerce/server/reservationSweepPort.ts

@@ -0,0 +1,67 @@
+export interface ReservationSweepCounts {
+  ordersChecked: number;
+  ordersExpired: number;
+  reservationsReleased: number;
+  skippedPaid: number;
+  skippedTerminal: number;
+  skippedSubscription: number;
+}
+
+export type ReservationSweepRpcClient = {
+  rpc(
+    name: string,
+    args: Record<string, unknown>,
+  ): PromiseLike<{ data: unknown; error: { message?: string } | null }>;
+};
+
+export interface RetryHoldSweepCounts {
+  holdsChecked: number;
+  holdsReleased: number;
+  skippedPaid: number;
+}
+
+export function createManagedReservationSweepPort(client: ReservationSweepRpcClient) {
+  return {
+    async sweep(input: { now: string; limit: number }): Promise<ReservationSweepCounts> {
+      const { data, error } = await client.rpc("commerce_sweep_expired_reservation_holds", {
+        p_idempotency_prefix: "commerce-reservation-sweep-run",
+        p_now: input.now,
+        p_limit: input.limit,
+      });
+      if (error) throw new Error(`rpc_sweep: ${error.message ?? "unknown"}`);
+      return readSweepCounts(data);
+    },
+    // Release-only: frees expired subscription_retry_window holds without
+    // touching the cycle order, subscription, or dunning case.
+    async sweepRetryHolds(input: { now: string; limit: number }): Promise<RetryHoldSweepCounts> {
+      const { data, error } = await client.rpc("commerce_sweep_expired_retry_holds", {
+        p_now: input.now,
+        p_limit: input.limit,
+      });
+      if (error) throw new Error(`rpc_retry_hold_sweep: ${error.message ?? "unknown"}`);
+      const sweep = (data as { retrySweep?: Record<string, unknown> } | null)?.retrySweep;
+      return {
+        holdsChecked: numberField(sweep, "holdsChecked"),
+        holdsReleased: numberField(sweep, "holdsReleased"),
+        skippedPaid: numberField(sweep, "skippedPaid"),
+      };
+    },
+  };
+}
+
+function readSweepCounts(data: unknown): ReservationSweepCounts {
+  const sweep = (data as { sweep?: Record<string, unknown> } | null)?.sweep;
+  return {
+    ordersChecked: numberField(sweep, "ordersChecked"),
+    ordersExpired: numberField(sweep, "ordersExpired"),
+    reservationsReleased: numberField(sweep, "reservationsReleased"),
+    skippedPaid: numberField(sweep, "skippedPaid"),
+    skippedTerminal: numberField(sweep, "skippedTerminal"),
+    skippedSubscription: numberField(sweep, "skippedSubscription"),
+  };
+}
+
+function numberField(record: Record<string, unknown> | undefined, key: string): number {
+  const value = record?.[key];
+  return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}

package/src/commerce/server/starterTermsPort.ts

@@ -0,0 +1,22 @@
+export interface StarterTermsDecision {
+    intervalDays: number;
+    steadyCadenceDays: number;
+    steadyUnits: number;
+    graduationSizeConstraint?: Record<string, unknown>;
+}
+
+export type StarterTermsRefusal = "basket_too_small" | "basket_not_admitted" | "demand_unknown";
+
+export type StarterTermsResolution =
+  | { kind: "terms"; terms: StarterTermsDecision }
+  | { kind: "refused"; reason: StarterTermsRefusal };
+
+export interface StarterTermsInput<Intent, Snapshot> {
+  intent: Intent;
+    authoritativeQuote: Snapshot;
+    offerVersion?: string;
+}
+
+export interface StarterTermsPort<Intent, Snapshot> {
+  resolve(input: StarterTermsInput<Intent, Snapshot>): Promise<StarterTermsResolution>;
+}

package/src/commerce/server/supabaseCommerceReturnsPort.ts

@@ -0,0 +1,81 @@
+import type {
+  CommerceReturnsPort,
+  ReturnLifecycleResult,
+  ReturnRequestCreateInput,
+} from "../commerceReturnsPort.js";
+
+/** Returns request/approve/reject only. Restock and refund fields record intent; no receive, restock or refund execution. */
+export interface CommerceReturnsRpcClient {
+  rpc(
+    fn: string,
+    params: Record<string, unknown>,
+  ): PromiseLike<{
+    data: unknown;
+    error: { code?: string; message?: string } | null;
+  }>;
+}
+
+function parseResult(fn: string, data: unknown): ReturnLifecycleResult {
+  const result = (data ?? {}) as Record<string, unknown>;
+  if (
+    typeof result.returnRequestId !== "string" ||
+    typeof result.status !== "string"
+  ) {
+    throw new Error(`${fn}_unexpected_result`);
+  }
+  return {
+    returnRequestId: result.returnRequestId,
+    status: result.status,
+    replayed: result.replayed === true,
+  };
+}
+
+/** Returns request/approve/reject only. Restock and refund fields record intent; no receive, restock or refund execution. */
+export function createSupabaseCommerceReturnsPort<Reason extends string = ReturnRequestCreateInput["reasonCode"]>(
+  client: CommerceReturnsRpcClient,
+): CommerceReturnsPort<Reason> {
+  async function call(
+    fn: string,
+    params: Record<string, unknown>,
+  ): Promise<ReturnLifecycleResult> {
+    const { data, error } = await client.rpc(fn, params);
+    if (error) throw new Error(`${fn}_failed:${error.code ?? "unknown"}`);
+    return parseResult(fn, data);
+  }
+
+  return {
+    createRequest(input) {
+      return call("commerce_return_request_create", {
+        p_idempotency_key: input.idempotencyKey,
+        p_order_id: input.orderId,
+        p_lines: input.lines.map((line) => ({
+          orderItemId: line.orderItemId,
+          sku: line.sku ?? null,
+          quantity: line.quantity,
+          restockDisposition: line.restockDisposition ?? "restock",
+        })),
+        p_reason_code: input.reasonCode,
+        p_customer_note: input.customerNote ?? null,
+        p_requested_by: input.requestedBy ?? null,
+      });
+    },
+    approve(input) {
+      return call("commerce_return_approve", {
+        p_idempotency_key: input.idempotencyKey,
+        p_return_request_id: input.returnRequestId,
+        p_approved_by: input.actorUserId ?? null,
+        p_refund_mode: input.refundMode,
+        p_refund_amount_cents: input.refundAmountCents ?? null,
+        p_admin_note: input.adminNote ?? null,
+      });
+    },
+    reject(input) {
+      return call("commerce_return_reject", {
+        p_idempotency_key: input.idempotencyKey,
+        p_return_request_id: input.returnRequestId,
+        p_approved_by: input.actorUserId ?? null,
+        p_admin_note: input.adminNote ?? null,
+      });
+    },
+  };
+}

package/src/composition/commerceContribution.ts

@@ -0,0 +1,35 @@
+import type { Contribution, RequiredSchema } from "@openlup/core/readiness";
+
+/** Describe existing selected commerce callables; never install another executor. */
+export function createCommerceContribution(input: {
+  version: string;
+  requiredSchema: RequiredSchema;
+  commerce: Readonly<Record<string, ((...args: never[]) => unknown) | null>>;
+  handlers: Contribution["handlers"];
+  schedules: Contribution["schedules"];
+  routes: Contribution["routes"];
+}) {
+  for (const [kind, names] of [
+    ["handler", input.handlers.map(handler => handler.eventType)],
+    ["schedule", input.schedules.map(schedule => schedule.id)],
+    ["route", input.routes.map(route => route.id)],
+  ] as const) {
+    if (new Set(names).size !== names.length) throw new Error(`commerce_duplicate_${kind}`);
+  }
+  const contribution: Contribution = {
+    manifest: {
+      name: "@openlup/platform", version: input.version, kind: "rail",
+      module: { id: "commerce", kind: "capability", provides: ["./commerce", "./commerce/contracts", "./commerce/server"], dependsOn: [] },
+      emits: [], handles: input.handlers.map(handler => handler.eventType),
+      schedules: input.schedules.map(({ id, cadenceSeconds }) => ({ id, cadenceSeconds })), env: [],
+      requiredPorts: Object.keys(input.commerce), routes: input.routes.map(route => route.id), requiredSchema: input.requiredSchema,
+    },
+    handlers: input.handlers.map(({ eventType, timeoutMs }) => Object.freeze({ eventType, timeoutMs })), schedules: input.schedules, routes: input.routes,
+  };
+  return {
+    contributions: [contribution],
+    ports: Object.fromEntries(Object.entries(input.commerce).filter(([, fn]) => typeof fn === "function").map(([name, fn]) => [`@openlup/platform/commerce:${name}`, fn])),
+    routes: Object.fromEntries(input.routes.map(route => [`@openlup/platform/commerce:${route.id}`, route.handle])),
+    triggers: Object.fromEntries(input.schedules.map(schedule => [`@openlup/platform/commerce:${schedule.id}`, schedule.run])),
+  };
+}

package/src/composition/index.ts

@@ -21,3 +21,4 @@ export { createInventoryContribution } from "./inventoryContribution.js";
 export { createShippingContribution } from "./shippingContribution.js";
 export { createFulfillmentContribution } from "./fulfillmentContribution.js";
 export { createSubscriptionContribution } from "./subscriptionContribution.js";
+export { createCommerceContribution } from "./commerceContribution.js";

package/src/fulfillment/index.ts

@@ -1,7 +1,7 @@
 export { FULFILLMENT_STATUS_MAP, CANONICAL_LOCAL_FULFILLMENT_STATUSES, CUSTOMER_STEP_SEQUENCE, canonicalStatusToken, stepForToken, customerStepFromSignals, phaseIndexForStep, stepLabelKey, timelineLabelForStep, trackingPhaseKeyForStep, stepUsesTruckIcon } from "./statusMap.js";
 export { parseFulfillmentFact, parseFulfillmentTransitionConflict } from "./normalizedFulfillmentFacts.js";
 export { readFulfillmentCapabilities } from "./providerCapabilities.js";
-export { createOutboxOrderPaidFulfillmentHandler } from "./paidHandoff.js";
+export { createOutboxOrderPaidFulfillmentHandler, outboxOrderPaidFulfillmentDescriptor, parseOutboxPayload } from "./paidHandoff.js";
 export { collectPaidFulfillmentRecoveryCandidates } from "./paidFulfillmentRecovery.js";
 export { runFulfillmentDispatchWorker } from "./providerDispatchWorker.js";
 export { createFulfillmentCommandLedger } from "./providerCommandLedger.js";

package/src/fulfillment/paidHandoff.ts

@@ -9,7 +9,7 @@ import type { OrderPaidFulfillmentPort } from "./paidHandoffPorts.js";
 const COMMERCE_ORDER_PAID_EVENT_TYPE = "commerce.order.paid";
 const HANDLER_TIMEOUT_MS = 15_000;
 
-const outboxOrderPaidFulfillmentDescriptor = Object.freeze({
+export const outboxOrderPaidFulfillmentDescriptor = Object.freeze({
   eventType: COMMERCE_ORDER_PAID_EVENT_TYPE, timeoutMs: HANDLER_TIMEOUT_MS,
 });
 
@@ -113,7 +113,7 @@ export function createOutboxOrderPaidFulfillmentHandler(deps: {
 }
 
 function truncateReason(value: string): string { return value.length <= 300 ? value : `${value.slice(0, 300)}…`; }
-function parseOutboxPayload<T>(schema: import("zod").ZodType<T>, payload: unknown):
+export function parseOutboxPayload<T>(schema: import("zod").ZodType<T>, payload: unknown):
   { ok: true; data: T } | { ok: false; outcome: OutboxHandlerOutcome } {
   const parsed = schema.safeParse(payload);
   if (parsed.success) return { ok: true, data: parsed.data };

package/src/inventory/bindings.ts

@@ -1,7 +1,9 @@
+import { createManagedStockAvailability, type ManagedStockRpc } from "./managedStockAvailability.js";
 import type { z } from "zod";
 import { createPostgresAdminInventoryPort } from "./adminInventory.js";
 import type { InventoryMutationPort, InventoryReadPort } from "./ports.js";
 import type { NewPurchaseStockReadPort } from "./newPurchaseStockAvailability.js";
+import { createPostgresStockAvailability } from "./postgresStockAvailability.js";
 import { createInventorySubscriptionForecastResponseSchema } from "./schemas.js";
 
 export interface InventoryBindingDependencies {
@@ -12,6 +14,8 @@ export interface InventoryBindingDependencies {
     readPort: InventoryReadPort; mutationPort: InventoryMutationPort;
   } | null;
   newPurchaseStockReadPort?: NewPurchaseStockReadPort | null;
+  stockSourceKey?: string;
+  stockRpc?: ManagedStockRpc;
   now?: () => string;
 }
 
@@ -31,18 +35,22 @@ export function createInventoryBindings(deps: InventoryBindingDependencies): Inv
   });
   if (!deps.provider?.providerSchema?.safeParse(deps.provider.stockMasterProvider).success) return refused("inventory_provider_mismatch");
   let readPort: InventoryReadPort, mutationPort: InventoryMutationPort;
+  let stockRead: NewPurchaseStockReadPort | null | undefined;
   if (deps.dataKind === "postgres") {
     if (!deps.executor || typeof deps.executor.query !== "function") return refused("inventory_executor_required");
     readPort = mutationPort = createPostgresAdminInventoryPort(deps.executor, deps.provider, deps.now);
+    stockRead = deps.stockSourceKey?.trim()
+      ? createPostgresStockAvailability(deps.executor, { sourceKey: deps.stockSourceKey, now: deps.now ?? (() => new Date().toISOString()) }).readPort
+      : null;
   } else if (deps.dataKind === "supabase") {
     const store = deps.createManagedStore?.(deps.provider);
     if (!store) return refused("inventory_managed_store_required");
     ({ readPort, mutationPort } = store);
+    stockRead = deps.newPurchaseStockReadPort ?? (deps.stockRpc
+      ? createManagedStockAvailability(deps.stockRpc, { now: deps.now ?? (() => new Date().toISOString()) }) : null);
   } else return refused("inventory_store_incompatible");
   if (![readPort?.listStock, readPort?.listReservations, readPort?.checkAtp, readPort?.forecastSubscriptions, mutationPort?.adjustStock].every(fn => typeof fn === "function")) return refused("inventory_store_incompatible");
   const responseSchema = createInventorySubscriptionForecastResponseSchema(deps.provider.providerSchema);
-  const native = deps.dataKind === "postgres";
-  const stockRead = native ? null : deps.newPurchaseStockReadPort;
   const newPurchaseStockReadPort = typeof stockRead?.read === "function" ? stockRead : null;
   return {
     readPort: {
@@ -54,8 +62,8 @@ export function createInventoryBindings(deps: InventoryBindingDependencies): Inv
     mutationPort, newPurchaseStockReadPort,
     readiness: { ready: true, reason: null },
     unsupported: {
-      newPurchaseStockRead: native ? "inventory_native_new_purchase_stock_read_unsupported"
-        : newPurchaseStockReadPort ? null : "inventory_new_purchase_stock_reader_required",
+      newPurchaseStockRead: newPurchaseStockReadPort ? null : deps.dataKind === "postgres"
+        ? "inventory_stock_source_key_required" : "inventory_new_purchase_stock_reader_required",
     },
   };
 }

package/src/inventory/index.ts

@@ -22,3 +22,4 @@ export { INVENTORY_MIGRATIONS } from "./sql.js";
 export { createInventoryBindings, type InventoryBindingDependencies, type InventoryBindings } from "./bindings.js";
 export { createPostgresStockAvailability } from "./postgresStockAvailability.js";
 export type { NativeStockPromise } from "./postgresStockAvailability.js";
+export { createManagedStockAvailability, type ManagedStockRpc } from "./managedStockAvailability.js";

package/src/inventory/managedStockAvailability.ts

@@ -0,0 +1,23 @@
+import type { NewPurchaseStockReadPort } from "./newPurchaseStockAvailability.js";
+import { parseStockReadResponse } from "./stockReadResponse.js";
+
+/** Minimal service-role RPC seam; transport and credentials remain host-owned. */
+export interface ManagedStockRpc {
+  rpc(name: string, args: Record<string, unknown>): PromiseLike<{
+    data: unknown;
+    error: { message: string; code?: string } | null;
+  }>;
+}
+
+/** Read-only managed ATP preview with fixed subscription priority. */
+export function createManagedStockAvailability(client: ManagedStockRpc, options: { now: () => string }): NewPurchaseStockReadPort {
+  return {
+    async read(input) {
+      if (input.horizonDays !== 14 || input.excludeOrderId !== null) throw new Error("managed_stock_read_options_unsupported");
+      if (!input.skus.length) return new Map();
+      const { data, error } = await client.rpc("inventory_new_purchase_stock_read", { p_skus: input.skus, p_as_of: options.now() });
+      if (error) throw error;
+      return parseStockReadResponse(data);
+    },
+  };
+}

package/src/inventory/postgresStockAvailability.ts

@@ -1,4 +1,4 @@
-import type { NewPurchaseStockRow } from "./contracts/newPurchaseStock.js";
+import { parseStockReadResponse, stockObject as object, stockQuantity as quantity } from "./stockReadResponse.js";
 import type { NewPurchaseStockReadPort } from "./newPurchaseStockAvailability.js";
 
 interface StockQueryExecutor {
@@ -8,16 +8,6 @@ export interface NativeStockPromise {
   availableQuantity: number; forSaleQuantity: number; hardHoldQuantity: number;
   safetyQuantity: number; softSubscriptionDemandQuantity: number; channelExposureQuantity: number;
 }
-function object(value: unknown): Record<string, unknown> {
-  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("inventory_stock_response_invalid");
-  return value as Record<string, unknown>;
-}
-function quantity(value: unknown): number {
-  if ((typeof value !== "number" && typeof value !== "string") || String(value).trim() === "") throw new Error("inventory_stock_quantity_invalid");
-  const n = Number(value);
-  if (!Number.isSafeInteger(n) || n < 0) throw new Error("inventory_stock_quantity_invalid");
-  return n;
-}
 /** Native read-only ATP. The fixed 14-day priority cannot be waived by a new
  * purchase caller. Only the fenced native SQL allocator uses the renewal exemption. */
 export function createPostgresStockAvailability(executor: StockQueryExecutor, options: { sourceKey: string; now: () => string }): {
@@ -38,16 +28,7 @@ export function createPostgresStockAvailability(executor: StockQueryExecutor, op
         if (!input.skus.length) return new Map();
         const value = (await executor.query(`SELECT public.inventory_new_purchase_stock_read(
           $1::text,$2::jsonb,$3::timestamptz) AS response`, [options.sourceKey, JSON.stringify(input.skus), options.now()])).rows[0]?.response;
-        if (!Array.isArray(value)) throw new Error("inventory_stock_response_invalid");
-        return new Map(value.map(value => {
-          const row = object(value);
-          if (typeof row.sku !== "string" || !["provider", "missing"].includes(String(row.source)) || typeof row.stale !== "boolean") throw new Error("inventory_stock_response_invalid");
-          const result: NewPurchaseStockRow = { sku: row.sku, catalogSkuId: row.catalogSkuId == null ? null : String(row.catalogSkuId),
-            source: row.source as "provider" | "missing", providerForSale: row.providerForSale == null ? null : quantity(row.providerForSale),
-            activeHolds: quantity(row.activeHolds), safetyStock: quantity(row.safetyStock), available: quantity(row.available), stale: row.stale,
-            renewalDemand: quantity(row.renewalDemand), availableForNewPurchases: quantity(row.availableForNewPurchases), excludedOrderHolds: quantity(row.excludedOrderHolds) };
-          return [result.sku, result];
-        }));
+        return parseStockReadResponse(value);
       },
     },
   };

package/src/inventory/stockReadResponse.ts

@@ -0,0 +1,25 @@
+import type { NewPurchaseStockRow } from "./contracts/newPurchaseStock.js";
+
+export function stockObject(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("inventory_stock_response_invalid");
+  return value as Record<string, unknown>;
+}
+export function stockQuantity(value: unknown): number {
+  if ((typeof value !== "number" && typeof value !== "string") || String(value).trim() === "") throw new Error("inventory_stock_quantity_invalid");
+  const n = Number(value);
+  if (!Number.isSafeInteger(n) || n < 0) throw new Error("inventory_stock_quantity_invalid");
+  return n;
+}
+
+export function parseStockReadResponse(value: unknown): Map<string, NewPurchaseStockRow> {
+  if (!Array.isArray(value)) throw new Error("inventory_stock_response_invalid");
+  return new Map(value.map(value => {
+    const row = stockObject(value);
+    if (typeof row.sku !== "string" || !["provider", "missing"].includes(String(row.source)) || typeof row.stale !== "boolean") throw new Error("inventory_stock_response_invalid");
+    const result: NewPurchaseStockRow = { sku: row.sku, catalogSkuId: row.catalogSkuId == null ? null : String(row.catalogSkuId),
+      source: row.source as "provider" | "missing", providerForSale: row.providerForSale == null ? null : stockQuantity(row.providerForSale),
+      activeHolds: stockQuantity(row.activeHolds), safetyStock: stockQuantity(row.safetyStock), available: stockQuantity(row.available), stale: row.stale,
+      renewalDemand: stockQuantity(row.renewalDemand), availableForNewPurchases: stockQuantity(row.availableForNewPurchases), excludedOrderHolds: stockQuantity(row.excludedOrderHolds) };
+    return [result.sku, result];
+  }));
+}

package/src/pricing/browser/index.ts

@@ -0,0 +1,6 @@
+export { createCommerceQuotePrimitives } from "../quotePrimitives.js";
+export { acquisitionCapabilitySchema, acquisitionTermsExpectationSchema } from "../acquisitionTermsSchemas.js";
+/** @consumer src/domains/commerce/quoteContracts.ts */
+export { resolvedAcquisitionTermsSchema } from "../acquisitionTermsSchemas.js";
+/** @consumer src/domains/commerce/quoteContracts.ts */
+export { shippingTermsSchema } from "../../shipping/thresholdPolicy.js";

package/src/subscriptions/index.ts

@@ -31,8 +31,9 @@ export type { NativeSubscriptionCommand, NativeSubscriptionCommandBinding } from
 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.
+/** Managed SQL is exposed for service-role hosts; no StockWaitStorePort
+ * TypeScript adapter is composed for this graph. A NewPurchaseStockReadPort
+ * adapter is available in ../inventory for managed service-role hosts.
  * SQL behavior is proved by the managed pgTAP/real-PostgreSQL witnesses.
  */
 export const MANAGED_SUBSCRIPTION_STOCK_CAPABILITIES = Object.freeze({