@openlup/platform 0.17.0 → 0.18.0

package/src/communications/resend/index.ts

@@ -0,0 +1,350 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { createGuardedEmailTransport, type EmailEgressPolicy, type EmailEgressContext } from "../emailEgress.js";
+import type { EmailMessage, EmailSendResult, EmailTransport } from "../emailTransport.js";
+import { processEmailObservation, type EmailObservationPort } from "../emailObservation.js";
+import { runDeliveryReconciliation, type DeliveryReconciliationPort, type DeliveryReconciliationResult } from "../deliveryReconciliation.js";
+
+/** Opt-in Node sender. Every send obtains a fresh validated host egress decision. */
+export function createResendTransport(input: {
+  policy: EmailEgressPolicy;
+  environmentTagName: string;
+  fetch?: typeof fetch;
+}): EmailTransport {
+  return createGuardedEmailTransport({
+    providerKind: "resend",
+    policy: input.policy,
+    send: (message, context) => postResendEmail(message, context, input.environmentTagName, input.fetch ?? fetch),
+  });
+}
+
+const RESEND_ENDPOINT = "https://api.resend.com/emails";
+const PROVIDER_ERROR_MAX = 240;
+const PROVIDER_ERROR_CODE_MAX = 80;
+const EMAIL_ADDRESS_PATTERN = /[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/gi;
+
+function truncate(value: string, max: number): string {
+  return value.length > max ? `${value.slice(0, max - 1)}...` : value;
+}
+
+function sanitizeProviderText(value: string): string {
+  return truncate(value.replace(EMAIL_ADDRESS_PATTERN, "[email]").replace(/\s+/g, " ").trim(), PROVIDER_ERROR_MAX);
+}
+
+function sanitizeProviderCode(value: string): string {
+  return truncate(value.replace(/[^A-Za-z0-9._:-]/g, "_"), PROVIDER_ERROR_CODE_MAX);
+}
+
+function providerErrorFromBody(body: Record<string, unknown>, httpStatus: number): string {
+  const errField = body.error;
+  if (typeof errField === "string") return sanitizeProviderText(errField);
+  if (errField && typeof errField === "object") {
+    const message = (errField as Record<string, unknown>).message;
+    if (typeof message === "string") return sanitizeProviderText(message);
+  }
+  if (typeof body.message === "string") return sanitizeProviderText(body.message);
+  return `Resend HTTP ${httpStatus}`;
+}
+
+function providerErrorCodeFromBody(body: Record<string, unknown>): string | null {
+  const errField = body.error;
+  const errorRecord = errField && typeof errField === "object"
+    ? (errField as Record<string, unknown>)
+    : {};
+  const candidates = [
+    errorRecord.code,
+    errorRecord.name,
+    errorRecord.type,
+    body.code,
+    body.name,
+    body.type,
+  ];
+  const value = candidates.find((candidate) => typeof candidate === "string" && candidate.trim() !== "");
+  return typeof value === "string" ? sanitizeProviderCode(value) : null;
+}
+
+function providerErrorResponse(body: Record<string, unknown>, httpStatus: number): Record<string, unknown> {
+  const providerErrorMessage = providerErrorFromBody(body, httpStatus);
+  const providerErrorCode = providerErrorCodeFromBody(body);
+  return {
+    http_status: httpStatus,
+    provider_error_message: providerErrorMessage,
+    ...(providerErrorCode ? { provider_error_code: providerErrorCode } : {}),
+  };
+}
+
+async function postResendEmail(
+  input: EmailMessage, context: Readonly<EmailEgressContext>, environmentTagName: string, fetcher: typeof fetch,
+): Promise<EmailSendResult> {
+  const headers: Record<string, string> = {
+    Authorization: `Bearer ${context.credential}`,
+    "Content-Type": "application/json",
+  };
+  if (input.idempotencyKey !== undefined) headers["Idempotency-Key"] = input.idempotencyKey;
+  if (context.mode === "sandbox_sink") headers["X-Original-Recipient"] = context.intendedRecipient;
+  try {
+    const res = await fetcher(RESEND_ENDPOINT, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({
+        from: input.from,
+        to: [context.recipient],
+        subject: input.subject,
+        html: input.html,
+        ...(input.text === undefined ? {} : { text: input.text }),
+        ...(input.replyTo === undefined ? {} : { reply_to: input.replyTo }),
+        ...(input.attachments === undefined ? {} : { attachments: input.attachments }),
+        tags: [{
+          name: environmentTagName,
+          value: context.environmentTag,
+        }],
+      }),
+      signal: input.signal,
+    });
+    const parsed = await res.json().catch(() => ({}));
+    const body = typeof parsed === "object" && parsed !== null
+      ? (parsed as Record<string, unknown>)
+      : {};
+    if (!res.ok) {
+      const providerErrorMessage = providerErrorFromBody(body, res.status);
+      const providerErrorCode = providerErrorCodeFromBody(body);
+      return {
+        outcome: {
+          ok: false,
+          resendId: null,
+          httpStatus: res.status,
+          providerError: providerErrorMessage,
+          providerErrorCode,
+          aborted: false,
+          egressMode: context.mode,
+          egressReason: context.reason,
+        },
+        providerResponse: providerErrorResponse(body, res.status),
+      };
+    }
+    const id = typeof body.id === "string" ? body.id : null;
+    return {
+      outcome: {
+        ok: true,
+        resendId: id,
+        httpStatus: res.status,
+        providerError: null,
+        aborted: false,
+        egressMode: context.mode,
+        egressReason: context.reason,
+      },
+      providerResponse: { id },
+    };
+  } catch (err) {
+    const aborted =
+      input.signal?.aborted === true ||
+      (err instanceof Error && err.name === "AbortError");
+    const msg = err instanceof Error ? err.message : String(err);
+    return {
+      outcome: {
+        ok: false,
+        resendId: null,
+        httpStatus: 0,
+        providerError: sanitizeProviderText(msg),
+        aborted,
+        egressMode: context.mode,
+        egressReason: context.reason,
+      },
+      providerResponse: { exception: true, aborted },
+    };
+  }
+}
+
+interface ResendEmailReadResult {
+  ok: boolean;
+  httpStatus: number;
+  lastEvent: string | null;
+  recipientEmail: string | null;
+  providerError: string | null;
+}
+
+function readFirstRecipient(value: unknown): string | null {
+  if (typeof value === "string" && value.includes("@")) return value;
+  if (!Array.isArray(value)) return null;
+  return value.find((recipient): recipient is string =>
+    typeof recipient === "string" && recipient.includes("@")
+  ) ?? null;
+}
+
+// Read-only status retrieval for the delivery reconciliation poller
+// (docs/platform/RUNTIME_AND_SELF_HOSTING.md Wave 4). No egress gating needed: this never
+// sends mail — it only reads the provider's view of an already-sent message.
+async function getResendEmail(input: {
+  apiKey: string;
+  resendId: string;
+  signal?: AbortSignal;
+}, fetcher: typeof fetch): Promise<ResendEmailReadResult> {
+  try {
+    const res = await fetcher(`${RESEND_ENDPOINT}/${encodeURIComponent(input.resendId)}`, {
+      method: "GET",
+      headers: { Authorization: `Bearer ${input.apiKey}` },
+      signal: input.signal,
+    });
+    const parsed = (await res.json().catch(() => ({}))) as Record<string, unknown>;
+    if (!res.ok) {
+      return {
+        ok: false,
+        httpStatus: res.status,
+        lastEvent: null,
+        recipientEmail: null,
+        providerError: providerErrorFromBody(parsed, res.status),
+      };
+    }
+    const lastEvent = typeof parsed.last_event === "string" ? parsed.last_event : null;
+    return {
+      ok: true,
+      httpStatus: res.status,
+      lastEvent,
+      recipientEmail: readFirstRecipient(parsed.to),
+      providerError: null,
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      httpStatus: 0,
+      lastEvent: null,
+      recipientEmail: null,
+      providerError: error instanceof Error ? sanitizeProviderCode(error.message) : "fetch_failed",
+    };
+  }
+}
+
+/** Poll existing IDs through the neutral runner; never retries a send. */
+export function runResendDeliveryReconciliation(input: {
+  port: DeliveryReconciliationPort;
+  now: string;
+  graceMinutes: number;
+  limit: number;
+  apiKey: string;
+  fetch?: typeof fetch;
+  signal?: AbortSignal;
+}): Promise<DeliveryReconciliationResult> {
+  return runDeliveryReconciliation({
+    port: input.port, now: input.now, graceMinutes: input.graceMinutes, limit: input.limit,
+    readEmail: messageId => getResendEmail({ apiKey: input.apiKey, resendId: messageId, signal: input.signal }, input.fetch ?? fetch),
+    observationFor: read => {
+      const status = read.lastEvent;
+      if (!status || !["delivered", "delivery_delayed", "bounced", "complained", "failed"].includes(status)) return null;
+      return { eventType: `email.${status}`, terminal: ["bounced", "complained", "failed"].includes(status) };
+    },
+  });
+}
+
+const eventKinds = new Map([
+  ["email.sent", "sent"], ["email.delivered", "delivered"], ["email.delivery_delayed", "delivery_delayed"],
+  ["email.opened", "open"], ["email.clicked", "click"], ["email.bounced", "bounce"],
+  ["email.complained", "complaint"], ["email.failed", "failed"], ["email.suppressed", "suppressed"], ["email.scheduled", "scheduled"],
+]);
+
+/** Authenticate untouched bytes before decoding. now returns UTC seconds; receiver defaults to non-production. */
+export function createResendWebhookHandler(input: {
+  port: EmailObservationPort;
+  webhookSecret: string;
+  environmentTagName: string;
+  resolveReceiverEnvironmentTag?: () => "production" | "non_production";
+  now?: () => number;
+  receivedAt?: () => Date;
+}): (request: {
+  method?: string;
+  rawBody: string | Uint8Array;
+  headers: { webhookId?: string; timestamp?: string; signature?: string };
+}) => Promise<{ status: number; body: Record<string, unknown> | "ok" }> {
+  return async request => {
+    if (request.method === "OPTIONS") return { status: 200, body: "ok" };
+    if (!verifyResendWebhookSignature({ ...request.headers, rawBody: request.rawBody, secret: input.webhookSecret, now: input.now })) {
+      return { status: 401, body: { error: "Invalid signature" } };
+    }
+    try {
+      const payload: unknown = JSON.parse(typeof request.rawBody === "string" ? request.rawBody : Buffer.from(request.rawBody).toString("utf8"));
+      const type = isRecord(payload) ? payload.type : null;
+      const data = isRecord(payload) ? payload.data : null;
+      if (typeof type !== "string" || !eventKinds.has(type)) return { status: 200, body: { ignored: true } };
+      const messageId = isRecord(data) && typeof data.email_id === "string" ? data.email_id : null;
+      if (!messageId) return { status: 200, body: { ignored: true, reason: "missing_email_id" } };
+      const tag = readEnvironmentTag(data, input.environmentTagName);
+      if (tag && tag !== (input.resolveReceiverEnvironmentTag?.() ?? "non_production")) {
+        return { status: 200, body: { ignored: true, reason: "foreign_send_not_found" } };
+      }
+      const disposition = await processEmailObservation({
+        port: input.port, messageId,
+        observation: () => {
+          const time = resolveEventTime(isRecord(payload) ? payload.created_at : null, request.headers.timestamp, input.receivedAt?.() ?? new Date());
+          return { eventType: type, eventAt: time.eventAt, metadata: {
+            providerEventId: request.headers.webhookId ?? null, eventMetadata: data ?? {},
+            link: isRecord(data) && isRecord(data.click) && typeof data.click.link === "string" ? data.click.link : null,
+            source: "resend-webhook", eventTimeSource: time.source,
+          } };
+        },
+      });
+      return disposition.outcome === "send_not_found"
+        ? { status: 200, body: { ignored: true, reason: "send_not_found" } }
+        : { status: 200, body: { success: true } };
+    } catch {
+      return { status: 500, body: { error: "Webhook processing failed" } };
+    }
+  };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+function readEnvironmentTag(data: unknown, tagName: string): "production" | "non_production" | null {
+  if (!isRecord(data)) return null;
+  const tags = data.tags;
+  const value = Array.isArray(tags)
+    ? tags.find(entry => isRecord(entry) && entry.name === tagName)?.value
+    : isRecord(tags) ? tags[tagName] : null;
+  return value === "production" || value === "non_production" ? value : null;
+}
+function resolveEventTime(createdAt: unknown, timestamp: string | undefined, receivedAt: Date) {
+  if (typeof createdAt === "string" && Number.isFinite(Date.parse(createdAt))) {
+    return { eventAt: new Date(createdAt).toISOString(), source: "provider_created_at" };
+  }
+  const seconds = Number(timestamp);
+  if (Number.isFinite(seconds) && seconds > 0) return { eventAt: new Date(seconds * 1000).toISOString(), source: "svix_timestamp" };
+  return { eventAt: receivedAt.toISOString(), source: "received_at" };
+}
+
+function verifyResendWebhookSignature(input: { rawBody: string | Uint8Array; webhookId?: string; timestamp?: string; signature?: string; secret: string; now?: () => number }): boolean {
+  const { webhookId, timestamp, signature, rawBody, secret } = input;
+  if (!webhookId || !timestamp || !signature || !secret) return false;
+
+  const timestampSeconds = Number(timestamp);
+  if (!Number.isFinite(timestampSeconds)) return false;
+  const now = input.now ?? (() => Math.floor(Date.now() / 1000));
+  if (Math.abs(now() - timestampSeconds) > 300) return false;
+
+  const secretKey = signingSecret(secret);
+  if (secretKey === null) return false;
+
+  const expected = createHmac("sha256", secretKey)
+    .update(`${webhookId}.${timestamp}.`).update(rawBody)
+    .digest("base64");
+  return signature.split(" ").some((member) =>
+    timingSafeStringEqual(member, `v1,${expected}`) || timingSafeStringEqual(member, expected));
+}
+
+function signingSecret(secret: string): Buffer | string | null {
+  if (!secret.startsWith("whsec_")) return secret;
+  // Svix encodes endpoint secrets after the whsec_ prefix. Buffer preserves the
+  // decoded bytes for node:crypto rather than treating the base64 text as a key.
+  // Buffer.from(base64) is deliberately permissive, so reject empty, malformed,
+  // or non-canonical input before it can silently become an empty/partial key.
+  const encoded = secret.slice("whsec_".length);
+  if (!encoded || !/^[A-Za-z0-9+/]+={0,2}$/.test(encoded) || encoded.length % 4 === 1) return null;
+  const decoded = Buffer.from(encoded, "base64");
+  if (decoded.length === 0) return null;
+  const canonicalPadded = decoded.toString("base64");
+  const canonicalUnpadded = canonicalPadded.replace(/=+$/, "");
+  return encoded === canonicalPadded || encoded === canonicalUnpadded ? decoded : null;
+}
+
+function timingSafeStringEqual(left: string, right: string): boolean {
+  const leftBuffer = Buffer.from(left);
+  const rightBuffer = Buffer.from(right);
+  return leftBuffer.length === rightBuffer.length && timingSafeEqual(leftBuffer, rightBuffer);
+}

package/src/composition/catalogContribution.ts

@@ -0,0 +1,32 @@
+import type { Contribution, RequiredSchema } from "@openlup/core/readiness";
+
+/** Actual selected callables, supplied by the host; declarations never activate them. */
+export interface CatalogContributionInput {
+  version: string;
+  requiredSchema: RequiredSchema;
+  catalog: Readonly<Record<string, (...args: never[]) => unknown>>;
+  pricing: Readonly<Record<string, (...args: never[]) => unknown>>;
+  promotions: Readonly<Record<string, (...args: never[]) => unknown>>;
+  routes: Contribution["routes"];
+}
+
+/** Thin structural declarations under the existing logical module identities. */
+export function createCatalogContribution(input: CatalogContributionInput) {
+  const contributions: Contribution[] = [];
+  const ports: Record<string, unknown> = {};
+  for (const module of ["catalog", "pricing", "promotions"] as const) {
+    const selected = input[module];
+    for (const [name, callable] of Object.entries(selected)) ports[`@openlup/platform/${module}:${name}`] = callable;
+    contributions.push({
+      manifest: {
+        name: "@openlup/platform", version: input.version, kind: "rail",
+        module: { id: module, kind: "capability", provides: [`./${module}`], dependsOn: [] },
+        emits: [], handles: [], schedules: [], env: [], requiredPorts: Object.keys(selected),
+        routes: module === "catalog" ? input.routes.map(route => route.id) : [],
+        ...(module === "catalog" ? { requiredSchema: input.requiredSchema } : {}),
+      },
+      handlers: [], schedules: [], routes: module === "catalog" ? input.routes : [],
+    });
+  }
+  return { contributions, ports, routes: Object.fromEntries(input.routes.map(route => [`@openlup/platform/catalog:${route.id}`, route.handle])) };
+}

package/src/composition/index.ts

@@ -15,3 +15,4 @@ export {
   type ServeNodeOptions,
   type ServeNodeResult,
 } from "./nodeHost.js";
+export { createCatalogContribution, type CatalogContributionInput } from "./catalogContribution.js";

package/src/inventory/adminInventory.ts

@@ -0,0 +1,251 @@
+import { createHash } from "node:crypto";
+
+import { calculateInventoryAtp, availableNow, INVENTORY_CONTRACT_VERSION, type InventoryStockLine } from "@openlup/core/inventory";
+import type { z } from "zod";
+import { createInventorySubscriptionForecastResponseSchema } from "./schemas.js";
+import {
+  type InventorySubscriptionForecastSku,
+} from "./contracts/index.js";
+import {
+  InventoryPersistenceError,
+  type InventoryMutationPort,
+  type InventoryReadPort,
+} from "./ports.js";
+interface PgQueryExecutor {
+  query(text: string, values?: unknown[]): Promise<{ rows: Record<string, unknown>[] }>;
+}
+
+const STOCK_SQL = `SELECT sku.id AS sku_id, sku.sku, stock.source_key,
+    stock.for_sale_quantity AS on_hand,
+    COALESCE((SELECT sum(line.quantity)::integer
+      FROM public.fulfillment_inventory_reservation_lines line
+      JOIN public.fulfillment_inventory_reservations reservation ON reservation.id = line.reservation_id
+     WHERE line.sku = stock.sku AND reservation.source_key = stock.source_key
+       AND reservation.status IN ('held', 'committed')), 0) AS reserved,
+    stock.last_synced_at, stock.stale_after,
+    count(*) OVER() AS total_count
+  FROM public.fulfillment_stock_current stock
+  JOIN public.catalog_skus sku ON sku.sku = stock.sku
+ WHERE ($1::uuid IS NULL OR sku.id = $1::uuid)
+   AND ($2::boolean OR stock.for_sale_quantity > 0)
+ ORDER BY stock.updated_at DESC, stock.source_key, stock.sku
+ LIMIT $3::integer OFFSET $4::integer`;
+
+const RESERVATIONS_SQL = `SELECT reservation.id, order_row.id AS order_id, cycle.id AS cycle_id,
+    CASE reservation.status
+      WHEN 'held' THEN 'reserved' WHEN 'committed' THEN 'reserved'
+      ELSE reservation.status END AS status,
+    reservation.expires_at, reservation.created_at,
+    operation.identity_key, operation.operation_fingerprint, operation.terminal_outcome,
+    count(*) OVER() AS total_count
+  FROM public.fulfillment_inventory_reservations reservation
+  JOIN public.subscription_renewal_operations operation ON operation.id = reservation.renewal_operation_id
+  LEFT JOIN public.subscription_cycles cycle ON cycle.renewal_operation_id = operation.id
+  LEFT JOIN public.commerce_orders order_row ON order_row.renewal_operation_id = operation.id
+ WHERE ($1::text IS NULL OR CASE reservation.status
+      WHEN 'held' THEN 'reserved' WHEN 'committed' THEN 'reserved'
+      ELSE reservation.status END = $1::text)
+   AND ($2::uuid IS NULL OR order_row.id = $2::uuid)
+ ORDER BY reservation.created_at DESC, reservation.id
+  LIMIT $3::integer OFFSET $4::integer`;
+
+const ATP_SQL = `SELECT sku.id AS sku_id, sku.sku, stock.source_key,
+    stock.for_sale_quantity AS on_hand,
+    COALESCE((SELECT sum(line.quantity)::integer
+      FROM public.fulfillment_inventory_reservation_lines line
+      JOIN public.fulfillment_inventory_reservations reservation ON reservation.id = line.reservation_id
+     WHERE line.sku = stock.sku AND reservation.source_key = stock.source_key
+       AND reservation.status IN ('held', 'committed')), 0) AS reserved,
+    stock.last_synced_at, stock.stale_after, 0 AS total_count
+  FROM public.fulfillment_stock_current stock
+  JOIN public.catalog_skus sku ON sku.sku = stock.sku
+ WHERE sku.id = ANY($1::uuid[])
+   AND stock.inventory_class = 'sellable'
+   AND stock.stale_after > $2::timestamptz
+ ORDER BY stock.source_key, stock.sku`;
+
+const FORECAST_SQL = `WITH forecast_skus AS (
+    SELECT line.sku
+      FROM public.subscription_renewal_term_lines line
+      JOIN public.subscriptions subscription ON subscription.id = line.subscription_id
+     WHERE subscription.status = 'active'
+    UNION
+    SELECT stock.sku
+      FROM public.fulfillment_stock_current stock
+     WHERE stock.inventory_class = 'sellable'
+  ), sellable_stock AS (
+    SELECT stock.sku,
+           sum(stock.for_sale_quantity)::integer AS for_sale_quantity,
+           max(stock.last_synced_at) AS last_synced_at,
+           min(stock.stale_after) AS stale_after
+      FROM public.fulfillment_stock_current stock
+     WHERE stock.inventory_class = 'sellable'
+     GROUP BY stock.sku
+  )
+  SELECT sku.id AS sku_id, sku.sku,
+    stock.for_sale_quantity, stock.last_synced_at, stock.stale_after,
+    COALESCE(reserved.quantity, 0)::integer AS reserved,
+    COALESCE(demand.days_30, 0)::integer AS days_30,
+    COALESCE(demand.days_45, 0)::integer AS days_45,
+    COALESCE(demand.days_60, 0)::integer AS days_60
+  FROM forecast_skus forecast
+  JOIN public.catalog_skus sku ON sku.sku = forecast.sku
+  LEFT JOIN sellable_stock stock ON stock.sku = forecast.sku
+  LEFT JOIN LATERAL (
+    SELECT sum(line.quantity)::integer AS quantity
+      FROM public.fulfillment_inventory_reservation_lines line
+      JOIN public.fulfillment_inventory_reservations reservation ON reservation.id = line.reservation_id
+     WHERE line.sku = forecast.sku
+       AND reservation.status IN ('held', 'committed')) reserved ON true
+  LEFT JOIN LATERAL (
+    SELECT
+      sum(CASE WHEN subscription.next_cycle_at <= $1::timestamptz + interval '30 days' THEN line.quantity ELSE 0 END)::integer AS days_30,
+      sum(CASE WHEN subscription.next_cycle_at <= $1::timestamptz + interval '45 days' THEN line.quantity ELSE 0 END)::integer AS days_45,
+      sum(CASE WHEN subscription.next_cycle_at <= $1::timestamptz + interval '60 days' THEN line.quantity ELSE 0 END)::integer AS days_60
+      FROM public.subscription_renewal_term_lines line
+      JOIN public.subscriptions subscription ON subscription.id = line.subscription_id
+     WHERE line.sku = forecast.sku AND subscription.status = 'active'
+       AND subscription.next_cycle_at <= $1::timestamptz + ($2::integer * interval '1 day')) demand ON true
+ ORDER BY sku.sku`;
+
+const ACTIVE_SUBSCRIPTION_COUNT_SQL = `SELECT count(*)::integer AS active_subscription_count
+  FROM public.subscriptions WHERE status = 'active'`;
+
+/** Operator readback over the same public stock and reservation rail used by renewal. */
+export function createPostgresAdminInventoryPort(
+  executor: PgQueryExecutor,
+  config: { stockMasterProvider: string; providerSchema: z.ZodType<string> },
+  now: () => string = () => new Date().toISOString(),
+): InventoryReadPort & InventoryMutationPort {
+  const forecastResponseSchema = createInventorySubscriptionForecastResponseSchema(config.providerSchema);
+  return {
+    async listStock(request) {
+      const offset = (request.page - 1) * request.pageSize;
+      const result = await executor.query(STOCK_SQL, [
+        request.skuId ?? null, request.includeZero, request.pageSize, offset,
+      ]);
+      const stock = result.rows.map(mapStock);
+      return {
+        contractVersion: INVENTORY_CONTRACT_VERSION,
+        stock: stock.map((line) => ({ ...line, availableNow: availableNow(line) })),
+        totalCount: count(result.rows[0]), page: request.page, pageSize: request.pageSize,
+      };
+    },
+
+    async listReservations(request) {
+      const offset = (request.page - 1) * request.pageSize;
+      const result = await executor.query(RESERVATIONS_SQL, [
+        request.status ?? null, request.orderId ?? null, request.pageSize, offset,
+      ]);
+      return {
+        contractVersion: INVENTORY_CONTRACT_VERSION,
+        reservations: result.rows.map((row) => ({
+          id: text(row.id), orderId: text(row.order_id),
+          subscriptionCycleId: nullableText(row.cycle_id),
+          status: text(row.status) as "reserved" | "released" | "consumed" | "expired",
+          kind: "subscription_retry_window" as const,
+          expiresAt: timestampOrNull(row.expires_at), createdAt: timestamp(row.created_at),
+        })),
+        totalCount: count(result.rows[0]), page: request.page, pageSize: request.pageSize,
+      };
+    },
+
+    async checkAtp(request) {
+      const result = await executor.query(ATP_SQL, [
+        request.lines.map((line) => line.skuId), request.requestedAt,
+      ]);
+      return calculateInventoryAtp({ request, stock: result.rows.map(mapStock) });
+    },
+
+    async forecastSubscriptions(request) {
+      const generatedAt = now();
+      const result = await executor.query(FORECAST_SQL, [generatedAt, request.horizonDays]);
+      const activeSubscriptionResult = await executor.query(ACTIVE_SUBSCRIPTION_COUNT_SQL);
+      const skus = result.rows.map((row) => mapForecast(row, generatedAt, request));
+      return forecastResponseSchema.parse({
+        contractVersion: INVENTORY_CONTRACT_VERSION,
+        generatedAt,
+        // Compatibility projection required by the existing admin BFF contract;
+        // the public tables themselves keep source_key opaque.
+        stockMasterProvider: config.stockMasterProvider,
+        horizonDays: request.horizonDays,
+        protectionDays: request.protectionDays,
+        skus,
+        totals: {
+          activeSubscriptionCount: integer(
+            activeSubscriptionResult.rows[0]?.active_subscription_count,
+          ),
+          excludedSubscriptionCount: 0,
+          missingProviderStockSkuCount: skus.filter((sku) => sku.stockStatus === "missing").length,
+          staleProviderStockSkuCount: skus.filter((sku) => sku.stockStatus === "stale").length,
+          horizonShortageSkuCount: skus.filter((sku) => sku.horizonMissingQty > 0).length,
+          protectionShortageSkuCount: skus.filter((sku) => sku.protectionMissingQty > 0).length,
+          shortageSkuCount: skus.filter((sku) => sku.missingQty > 0).length,
+          recommendedProductionQty: skus.reduce((sum, sku) => sum + sku.recommendedProductionQty, 0),
+        },
+      });
+    },
+
+    async adjustStock() {
+      throw new InventoryPersistenceError(
+        "Direct stock is externally observed; use the configured stock-source adapter",
+      );
+    },
+  };
+}
+
+function mapStock(row: Record<string, unknown>): InventoryStockLine {
+  const source = text(row.source_key);
+  return {
+    skuId: text(row.sku_id), sku: text(row.sku),
+    locationId: stableUuid(source), locationCode: source,
+    locationKind: "third_party_logistics", locationStatus: "active", fulfillable: true,
+    lotId: null, lotCode: null, lotStatus: null, expiresAt: null,
+    onHand: integer(row.on_hand), reserved: integer(row.reserved), unavailable: 0,
+    incoming: 0, safetyStock: 0,
+  };
+}
+
+function mapForecast(
+  row: Record<string, unknown>,
+  generatedAt: string,
+  request: { horizonDays: number; protectionDays: number },
+): InventorySubscriptionForecastSku {
+  const sellable = Math.max(0, integer(row.for_sale_quantity) - integer(row.reserved));
+  const horizonDemand = request.horizonDays <= 30 ? integer(row.days_30)
+    : request.horizonDays <= 45 ? integer(row.days_45) : integer(row.days_60);
+  const protectionDemand = request.protectionDays <= 30 ? integer(row.days_30)
+    : request.protectionDays <= 45 ? integer(row.days_45) : integer(row.days_60);
+  const horizonMissingQty = Math.max(0, horizonDemand - sellable);
+  const protectionMissingQty = Math.max(0, protectionDemand - sellable);
+  const staleAfter = timestampOrNull(row.stale_after);
+  const stockStatus = row.for_sale_quantity === null || row.for_sale_quantity === undefined
+    ? "missing" as const
+    : staleAfter && staleAfter <= generatedAt ? "stale" as const : "fresh" as const;
+  return {
+    skuId: text(row.sku_id), sku: text(row.sku),
+    providerCurrentForSale: nullableInteger(row.for_sale_quantity),
+    providerStockLastSyncedAt: timestampOrNull(row.last_synced_at),
+    providerStockStaleAfter: staleAfter, stockStatus,
+    openHardReservations: integer(row.reserved), safetyStock: 0, sellableNow: sellable,
+    activeSubscriptionDemand30: integer(row.days_30),
+    activeSubscriptionDemand45: integer(row.days_45),
+    activeSubscriptionDemand60: integer(row.days_60), plannedSupply: 0,
+    coverageDays: null, shortageDate: null,
+    horizonMissingQty, protectionMissingQty,
+    missingQty: Math.max(horizonMissingQty, protectionMissingQty),
+    recommendedProductionQty: Math.max(horizonMissingQty, protectionMissingQty),
+  };
+}
+
+function stableUuid(value: string): string {
+  const hash = createHash("sha256").update(`inventory-source:${value}`).digest("hex");
+  return `${hash.slice(0, 8)}-${hash.slice(8, 12)}-4${hash.slice(13, 16)}-8${hash.slice(17, 20)}-${hash.slice(20, 32)}`;
+}
+function text(value: unknown): string { return typeof value === "string" ? value : String(value ?? ""); }
+function nullableText(value: unknown): string | null { const result = text(value).trim(); return result || null; }
+function integer(value: unknown): number { const result = Number(value); return Number.isSafeInteger(result) && result >= 0 ? result : 0; }
+function nullableInteger(value: unknown): number | null { return value === null || value === undefined ? null : integer(value); }
+function count(row: Record<string, unknown> | undefined): number { return row ? integer(row.total_count) : 0; }
+function timestamp(value: unknown): string { return value instanceof Date ? value.toISOString() : text(value); }
+function timestampOrNull(value: unknown): string | null { return value === null || value === undefined ? null : timestamp(value); }