@openlup/core 0.0.0 → 0.6.0

package/src/payment/paymentStateMachine.ts

@@ -0,0 +1,263 @@
+import type {
+  CanonicalPaymentControlEvent,
+  PaymentAttemptAggregate,
+  PaymentAttemptStatus,
+  PaymentControlDecision,
+  PaymentControlFailureReason,
+  PaymentControlResult,
+  PaymentIntentAggregate,
+  PaymentIntentStatus,
+} from "./paymentControlTypes.js";
+
+const intentTransitions: Record<PaymentIntentStatus, readonly PaymentIntentStatus[]> = {
+  created: ["requires_action", "processing", "failed", "expired", "cancelled"],
+  requires_action: ["processing", "succeeded", "failed", "expired", "cancelled"],
+  processing: ["requires_action", "succeeded", "failed", "expired", "cancelled"],
+  failed: ["requires_action", "processing", "succeeded", "cancelled"],
+  expired: ["requires_action", "processing", "succeeded", "cancelled"],
+  cancelled: [],
+  succeeded: ["refunded", "partially_refunded", "disputed"],
+  partially_refunded: ["refunded", "disputed"],
+  refunded: ["disputed"],
+  disputed: [],
+};
+
+const attemptTransitions: Record<PaymentAttemptStatus, readonly PaymentAttemptStatus[]> = {
+  created: ["blocked_preflight", "sent_to_provider", "requires_action", "processing", "failed", "cancelled", "expired"],
+  blocked_preflight: ["failed", "cancelled", "expired"],
+  sent_to_provider: ["requires_action", "processing", "succeeded", "failed", "cancelled", "expired"],
+  requires_action: ["processing", "succeeded", "failed", "cancelled", "expired"],
+  processing: ["requires_action", "succeeded", "failed", "cancelled", "expired"],
+  failed: ["succeeded"],
+  cancelled: ["succeeded"],
+  expired: ["succeeded"],
+  succeeded: [],
+};
+
+function success<T>(value: T): PaymentControlResult<T> {
+  return { ok: true, value };
+}
+
+function failure(
+  reason: PaymentControlFailureReason,
+  message: string,
+): PaymentControlResult<never> {
+  return { ok: false, reason, message };
+}
+
+/** @beta */
+export function canTransitionPaymentIntent(
+  from: PaymentIntentStatus,
+  to: PaymentIntentStatus,
+): boolean {
+  return from === to || intentTransitions[from].includes(to);
+}
+
+/** @beta */
+export function canTransitionPaymentAttempt(
+  from: PaymentAttemptStatus,
+  to: PaymentAttemptStatus,
+): boolean {
+  return from === to || attemptTransitions[from].includes(to);
+}
+
+/** @beta */
+export function transitionPaymentIntent(input: {
+  intent: PaymentIntentAggregate;
+  to: PaymentIntentStatus;
+  at: string;
+  failureReason?: string | null;
+}): PaymentControlResult<PaymentIntentAggregate> {
+  if (!canTransitionPaymentIntent(input.intent.status, input.to)) {
+    return failure("invalid_transition", `Cannot move payment intent from ${input.intent.status} to ${input.to}`);
+  }
+
+  return success({
+    ...input.intent,
+    status: input.to,
+    updatedAt: input.at,
+    failureReason: input.failureReason ?? (input.to === "failed" ? input.intent.failureReason ?? "provider_failed" : null),
+  });
+}
+
+/** @beta */
+export function transitionPaymentAttempt(input: {
+  attempt: PaymentAttemptAggregate;
+  to: PaymentAttemptStatus;
+  at: string;
+  providerAttemptId?: string | null;
+  nextActionKind?: string | null;
+  failureReason?: string | null;
+}): PaymentControlResult<PaymentAttemptAggregate> {
+  if (!canTransitionPaymentAttempt(input.attempt.status, input.to)) {
+    return failure("invalid_transition", `Cannot move payment attempt from ${input.attempt.status} to ${input.to}`);
+  }
+
+  return success({
+    ...input.attempt,
+    status: input.to,
+    updatedAt: input.at,
+    providerAttemptId: input.providerAttemptId ?? input.attempt.providerAttemptId,
+    nextActionKind: input.nextActionKind ?? input.attempt.nextActionKind ?? null,
+    failureReason: input.failureReason ?? (input.to === "failed" ? input.attempt.failureReason ?? "provider_failed" : null),
+  });
+}
+
+function assertEventTargetsActiveAttempt(input: {
+  intent: PaymentIntentAggregate;
+  attempt: PaymentAttemptAggregate;
+}): PaymentControlResult<void> {
+  if (input.attempt.intentId !== input.intent.id || input.intent.activeAttemptId !== input.attempt.id) {
+    return failure("wrong_attempt", "Provider event must target the active local payment attempt");
+  }
+  return success(undefined);
+}
+
+function assertMoneyMatches(input: {
+  intent: PaymentIntentAggregate;
+  event: CanonicalPaymentControlEvent;
+  exactAmount: boolean;
+}): PaymentControlResult<void> {
+  if (input.event.currency && input.event.currency !== input.intent.currency) {
+    return failure("currency_mismatch", "Provider event currency does not match the local payment intent");
+  }
+
+  if (input.event.amountMinor === undefined) return success(undefined);
+  if (input.exactAmount && input.event.amountMinor !== input.intent.amountMinor) {
+    return failure("amount_mismatch", "Provider event amount does not match the local payment intent");
+  }
+  if (!input.exactAmount && (input.event.amountMinor < 1 || input.event.amountMinor > input.intent.amountMinor)) {
+    return failure("amount_mismatch", "Refund amount must be positive and not exceed the original payment amount");
+  }
+
+  return success(undefined);
+}
+
+function buildDecision(input: {
+  kind: PaymentControlDecision["kind"];
+  reason: string;
+  intent: PaymentIntentAggregate;
+  attempt: PaymentAttemptAggregate;
+}): PaymentControlResult<PaymentControlDecision> {
+  return success(input);
+}
+
+/** @beta */
+export function applyProviderPaymentEvent(input: {
+  intent: PaymentIntentAggregate;
+  attempt: PaymentAttemptAggregate;
+  event: CanonicalPaymentControlEvent;
+  seenProviderEventIds?: readonly string[];
+}): PaymentControlResult<PaymentControlDecision> {
+  if (input.seenProviderEventIds?.includes(input.event.providerEventId)) {
+    return buildDecision({ kind: "noop", reason: "duplicate_provider_event", ...input });
+  }
+
+  const targetCheck = assertEventTargetsActiveAttempt(input);
+  if (targetCheck.ok === false) return failure(targetCheck.reason, targetCheck.message);
+
+  if (input.event.eventType === "payment.refunded") return applyRefundEvent(input);
+  if (input.event.eventType === "payment.disputed") return applyDisputeEvent(input);
+
+  const moneyCheck = assertMoneyMatches({ intent: input.intent, event: input.event, exactAmount: true });
+  if (moneyCheck.ok === false) return failure(moneyCheck.reason, moneyCheck.message);
+
+  if (input.event.eventType === "payment.succeeded") return applySuccessEvent(input);
+  if (input.event.eventType === "payment.failed") return applyFailureEvent(input);
+  return applyRequiresActionEvent(input);
+}
+
+function applyRequiresActionEvent(input: {
+  intent: PaymentIntentAggregate;
+  attempt: PaymentAttemptAggregate;
+  event: CanonicalPaymentControlEvent;
+}): PaymentControlResult<PaymentControlDecision> {
+  const intent = transitionPaymentIntent({ intent: input.intent, to: "requires_action", at: input.event.occurredAt });
+  const attempt = transitionPaymentAttempt({
+    attempt: input.attempt,
+    to: "requires_action",
+    at: input.event.occurredAt,
+    providerAttemptId: input.event.providerPaymentId,
+    nextActionKind: input.event.nextActionKind ?? null,
+  });
+  if (intent.ok === false) return failure(intent.reason, intent.message);
+  if (attempt.ok === false) return failure(attempt.reason, attempt.message);
+  return buildDecision({ kind: "state_changed", reason: "provider_requires_action", intent: intent.value, attempt: attempt.value });
+}
+
+function applySuccessEvent(input: {
+  intent: PaymentIntentAggregate;
+  attempt: PaymentAttemptAggregate;
+  event: CanonicalPaymentControlEvent;
+}): PaymentControlResult<PaymentControlDecision> {
+  if (["cancelled", "refunded", "partially_refunded", "disputed"].includes(input.intent.status)) {
+    return failure("terminal_intent", `Cannot apply provider success after intent status ${input.intent.status}`);
+  }
+  if (input.intent.status === "succeeded" && input.attempt.status === "succeeded") {
+    return buildDecision({ kind: "noop", reason: "already_succeeded", ...input });
+  }
+
+  const recovered = input.intent.status === "failed" || input.intent.status === "expired";
+  const intent = transitionPaymentIntent({ intent: input.intent, to: "succeeded", at: input.event.occurredAt });
+  const attempt = transitionPaymentAttempt({
+    attempt: input.attempt,
+    to: "succeeded",
+    at: input.event.occurredAt,
+    providerAttemptId: input.event.providerPaymentId,
+    failureReason: null,
+  });
+  if (intent.ok === false) return failure(intent.reason, intent.message);
+  if (attempt.ok === false) return failure(attempt.reason, attempt.message);
+  return buildDecision({
+    kind: recovered ? "late_success_recovered" : "state_changed",
+    reason: recovered ? "late_success_after_failed_or_expired" : "provider_succeeded",
+    intent: { ...intent.value, providerPaymentId: input.event.providerPaymentId },
+    attempt: attempt.value,
+  });
+}
+
+function applyFailureEvent(input: {
+  intent: PaymentIntentAggregate;
+  attempt: PaymentAttemptAggregate;
+  event: CanonicalPaymentControlEvent;
+}): PaymentControlResult<PaymentControlDecision> {
+  if (["succeeded", "refunded", "partially_refunded", "disputed"].includes(input.intent.status)) {
+    return buildDecision({ kind: "noop", reason: "ignored_failure_after_success_or_terminal", ...input });
+  }
+
+  const reason = input.event.failureReason ?? "provider_failed";
+  const intent = transitionPaymentIntent({ intent: input.intent, to: "failed", at: input.event.occurredAt, failureReason: reason });
+  const attempt = transitionPaymentAttempt({ attempt: input.attempt, to: "failed", at: input.event.occurredAt, failureReason: reason });
+  if (intent.ok === false) return failure(intent.reason, intent.message);
+  if (attempt.ok === false) return failure(attempt.reason, attempt.message);
+  return buildDecision({ kind: "state_changed", reason: "provider_failed", intent: intent.value, attempt: attempt.value });
+}
+
+function applyRefundEvent(input: {
+  intent: PaymentIntentAggregate;
+  attempt: PaymentAttemptAggregate;
+  event: CanonicalPaymentControlEvent;
+}): PaymentControlResult<PaymentControlDecision> {
+  if (!["succeeded", "partially_refunded", "refunded"].includes(input.intent.status)) {
+    return failure("refund_requires_success", "Refund event requires a previously succeeded local payment intent");
+  }
+  const moneyCheck = assertMoneyMatches({ intent: input.intent, event: input.event, exactAmount: false });
+  if (moneyCheck.ok === false) return failure(moneyCheck.reason, moneyCheck.message);
+  const status = input.event.amountMinor === input.intent.amountMinor ? "refunded" : "partially_refunded";
+  const intent = transitionPaymentIntent({ intent: input.intent, to: status, at: input.event.occurredAt });
+  if (intent.ok === false) return failure(intent.reason, intent.message);
+  return buildDecision({ kind: "state_changed", reason: "provider_refunded", intent: intent.value, attempt: input.attempt });
+}
+
+function applyDisputeEvent(input: {
+  intent: PaymentIntentAggregate;
+  attempt: PaymentAttemptAggregate;
+  event: CanonicalPaymentControlEvent;
+}): PaymentControlResult<PaymentControlDecision> {
+  if (input.intent.status === "cancelled") {
+    return failure("terminal_intent", "Cannot dispute a cancelled local payment intent");
+  }
+  const intent = transitionPaymentIntent({ intent: input.intent, to: "disputed", at: input.event.occurredAt });
+  if (intent.ok === false) return failure(intent.reason, intent.message);
+  return buildDecision({ kind: "state_changed", reason: "provider_disputed", intent: intent.value, attempt: input.attempt });
+}

package/src/payment/providerAttemptIdempotency.ts

@@ -0,0 +1,57 @@
+/** @beta */
+export interface ProviderAttemptIdentityInput {
+  namespace: string;
+  provider: string;
+  localExecutionIdempotencyKey: string;
+  paymentIntentId: string;
+  amountMinor: number;
+  currency: string;
+  mode: "one_time" | "subscription_cycle";
+  orderRef: string;
+}
+
+/** @beta */
+export interface ProviderAttemptIdentity {
+  providerIdempotencyKey: string;
+  providerRequestFingerprint: string;
+}
+
+/** @beta */
+export function buildProviderAttemptIdentity(
+  input: ProviderAttemptIdentityInput,
+): ProviderAttemptIdentity {
+  const normalizedNamespace = normalizeSegment(input.namespace);
+  const normalizedProvider = normalizeSegment(input.provider);
+  const normalizedLocalKey = normalizeSegment(input.localExecutionIdempotencyKey);
+  const normalizedCurrency = input.currency.trim().toUpperCase();
+  const providerIdempotencyKey = [
+    normalizedNamespace,
+    normalizedProvider,
+    input.paymentIntentId,
+    normalizedLocalKey,
+  ].join(":");
+
+  return {
+    providerIdempotencyKey,
+    providerRequestFingerprint: [
+      normalizedProvider,
+      input.paymentIntentId,
+      input.amountMinor.toString(),
+      normalizedCurrency,
+      input.mode,
+      input.orderRef,
+    ].join("|"),
+  };
+}
+
+/** @beta */
+export function isProviderAttemptReplaySafe(input: {
+  existingFingerprint: string;
+  nextFingerprint: string;
+}): boolean {
+  return input.existingFingerprint === input.nextFingerprint;
+}
+
+function normalizeSegment(value: string): string {
+  return value.trim().toLowerCase().replace(/[^a-z0-9_.:-]+/g, "_");
+}

package/src/payment/providerCapability.ts

@@ -0,0 +1,172 @@
+/**
+ * Payment provider capability contracts.
+ *
+ * Renewal and dunning orchestration must decide what it can do with a stored
+ * consent by reading CAPABILITIES, never by comparing a provider identity
+ * string. This module is the neutral vocabulary those decisions are expressed
+ * in; the values live in each adapter, so nothing here names a provider.
+ *
+ * Every field exists because a live branch consumes it. Capabilities without a
+ * consumer (capture flows, status reads, limits) are deliberately absent and
+ * arrive with the code that needs them.
+ */
+
+/**
+ * Why a stored consent cannot back an unattended (off-session) charge.
+ *
+ * Neutral by construction: a provider-native refusal code never reaches a
+ * caller through this contract, so the orchestrator can route a blocked
+ * renewal into customer repair without learning provider vocabulary.
+ */
+export type UnattendedChargeBlockReason =
+  // The consent was registered under a model that cannot be charged
+  // unattended — including the case where no model was recorded at all, which
+  // fails closed rather than guessing one.
+  "mandate_model_unsupported_for_unattended_charge";
+
+/**
+ * The stored consent evidence a capability judges, as read from local records
+ * rather than from a provider call. Optional everywhere: a provider whose
+ * consent carries no model simply ignores the field.
+ */
+export interface StoredMandateSnapshot {
+  /** Recurring/mandate model recorded when the payer gave consent. */
+  recurringModel?: string | null;
+}
+
+/** The verdict on whether a stored consent may be charged unattended. */
+export interface UnattendedMandateAssessment {
+  chargeable: boolean;
+  blockReason?: UnattendedChargeBlockReason;
+}
+
+/**
+ * What an unattended charge request must carry about the payer.
+ *
+ * Models the two payer-shaped branches on the renewal path: whether the
+ * request needs a payer block at all, and whether the customer reference may
+ * fall back to the stored contact email when no provider customer exists.
+ */
+export interface PayerContextRequirements {
+  requiresPayerBlock: boolean;
+  customerRefFallsBackToContactEmail: boolean;
+}
+
+/**
+ * What the stored-method health check must see before a charge is attempted.
+ *
+ * Models the per-provider preconditions the payment-method lifecycle applies
+ * to a stored method; the lifecycle keeps owning the reason vocabulary it
+ * reports, this contract owns only the expectations.
+ */
+export interface PaymentMethodHealthExpectations {
+  /** A provider-side customer reference is mandatory for a charge. */
+  requiresCustomerRef: boolean;
+  /** The stored method must be of exactly this kind, or null when any kind charges. */
+  requiredMethodKind: string | null;
+  /** A stored payer contact (email) is mandatory for a charge. */
+  requiresPayerContact: boolean;
+}
+
+/**
+ * How a customer-present client must drive one method-capture flow.
+ *
+ * Closed on purpose: a client can only offer a flow it knows how to drive, so a
+ * provider that invents a handoff no client implements must widen this union
+ * together with the surface that renders it, rather than have a repair page
+ * present a control that leads nowhere.
+ */
+export type PaymentMethodCaptureHandoff =
+  // The client mounts provider-supplied fields bound to a per-attempt secret,
+  // or the payer types a short-lived authorisation code into the client's own
+  // form. Line comments on purpose: a member-level doc comment makes the
+  // extractor emit a trailing-whitespace alias line the diff guard refuses.
+  "embedded_client_secret" | "payer_supplied_code";
+
+/**
+ * One way a payer can hand this provider a reusable payment consent while
+ * present at the keyboard — the repair path out of a failed unattended charge.
+ *
+ * `kind` is neutral vocabulary the renderer may label and key on; it is never a
+ * provider identity. A declared flow is an offer of capability, not a promise
+ * that any given client implements it: the client filters by `handoff`.
+ */
+export interface PaymentMethodCaptureFlow {
+  kind: string;
+  handoff: PaymentMethodCaptureHandoff;
+}
+
+/**
+ * Where a terminal outcome becomes visible on a rail, and how long the absence
+ * of one is still normal.
+ *
+ * Reconciliation cannot tell "still running" from "stuck" by polling alone: a
+ * rail that answers non-terminally forever looks identical to a healthy slow
+ * one. Declaring the shape makes silence measurable per rail instead of
+ * guessed at globally, and makes the question something a new adapter must
+ * answer up front rather than discover through an incident.
+ */
+export interface TerminalOutcomeReporting {
+  /**
+   * Where the outcome lands. Line comments on purpose: a member-level doc
+   * comment makes the extractor emit a trailing-whitespace alias line the diff
+   * guard refuses.
+   */
+  // "status_field" - the readback's own status turns terminal.
+  // "attempt_records" - the status stays non-terminal and the outcome is
+  //   reported per attempt, so reading only the status never terminalizes.
+  // "inbound_event" - only a pushed event carries the outcome, so a lost event
+  //   means the readback never turns terminal at all.
+  kind: "status_field" | "attempt_records" | "inbound_event";
+  /**
+   * Minutes of non-terminal answers after which this rail is behaving
+   * abnormally and the attempt deserves a human, not another poll. This is a
+   * suspicion threshold, never a verdict: elapsed time is not evidence about
+   * money, so nothing may terminalize a charge from this value alone.
+   */
+  silenceBecomesSuspectAfterMinutes: number;
+}
+
+/**
+ * One provider's unattended-charge capabilities, published by its adapter.
+ *
+ * `providerKind` is the registry key only. Consumers must read the capability
+ * fields; branching on this value re-creates the coupling the contract exists
+ * to remove.
+ */
+export interface PaymentProviderCapabilityDescriptor {
+  providerKind: string;
+  /**
+   * Every customer-present capture flow this provider can complete. Empty means
+   * a payer cannot repair this rail's consent without leaving the product.
+   */
+  captureFlows: readonly PaymentMethodCaptureFlow[];
+  /**
+   * The stored consent evidence must be loaded from local records before a
+   * charge is prepared. False means `assessMandate` decides without it, and the
+   * caller must not pay for the read.
+   */
+  requiresStoredMandateEvidence: boolean;
+  /** Judges stored consent evidence before any durable provider attempt is created. */
+  assessMandate(snapshot: StoredMandateSnapshot): UnattendedMandateAssessment;
+  /** The provider flow an unattended renewal charge must be dispatched under. */
+  unattendedChargeFlow: string;
+  payerContext: PayerContextRequirements;
+  methodHealth: PaymentMethodHealthExpectations;
+  /** How this rail reports a terminal outcome, and when its silence stops being normal. */
+  terminalOutcomeReporting: TerminalOutcomeReporting;
+  /**
+   * The stored consent belongs to one subscription rather than to the payer
+   * account, so persisting it from a webhook must use the subscription-scoped
+   * guarded write.
+   */
+  mandateUpsertIsSubscriptionScoped: boolean;
+}
+
+/** Lookup of published capabilities, keyed by provider kind. */
+export interface PaymentProviderCapabilityRegistry {
+  /** The descriptor published for this kind, or null when the kind is unknown. */
+  get(providerKind: string): PaymentProviderCapabilityDescriptor | null;
+  /** Every published kind, for inventory and conformance proofs. */
+  kinds(): readonly string[];
+}

package/src/platform-runtime/contracts.ts

@@ -0,0 +1,33 @@
+// Platform-runtime shared contracts.
+// Provider-neutral types only: no I/O, no concrete host/provider presets. Host
+// composition and bundle catalogs stay downstream.
+
+/** @beta */
+export type PlatformBundleId = string;
+
+/** Capability surfaces a runtime bundle can bind. */
+/** @beta */
+export type PlatformCapability =
+  | "http"
+  | "scheduler"
+  | "blob"
+  | "data"
+  | "migrations"
+  | "analytics"
+  | "transactional";
+
+/** @beta */
+export type PlatformBundleIdGuard<TId extends string = PlatformBundleId> = (value: unknown) => value is TId;
+
+/** @beta */
+export function createPlatformBundleIdGuard<const TIds extends readonly string[]>(
+  ids: TIds,
+): PlatformBundleIdGuard<TIds[number]> {
+  for (const id of ids) {
+    if (!id || id.trim() !== id) {
+      throw new Error("Platform bundle ids must be non-empty and trimmed");
+    }
+  }
+  const allowed = new Set<string>(ids);
+  return (value: unknown): value is TIds[number] => typeof value === "string" && allowed.has(value);
+}

package/src/platform-runtime/index.ts

@@ -0,0 +1,36 @@
+/** @beta */
+export {
+  createPlatformBundleIdGuard,
+} from "./contracts.js";
+/** @beta */
+export type {
+  PlatformBundleId,
+  PlatformBundleIdGuard,
+  PlatformCapability,
+} from "./contracts.js";
+/** @beta */
+export {
+  createPlatformBundleRegistry,
+  platformEnvSchema,
+} from "./platformKernel.js";
+/** @beta */
+export type {
+  CreatePlatformBundleRegistryInput,
+  PlatformBundleDescriptor,
+  PlatformBundleRegistry,
+  PlatformBundleReadiness,
+  PlatformEnv,
+  PlatformEnvInput,
+} from "./platformKernel.js";
+/** @beta */
+export type {
+  AnalyticsPort,
+  BlobStoragePort,
+  DataGatewayPort,
+  HttpRuntimePort,
+  MigrationRunnerPort,
+  PlatformHttpRequest,
+  PlatformHttpResponse,
+  SchedulerPort,
+  TransactionalRuntimePort,
+} from "./ports.js";

package/src/platform-runtime/platformKernel.ts

@@ -0,0 +1,86 @@
+import { z } from "zod";
+
+import { createPlatformBundleIdGuard, type PlatformBundleId, type PlatformCapability } from "./contracts.js";
+
+/** @beta */
+export interface PlatformBundleReadiness {
+  ok: boolean;
+  error?: string;
+}
+
+/** @beta */
+export interface PlatformBundleDescriptor {
+  id: PlatformBundleId;
+  /** Declarative capability provider kind, bound by downstream composition. */
+  capabilities: Record<PlatformCapability, string>;
+  readReadiness(env: PlatformEnvInput): PlatformBundleReadiness;
+}
+
+/** @beta */
+export type PlatformEnvInput = Record<string, string | undefined>;
+
+/** @beta */
+export const platformEnvSchema = z.object({
+  PLATFORM_BUNDLE: z.string().trim().min(1).optional(),
+  APP_BASE_URL: z.string().url().optional(),
+});
+
+/** @beta */
+export type PlatformEnv = z.infer<typeof platformEnvSchema>;
+
+/** @beta */
+export interface PlatformBundleRegistry<TId extends string = PlatformBundleId> {
+  readonly defaultBundleId: TId;
+  readonly bundleIds: readonly TId[];
+  readonly descriptors: readonly PlatformBundleDescriptor[];
+  isBundleId(value: unknown): value is TId;
+  resolveBundleId(env: PlatformEnvInput): TId;
+  getBundleDescriptor(id: TId): PlatformBundleDescriptor;
+}
+
+/** @beta */
+export interface CreatePlatformBundleRegistryInput<TId extends string = PlatformBundleId> {
+  descriptors: readonly PlatformBundleDescriptor[];
+  defaultBundleId: TId;
+}
+
+/** @beta */
+export function createPlatformBundleRegistry<const TIds extends readonly string[]>(
+  input: {
+    descriptors: readonly (PlatformBundleDescriptor & { id: TIds[number] })[];
+    defaultBundleId: TIds[number];
+  },
+): PlatformBundleRegistry<TIds[number]> {
+  const bundleIds = input.descriptors.map((descriptor) => descriptor.id) as unknown as TIds;
+  const isBundleId = createPlatformBundleIdGuard(bundleIds);
+  const descriptorsById = new Map<TIds[number], PlatformBundleDescriptor>();
+
+  for (const descriptor of input.descriptors) {
+    if (descriptorsById.has(descriptor.id)) {
+      throw new Error(`Duplicate platform bundle descriptor: ${descriptor.id}`);
+    }
+    descriptorsById.set(descriptor.id, descriptor);
+  }
+
+  if (!descriptorsById.has(input.defaultBundleId)) {
+    throw new Error(`Default platform bundle is not declared: ${input.defaultBundleId}`);
+  }
+
+  return {
+    defaultBundleId: input.defaultBundleId,
+    bundleIds,
+    descriptors: input.descriptors,
+    isBundleId,
+    resolveBundleId(env) {
+      const raw = env.PLATFORM_BUNDLE;
+      return isBundleId(raw) ? raw : input.defaultBundleId;
+    },
+    getBundleDescriptor(id) {
+      const descriptor = descriptorsById.get(id);
+      if (!descriptor) {
+        throw new Error(`Unknown platform bundle descriptor: ${id}`);
+      }
+      return descriptor;
+    },
+  };
+}