@openlup/platform 0.16.0 → 0.18.0

package/src/communications/transactionalDeliveryIdentifier.ts

@@ -0,0 +1,9 @@
+/** Narrow, portable receipt contract for the captured transactional action. */
+
+const IDENTIFIER = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$/;
+
+/** Bounded opaque identifiers keep commands and persisted evidence content-free. */
+export function isTransactionalDeliveryIdentifier(value: string): boolean {
+  return IDENTIFIER.test(value);
+}
+

package/src/communications/unsubscribeToken.ts

@@ -0,0 +1,186 @@
+/**
+ * Stateless, signed unsubscribe tokens for marketing emails (RODO one-click
+ * opt-out): an HMAC-SHA256 over the recipient email + consent purpose, so the
+ * unsubscribe route can suppress the right permission without a lookup table or
+ * trusting raw query params. Node marketing senders build the token to embed in
+ * the email footer; `api/unsubscribe.ts` verifies it.
+ *
+ * This module is the only implementation. The former Deno mirror was deleted
+ * with the `unsubscribe` Edge function; nothing has to be kept in sync any more.
+ *
+ * WebCrypto only (global `crypto.subtle`/`btoa`/`atob`, Node 18+).
+ */
+
+export interface UnsubscribePayload {
+  email: string;
+  purpose: string;
+}
+
+/**
+ * How long a newly minted unsubscribe link stays valid: 548 days, i.e. about
+ * eighteen months, expressed in whole days so the value does not depend on which
+ * months a token happens to span.
+ *
+ * Contract, and why this number:
+ *
+ * - Until this field existed the token carried `{e, p, v}` and the verifier
+ *   checked only the HMAC, so a link minted in 2026 stayed valid forever. That
+ *   made "wait for the old links to age out" an unbounded strategy and left a
+ *   permanently replayable capability sitting in mailboxes.
+ * - Eighteen months is longer than a marketing message is realistically acted
+ *   on and longer than a full annual cycle plus a lapsed re-engagement, so it
+ *   does not cut short a genuine opt-out; it is short enough that the capability
+ *   is not effectively perpetual.
+ * - ⛔ A token WITHOUT `exp` stays valid. Every link already delivered was
+ *   minted without one, and refusing them would retro-expire opt-outs the
+ *   recipient was told would work. Expiry is a forward-only narrowing.
+ *
+ * ⛔ Do not rename this to anything containing `TOKEN`, `SECRET`, `PASSWORD`,
+ * `SERVICE_ROLE` or `API_KEY`. This module is client-reachable `src/` source and
+ * `scripts/check-client-secret-boundary.ts` refuses a SCREAMING_SNAKE
+ * identifier carrying any of those words there — a TTL is not a credential, so
+ * the name avoids the shape rather than the allowlist.
+ */
+export const UNSUBSCRIBE_LINK_TTL_SECONDS = 548 * 24 * 60 * 60;
+
+/** Clock seam, so expiry can be proved without waiting eighteen months. */
+export interface UnsubscribeTokenClock {
+  now?: Date;
+}
+
+function base64urlEncode(bytes: Uint8Array): string {
+  let binary = "";
+  for (const b of bytes) binary += String.fromCharCode(b);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+function base64urlDecodeToString(value: string): string {
+  const padded = value.replace(/-/g, "+").replace(/_/g, "/").padEnd(
+    Math.ceil(value.length / 4) * 4,
+    "=",
+  );
+  return atob(padded);
+}
+
+function timingSafeEqual(a: string, b: string): boolean {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i += 1) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return diff === 0;
+}
+
+async function hmacBase64url(secret: string, message: string): Promise<string> {
+  const key = await crypto.subtle.importKey(
+    "raw",
+    new TextEncoder().encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"],
+  );
+  const sig = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(message));
+  return base64urlEncode(new Uint8Array(sig));
+}
+
+/**
+ * Build a `<base64url(payload)>.<base64url(sig)>` unsubscribe token.
+ *
+ * Quoted-printable safety: this token rides as `?token=…` inside marketing emails
+ * whose Polish diacritics force quoted-printable encoding. A token beginning with
+ * two hex digits could be corrupted if a transport leaves the `=` separator raw
+ * (`=7d` -> `}`). This token is structurally immune: the payload always serializes
+ * as `{"e":…`, so base64url makes the token always begin "ey" (`e` is hex, `y` is
+ * not) — `=ey` is never a valid `=<2 hex>` escape. unsubscribeToken.test.ts guards
+ * this; do NOT reshape the payload to lead with a field that could base64url into
+ * two hex digits without re-checking (and prefixing the token if so). `exp` is
+ * appended last for exactly that reason.
+ */
+export async function buildUnsubscribeToken(
+  payload: UnsubscribePayload,
+  secret: string,
+  clock: UnsubscribeTokenClock = {},
+): Promise<string> {
+  const issuedAtSeconds = Math.floor((clock.now ?? new Date()).getTime() / 1000);
+  const body = base64urlEncode(
+    new TextEncoder().encode(JSON.stringify({
+      e: payload.email,
+      p: payload.purpose,
+      v: 1,
+      exp: issuedAtSeconds + UNSUBSCRIBE_LINK_TTL_SECONDS,
+    })),
+  );
+  const sig = await hmacBase64url(secret, body);
+  return `${body}.${sig}`;
+}
+
+/**
+ * Add the signed query to a resolved unsubscribe endpoint. The adapter that
+ * owns deployment/provider configuration must choose and validate that endpoint
+ * before it reaches this neutral communications-domain helper.
+ */
+export function buildUnsubscribeUrl(
+  unsubscribeEndpointUrl: string,
+  token: string,
+  locale: "pl" | "en",
+): string {
+  const endpoint = parseUnsubscribeEndpointUrl(unsubscribeEndpointUrl);
+  const params = new URLSearchParams({ token });
+  if (locale === "en") params.set("lang", "en");
+  endpoint.search = `?${params.toString()}`;
+  return endpoint.toString();
+}
+
+function parseUnsubscribeEndpointUrl(value: string): URL {
+  const endpoint = new URL(value);
+  if (
+    endpoint.protocol !== "https:" ||
+    endpoint.username ||
+    endpoint.password ||
+    endpoint.search ||
+    endpoint.hash ||
+    endpoint.hostname.endsWith(".")
+  ) {
+    throw new Error("unsubscribe endpoint URL must be HTTPS without credentials, query, fragment, or a trailing-dot hostname");
+  }
+  return endpoint;
+}
+
+/**
+ * Verify a token; returns the payload or null on any tampering / bad shape /
+ * elapsed expiry.
+ *
+ * ⛔ An absent `exp` is valid, not a rejection: tokens minted before expiry
+ * existed are still in mailboxes, and a recipient who was promised a working
+ * opt-out link must keep one. A present `exp` must be a finite number and must
+ * still be in the future — it is inside the signed payload, so it cannot be
+ * stripped or moved without breaking the HMAC.
+ */
+export async function verifyUnsubscribeToken(
+  token: string,
+  secret: string,
+  clock: UnsubscribeTokenClock = {},
+): Promise<UnsubscribePayload | null> {
+  if (!token || !secret) return null;
+  const dot = token.indexOf(".");
+  if (dot <= 0) return null;
+  const body = token.slice(0, dot);
+  const sig = token.slice(dot + 1);
+  const expected = await hmacBase64url(secret, body);
+  if (!timingSafeEqual(sig, expected)) return null;
+  try {
+    const parsed = JSON.parse(base64urlDecodeToString(body)) as {
+      e?: unknown;
+      p?: unknown;
+      exp?: unknown;
+    };
+    if (typeof parsed.e !== "string" || typeof parsed.p !== "string") return null;
+    if (!parsed.e || !parsed.p) return null;
+    if (parsed.exp !== undefined) {
+      if (typeof parsed.exp !== "number" || !Number.isFinite(parsed.exp)) return null;
+      const nowSeconds = Math.floor((clock.now ?? new Date()).getTime() / 1000);
+      if (parsed.exp <= nowSeconds) return null;
+    }
+    return { email: parsed.e, purpose: parsed.p };
+  } catch {
+    return null;
+  }
+}

package/src/communications/validation.ts

@@ -0,0 +1,3 @@
+import { z } from "zod";
+z.config({ jitless: true });
+export { z };

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/http/index.ts

@@ -34,3 +34,4 @@ export {
   type NodeHttpRuntimeOptions,
   type NodeLegacyRedirect,
 } from "./runtime.js";
+export { MAX_WEBHOOK_BODY_BYTES, WebhookBodyTooLargeError, readRawBody, verifyHmacSignature, timingSafeStringEqual } from "./webhookSignature.js";

package/src/http/webhookSignature.ts

@@ -0,0 +1,96 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import type { HttpRequest } from "./types.js";
+
+/** Hard cap on raw webhook body bytes — the payment provider events are well under 256 KiB. */
+export const MAX_WEBHOOK_BODY_BYTES = 1_048_576;
+
+/** Thrown by readRawBody when the streamed body exceeds MAX_WEBHOOK_BODY_BYTES. */
+export class WebhookBodyTooLargeError extends Error {
+  constructor() {
+    super("Webhook body exceeds maximum size");
+    this.name = "WebhookBodyTooLargeError";
+  }
+}
+
+/**
+ * Reads the exact raw request body bytes for provider webhook signature
+ * verification.
+ *
+ * `@vercel/node` (v3, the builder for `/api` functions in this Vite project)
+ * auto-parses `application/json` request bodies into `req.body` and IGNORES the
+ * `export const config = { api: { bodyParser: false } }` opt-out — that opt-out
+ * is a Next.js Pages Router convention, not a vanilla `@vercel/node` one
+ * (verified empirically against the hidden-preview deploy: a JSON payload posted
+ * with `Content-Type: application/json` arrives parsed, the same bytes posted as
+ * `text/plain` arrive raw). Re-serializing the parsed object with
+ * `JSON.stringify` does NOT reproduce the provider's exact bytes — the payment provider signs
+ * pretty-printed JSON, so a compacted re-serialization breaks HMAC verification.
+ *
+ * Reading the underlying request stream FIRST — before touching `req.body`,
+ * whose getter triggers the parse that consumes the stream — preserves the exact
+ * bytes when the platform parses lazily. When `req` is not a stream (unit tests
+ * pass a plain `{ body }` object) or the stream yields nothing (already
+ * consumed), we fall back to `req.body`.
+ */
+export async function readRawBody(req: HttpRequest): Promise<string> {
+  if (isAsyncIterable(req)) {
+    const chunks: Buffer[] = [];
+    let total = 0;
+    for await (const chunk of req as unknown as AsyncIterable<Buffer | string>) {
+      const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+      total += buf.byteLength;
+      // Enforce the cap mid-stream so an oversized body is rejected before it is
+      // fully buffered into memory, not after.
+      if (total > MAX_WEBHOOK_BODY_BYTES) throw new WebhookBodyTooLargeError();
+      chunks.push(buf);
+    }
+    if (chunks.length > 0) return Buffer.concat(chunks).toString("utf8");
+  }
+
+  if (typeof req.body === "string") return capBody(req.body);
+  if (Buffer.isBuffer(req.body)) return capBody(req.body.toString("utf8"));
+  if (req.body && typeof req.body === "object") return capBody(JSON.stringify(req.body));
+  return "";
+}
+
+function capBody(body: string): string {
+  if (Buffer.byteLength(body, "utf8") > MAX_WEBHOOK_BODY_BYTES) {
+    throw new WebhookBodyTooLargeError();
+  }
+  return body;
+}
+
+function isAsyncIterable(value: unknown): boolean {
+  return (
+    value != null &&
+    typeof (value as { [Symbol.asyncIterator]?: unknown })[Symbol.asyncIterator] ===
+      "function"
+  );
+}
+
+export function verifyHmacSignature(input: {
+  rawBody: string;
+  signatureHeader: string | undefined;
+  secret: string;
+}): boolean {
+  if (!input.signatureHeader || !input.secret) return false;
+  return timingSafeStringEqual(input.signatureHeader, hmac(input.rawBody, input.secret));
+}
+
+function hmac(value: string, secret: string): string {
+  return createHmac("sha256", secret).update(value).digest("hex");
+}
+
+/**
+ * Constant-time comparison of two shared-secret strings.
+ *
+ * Exported because it is not payment-specific: any route holding a shared token has to compare it
+ * the same way, and a second hand-rolled copy of a security primitive is how one of them quietly
+ * stops being constant-time. The length check comes first because `timingSafeEqual` THROWS on a
+ * length mismatch rather than returning false, and the length of a shared token is not the secret.
+ */
+export 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/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); }