@openlup/platform 0.17.0 → 0.18.0

package/src/catalog/contracts/lifecycle.ts

@@ -0,0 +1,74 @@
+/**
+ * Lifecycle observations are additive DTOs, not changes to existing wire status.
+ * SKU draft/active/archived and draft receipt open/abandoned remain unchanged.
+ * Map archived to withdrawn only where an authority establishes that meaning;
+ * abandoning a draft never implies withdrawing the active variant.
+ */
+export type CatalogVariantState = "draft" | "active" | "withdrawn";
+
+export interface CatalogHeadRef {
+  publicationId: string;
+  revision: number;
+  documentDigest: string;
+}
+
+export interface CatalogLifecycleObservation {
+  productId: string;
+  variantId: string;
+  sku: string;
+  state: CatalogVariantState;
+  variantRevision: number;
+  /** Null means known unpublished, never unknown publication lineage. */
+  publicationHead: CatalogHeadRef | null;
+  draftRef: { draftId: string; revision: number } | null;
+}
+
+export interface CatalogPublishCommand {
+  commandKey: string;
+  productId: string;
+  candidateRef: string;
+  candidateDigest: string;
+  expectedHead: CatalogHeadRef | null;
+  changes: readonly {
+    variantId: string;
+    expectedRevision: number;
+    state: "active" | "withdrawn";
+  }[];
+}
+
+export interface CatalogPublicationReceipt {
+  commandKey: string;
+  fingerprint: string;
+  actorId: string;
+  previousHead: CatalogHeadRef | null;
+  head: CatalogHeadRef;
+  changes: readonly CatalogLifecycleObservation[];
+}
+
+/** Named refusals contain no arbitrary provider diagnostics. */
+export interface CatalogPublicationRefusal {
+  outcome: "unauthorized" | "validation_issue" | "conflict" | "dependency_unavailable" | "unsupported";
+  reason: "publisher_not_authorized" | "candidate_invalid" | "head_conflict"
+    | "publication_authority_unavailable" | "publication_not_supported";
+}
+
+/** Success requires coherent authoritative document and lifecycle facts. */
+export type CatalogPublicationReadResult =
+  | { outcome: "found"; head: CatalogHeadRef; documentRef: string; observations: readonly CatalogLifecycleObservation[] }
+  | { outcome: "unpublished" }
+  | CatalogPublicationRefusal;
+
+/** Absence is distinct from an unavailable or unsupported authority. */
+export type CatalogPublicationReceiptResult =
+  | { outcome: "found"; receipt: CatalogPublicationReceipt }
+  | { outcome: "absent" }
+  | CatalogPublicationRefusal;
+
+/**
+ * Authority-owned history, newest publication revision first with stable ordering.
+ * Limit is an integer from 1 through 100; receipts never exceed limit.
+ * nextCursor is opaque, and null only when no further page exists.
+ */
+export type CatalogHistoryResult =
+  | { outcome: "page"; receipts: readonly CatalogPublicationReceipt[]; limit: number; nextCursor: string | null }
+  | CatalogPublicationRefusal;

package/src/catalog/contracts/productMediaContracts.ts

@@ -0,0 +1,170 @@
+/** Provider-free source metadata. Delivery URLs are supplied projections. */
+export type ProductMediaRole = "primary" | "view" | "illustration";
+export interface ProductMediaAsset {
+  assetRef: string;
+  source: string;
+  contentType: "image/jpeg" | "image/png" | "image/webp";
+  byteLength: number;
+  sha256: string;
+  artworkLocale: string | null;
+}
+export interface ProductMediaProduct {
+  productId: string;
+  variantIds: readonly string[];
+  primaryVariantId: string;
+}
+export interface ProductMediaAssociation {
+  itemId: string;
+  assetRef: string;
+  productId: string;
+  scope: "product" | "variant";
+  variantId?: string;
+  locale: string | null;
+  role: ProductMediaRole;
+  viewKey?: string;
+  order: number;
+  label: string;
+}
+export interface ProductMediaManifest {
+  schemaVersion: 1;
+  assets: readonly ProductMediaAsset[];
+  products: readonly ProductMediaProduct[];
+  associations: readonly ProductMediaAssociation[];
+}
+export interface ProductMediaRequest { productId: string; variantId: string; locale: string }
+export interface ResolvedProductMediaItem {
+  id: string; assetRef: string; src: string; label: string; role: ProductMediaRole;
+}
+export interface ResolvedProductMedia {
+  key: string;
+  revision: string;
+  items: readonly ResolvedProductMediaItem[];
+  primaryItemId: string | null;
+}
+export interface StorefrontProductMedia {
+  productId: string;
+  locale: string;
+  primaryVariantId: string;
+  collections: Readonly<Record<string, ResolvedProductMedia>>;
+}
+export const PRODUCT_MEDIA_LIMITS = Object.freeze({
+  assets: 512, products: 256, variants: 1024, associations: 8192,
+  imageBytes: 358400, totalBytes: 128 * 1024 * 1024,
+  manifestBytes: 2 * 1024 * 1024, resolvedItems: 32,
+});
+export type ProductMediaValidationCode = "invalid_schema" | "duplicate_identity" |
+  "unsafe_path" | "undeclared_variant" | "missing_resource" | "conflicting_primary" |
+  "collection_limit_exceeded" | "pack_limit_exceeded";
+export class ProductMediaValidationError extends Error {
+  constructor(readonly code: ProductMediaValidationCode, readonly reference: string) {
+    super(`${code}: ${reference}`);
+    this.name = "ProductMediaValidationError";
+  }
+}
+function refuse(code: ProductMediaValidationCode, reference: string): never {
+  throw new ProductMediaValidationError(code, reference);
+}
+function record(value: unknown, reference: string): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) refuse("invalid_schema", reference);
+  return value as Record<string, unknown>;
+}
+function fields(value: Record<string, unknown>, allowed: readonly string[], reference: string): void {
+  if (Object.keys(value).some((key) => !allowed.includes(key))) refuse("invalid_schema", reference);
+}
+function text(value: unknown, reference: string, max = 256): string {
+  if (typeof value !== "string" || !value.trim() || value.length > max || Array.from(value).some((char) => char.charCodeAt(0) < 32 || char.charCodeAt(0) === 127)) {
+    refuse("invalid_schema", reference);
+  }
+  return value;
+}
+function locale(value: unknown, reference: string): void {
+  if (value !== null) text(value, reference, 64);
+}
+function array(value: unknown, reference: string, limit: number): unknown[] {
+  if (!Array.isArray(value)) refuse("invalid_schema", reference);
+  if (value.length > limit) refuse("pack_limit_exceeded", reference);
+  return value;
+}
+function unique(set: Set<string>, id: string): void {
+  if (set.has(id)) refuse("duplicate_identity", id);
+  set.add(id);
+}
+/** Checks contained relative resource bindings; the resource owner also checks symlinks. */
+export function validateProductMediaSourcePath(value: unknown): string {
+  const source = text(value, "source", 512);
+  if (source.startsWith("/") || /[:\\%?#]/u.test(source) || source.split("/").some((part) => !part || part === "." || part === "..")) {
+    refuse("unsafe_path", "source");
+  }
+  return source;
+}
+/** Structural authoring/pack validation. Signatures and digests require the source bytes. */
+export function validateProductMediaManifest(value: unknown): ProductMediaManifest {
+  const manifest = record(value, "manifest");
+  fields(manifest, ["schemaVersion", "assets", "products", "associations"], "manifest");
+  if (manifest.schemaVersion !== 1) refuse("invalid_schema", "schemaVersion");
+  const assets = array(manifest.assets, "assets", PRODUCT_MEDIA_LIMITS.assets);
+  const products = array(manifest.products, "products", PRODUCT_MEDIA_LIMITS.products);
+  const associations = array(manifest.associations, "associations", PRODUCT_MEDIA_LIMITS.associations);
+  const assetIds = new Set<string>();
+  let totalBytes = 0;
+  for (const entry of assets) {
+    const asset = record(entry, "asset");
+    fields(asset, ["assetRef", "source", "contentType", "byteLength", "sha256", "artworkLocale"], "asset");
+    const id = text(asset.assetRef, "assetRef");
+    unique(assetIds, id);
+    validateProductMediaSourcePath(asset.source);
+    if (!["image/jpeg", "image/png", "image/webp"].includes(asset.contentType as string)) refuse("invalid_schema", id);
+    if (!Number.isSafeInteger(asset.byteLength) || (asset.byteLength as number) <= 0) refuse("invalid_schema", id);
+    if ((asset.byteLength as number) > PRODUCT_MEDIA_LIMITS.imageBytes) refuse("pack_limit_exceeded", id);
+    totalBytes += asset.byteLength as number;
+    if (totalBytes > PRODUCT_MEDIA_LIMITS.totalBytes) refuse("pack_limit_exceeded", "totalBytes");
+    if (typeof asset.sha256 !== "string" || !/^[a-f0-9]{64}$/u.test(asset.sha256)) refuse("invalid_schema", id);
+    locale(asset.artworkLocale, id);
+  }
+  const productVariants = new Map<string, Set<string>>();
+  let variantCount = 0;
+  for (const entry of products) {
+    const product = record(entry, "product");
+    fields(product, ["productId", "variantIds", "primaryVariantId"], "product");
+    const id = text(product.productId, "productId");
+    if (productVariants.has(id)) refuse("duplicate_identity", id);
+    const variants = new Set<string>();
+    for (const variant of array(product.variantIds, id, PRODUCT_MEDIA_LIMITS.variants)) unique(variants, text(variant, id));
+    variantCount += variants.size;
+    if (variantCount > PRODUCT_MEDIA_LIMITS.variants) refuse("pack_limit_exceeded", "variants");
+    const primary = text(product.primaryVariantId, id);
+    if (!variants.has(primary)) refuse("undeclared_variant", primary);
+    productVariants.set(id, variants);
+  }
+  const referencedAssets = new Set<string>();
+  const identities = new Map<string, string>();
+  const localizedIds = new Set<string>();
+  for (const entry of associations) {
+    const item = record(entry, "association");
+    fields(item, ["itemId", "assetRef", "productId", "scope", "variantId", "locale", "role", "viewKey", "order", "label"], "association");
+    const id = text(item.itemId, "itemId");
+    const assetRef = text(item.assetRef, id);
+    if (!assetIds.has(assetRef)) refuse("missing_resource", assetRef);
+    referencedAssets.add(assetRef);
+    const productId = text(item.productId, id);
+    const variants = productVariants.get(productId);
+    if (!variants) refuse("invalid_schema", productId);
+    if (item.scope !== "product" && item.scope !== "variant") refuse("invalid_schema", id);
+    if (item.scope === "product" && item.variantId !== undefined) refuse("invalid_schema", id);
+    if (item.scope === "variant") {
+      const variantId = text(item.variantId, id);
+      if (!variants.has(variantId)) refuse("undeclared_variant", variantId);
+    }
+    locale(item.locale, id);
+    if (!["primary", "view", "illustration"].includes(item.role as string)) refuse("invalid_schema", id);
+    if (item.viewKey !== undefined) text(item.viewKey, id);
+    if (!Number.isSafeInteger(item.order)) refuse("invalid_schema", id);
+    text(item.label, id, 1024);
+    const identity = JSON.stringify([productId, item.scope, item.variantId, item.role, item.viewKey]);
+    if (identities.has(id) && identities.get(id) !== identity) refuse("duplicate_identity", id);
+    identities.set(id, identity);
+    unique(localizedIds, JSON.stringify([id, item.locale]));
+  }
+  for (const id of assetIds) if (!referencedAssets.has(id)) refuse("missing_resource", id);
+  return value as ProductMediaManifest;
+}

package/src/catalog/contracts/productTypes.ts

@@ -0,0 +1,35 @@
+export type CatalogQuantityDimension = "mass" | "volume" | "count";
+export interface CatalogQuantity { dimension: CatalogQuantityDimension; unscaled: string; scale: number; unit: string }
+export type CatalogOptionValue =
+  | { kind: "choice"; value: string }
+  | { kind: "quantity"; value: CatalogQuantity }
+  | { kind: "boolean"; value: boolean };
+export type CatalogDraftIssue = { path: string; code: string };
+export interface CatalogProductTypeRef { key: string; version: number }
+export interface CatalogProductTypeDefinition extends CatalogProductTypeRef {
+  units: { code: string; dimension: CatalogQuantityDimension; integral: boolean }[];
+  netContentUnits: string[];
+  dimensions: (
+    | { key: string; kind: "choice"; values: string[] }
+    | { key: string; kind: "quantity"; dimension: CatalogQuantityDimension; units: string[]; role?: "net_content" }
+    | { key: string; kind: "boolean" }
+  )[];
+  validateContent: (content: unknown) => readonly CatalogDraftIssue[];
+}
+export interface CatalogProductTypeRegistry {
+  resolve(ref: CatalogProductTypeRef): CatalogProductTypeDefinition | undefined;
+}
+
+export function validateCatalogQuantity(quantity: CatalogQuantity, definition: CatalogProductTypeDefinition): boolean {
+  const unit = definition.units.find(({ code }) => code === quantity.unit);
+  return !!unit && unit.dimension === quantity.dimension
+    && (!unit.integral || BigInt(quantity.unscaled) % (10n ** BigInt(quantity.scale)) === 0n);
+}
+
+/** Decimal spelling cannot make two equal option values distinct. No unit conversion is inferred. */
+export function canonicalCatalogOption(value: CatalogOptionValue): string {
+  if (value.kind !== "quantity") return JSON.stringify(value);
+  let { unscaled, scale } = value.value;
+  while (scale > 0 && unscaled.endsWith("0")) { unscaled = unscaled.slice(0, -1); scale -= 1; }
+  return JSON.stringify(["quantity", value.value.dimension, value.value.unit, unscaled, scale]);
+}

package/src/catalog/contracts/resolveProductMedia.ts

@@ -0,0 +1,85 @@
+import {
+  PRODUCT_MEDIA_LIMITS, ProductMediaValidationError, validateProductMediaManifest,
+  type ProductMediaAssociation, type ProductMediaManifest, type ProductMediaRequest,
+  type ResolvedProductMedia,
+} from "./productMediaContracts.js";
+
+const hasControls = (value: string): boolean => Array.from(value).some((char) => char.charCodeAt(0) < 32 || char.charCodeAt(0) === 127);
+const compareText = (a: string, b: string): number => a < b ? -1 : a > b ? 1 : 0;
+const ordered = (a: ProductMediaAssociation, b: ProductMediaAssociation): number =>
+  a.order - b.order || compareText(a.itemId, b.itemId);
+
+/** A deterministic browser-safe fingerprint, not a cryptographic integrity receipt. */
+function fingerprint(value: string): string {
+  return [0x811c9dc5, 0x9e3779b9, 0x85ebca6b, 0xc2b2ae35].map((seed) => {
+    let hash = seed;
+    for (let index = 0; index < value.length; index++) hash = Math.imul(hash ^ value.charCodeAt(index), 0x01000193);
+    return (hash >>> 0).toString(16).padStart(8, "0");
+  }).join("");
+}
+function revision(source: ProductMediaManifest, urls: Readonly<Record<string, string>>): string {
+  const assets = [...source.assets].sort((a, b) => compareText(a.assetRef, b.assetRef)).map((a) =>
+    [a.assetRef, a.source, a.contentType, a.byteLength, a.sha256, a.artworkLocale, Object.prototype.hasOwnProperty.call(urls, a.assetRef) ? urls[a.assetRef] : null]);
+  const products = [...source.products].sort((a, b) => compareText(a.productId, b.productId)).map((p) =>
+    [p.productId, [...p.variantIds].sort(compareText), p.primaryVariantId]);
+  const associations = source.associations.map((a) =>
+    [a.itemId, a.assetRef, a.productId, a.scope, a.variantId ?? null, a.locale, a.role, a.viewKey ?? null, a.order, a.label]
+  ).sort((a, b) => compareText(JSON.stringify(a), JSON.stringify(b)));
+  return fingerprint(JSON.stringify([source.schemaVersion, assets, products, associations]));
+}
+function survives(a: ProductMediaAssociation, b: ProductMediaAssociation, locale: string): boolean {
+  const ranks = (item: ProductMediaAssociation) => [item.role === "primary" ? 1 : 0,
+    item.scope === "variant" ? 1 : 0, item.locale === locale ? 1 : 0];
+  const ar = ranks(a), br = ranks(b);
+  for (let index = 0; index < ar.length; index++) if (ar[index] !== br[index]) return ar[index]! > br[index]!;
+  return ordered(a, b) < 0;
+}
+/** Resolve only declared variant/product material; no filename, SKU or provider inference. */
+export function resolveProductMedia(
+  value: ProductMediaManifest,
+  request: ProductMediaRequest,
+  assetUrls: Readonly<Record<string, string>>,
+): ResolvedProductMedia {
+  const source = validateProductMediaManifest(value);
+  const product = source.products.find((p) => p.productId === request.productId);
+  if (!product || !product.variantIds.includes(request.variantId)) {
+    throw new ProductMediaValidationError("undeclared_variant", request.variantId);
+  }
+  if (typeof request.locale !== "string" || !request.locale.trim() || request.locale.length > 64 || hasControls(request.locale)) {
+    throw new ProductMediaValidationError("invalid_schema", "locale");
+  }
+  const logicalItems = new Map<string, ProductMediaAssociation>();
+  for (const item of source.associations) {
+    if (item.productId !== request.productId || (item.scope === "variant" && item.variantId !== request.variantId)) continue;
+    if (item.locale !== null && item.locale !== request.locale) continue;
+    const current = logicalItems.get(item.itemId);
+    if (!current || item.locale === request.locale) logicalItems.set(item.itemId, item);
+  }
+  const applicable = [...logicalItems.values()];
+  if (applicable.filter((item) => item.role === "primary").length > 1) {
+    throw new ProductMediaValidationError("conflicting_primary", request.productId);
+  }
+  const uniqueAssets = new Map<string, ProductMediaAssociation>();
+  for (const item of applicable) {
+    const current = uniqueAssets.get(item.assetRef);
+    if (!current || survives(item, current, request.locale)) uniqueAssets.set(item.assetRef, item);
+  }
+  if (uniqueAssets.size > PRODUCT_MEDIA_LIMITS.resolvedItems) {
+    throw new ProductMediaValidationError("collection_limit_exceeded", request.productId);
+  }
+  const items = [...uniqueAssets.values()].sort(ordered).map((item) => {
+    const src = Object.prototype.hasOwnProperty.call(assetUrls, item.assetRef) ? assetUrls[item.assetRef] : undefined;
+    if (typeof src !== "string" || !src.trim()) throw new ProductMediaValidationError("missing_resource", item.assetRef);
+    // The projection may contain opaque relative delivery paths or HTTP(S) URLs only.
+    if (/^[a-z][a-z\d+.-]*:/iu.test(src) && !/^https?:\/\//iu.test(src) || /^\s/u.test(src) || hasControls(src)) {
+      throw new ProductMediaValidationError("unsafe_path", item.assetRef);
+    }
+    return { id: item.itemId, assetRef: item.assetRef, src, label: item.label, role: item.role };
+  });
+  const mediaRevision = revision(source, assetUrls);
+  return {
+    key: JSON.stringify([request.productId, request.variantId, request.locale, mediaRevision]),
+    revision: mediaRevision, items,
+    primaryItemId: items.find((item) => item.role === "primary")?.id ?? null,
+  };
+}

package/src/catalog/contracts/sellable.ts

@@ -0,0 +1,12 @@
+export const SELLABLE_CATALOG_CONTRACT_VERSION = "catalog.sellable.v1";
+export interface SellableCatalogItem {
+  sku: string; title: string; unitPrice: { amountMinor: number; currency: string };
+  permittedPurchaseModes: ("one_time" | "subscription")[];
+}
+export interface SellableCatalogProfile {
+  id: string; brand: string; country: string; currency: string; locale: string; timezone: string;
+}
+export interface SellableCatalogListResponse {
+  contractVersion: typeof SELLABLE_CATALOG_CONTRACT_VERSION;
+  profile: SellableCatalogProfile; items: SellableCatalogItem[];
+}

package/src/catalog/draftHandler.ts

@@ -0,0 +1,105 @@
+import { createHash } from "node:crypto";
+import {
+  canonicalCatalogDraftJson, catalogDraftApplyResultSchema, catalogDraftCommandSchema,
+  catalogDraftGetQuerySchema, catalogDraftListQuerySchema, catalogDraftPageSchema,
+  catalogDraftRecordSchema, catalogDraftRefusalSchema,
+  type CatalogDraftApplyResult, type CatalogDraftPage, type CatalogDraftRecord, type CatalogDraftRefusal,
+} from "./draftSchemas.js";
+import {
+  CatalogDraftStoreError, type CatalogDraftOperator, type CatalogDraftStorePort,
+} from "./draftPorts.js";
+import type { CatalogDraftIssue, CatalogProductTypeRegistry } from "./productTypeSchemas.js";
+import { validateCatalogDraft, type CatalogDraftReadiness } from "./draftValidation.js";
+
+export interface CatalogDraftHandlerDeps<Context> {
+  store: CatalogDraftStorePort;
+  registry: CatalogProductTypeRegistry;
+  authorizeOperator: (context: Context) => Promise<CatalogDraftOperator | null>;
+}
+export type CatalogDraftCommandResult = CatalogDraftApplyResult & {
+  issues?: readonly CatalogDraftIssue[]; readiness?: CatalogDraftReadiness;
+};
+const unavailable = (): CatalogDraftRefusal => ({ outcome: "dependency_unavailable", reason: "draft_dependency_unavailable" });
+const invalid = (): CatalogDraftRefusal => ({ outcome: "validation_issue", reason: "draft_input_invalid" });
+function failure(error: unknown): CatalogDraftRefusal {
+  if (error instanceof CatalogDraftStoreError) {
+    const parsed = catalogDraftRefusalSchema.safeParse(error.refusal);
+    if (parsed.success) return parsed.data;
+  }
+  return unavailable();
+}
+
+/** Dark use case: mounting requires a verified operator authorizer at composition. */
+export function createCatalogDraftHandler<Context>(deps: CatalogDraftHandlerDeps<Context>) {
+  async function actor(context: Context): Promise<CatalogDraftOperator | CatalogDraftRefusal> {
+    try {
+      const operator = await deps.authorizeOperator(context);
+      if (!operator || !/^[^\s].{0,239}$/u.test(operator.actorId) || operator.actorId.trim() !== operator.actorId) {
+        return { outcome: "unauthorized", reason: "draft_operator_required" };
+      }
+      return operator;
+    } catch { return unavailable(); }
+  }
+  return {
+    async execute(input: unknown, context: Context): Promise<CatalogDraftCommandResult> {
+      const operator = await actor(context);
+      if ("outcome" in operator) return operator;
+      let canonicalCommand: string;
+      try { canonicalCommand = canonicalCatalogDraftJson(input); } catch { return invalid(); }
+      const parsed = catalogDraftCommandSchema.safeParse(JSON.parse(canonicalCommand));
+      if (!parsed.success) return invalid();
+      const command = parsed.data;
+      const fingerprint = createHash("sha256").update(canonicalCommand).digest("hex");
+      try {
+        // Read receipts first: changed registry, moved head or abandonment cannot erase a committed command.
+        const original = await deps.store.get({ draftId: command.draftId, commandKey: command.commandKey }, operator.actorId);
+        if (original !== null) {
+          const record = catalogDraftRecordSchema.parse(original);
+          if (record.draftId !== command.draftId || record.commandKey !== command.commandKey) return unavailable();
+          if (record.actorId !== operator.actorId) return { outcome: "unauthorized", reason: "draft_command_actor_mismatch" };
+          if (record.fingerprint !== fingerprint) return { outcome: "conflict", reason: "draft_command_key_reused" };
+          return { outcome: "replayed", record };
+        }
+        let readiness: CatalogDraftReadiness | undefined;
+        if (command.payload) {
+          const validation = validateCatalogDraft(command.payload, deps.registry);
+          if (!validation.valid) return { outcome: "validation_issue", reason: "draft_payload_invalid", issues: validation.issues };
+          readiness = validation.readiness;
+        }
+        const result = catalogDraftApplyResultSchema.parse(await deps.store.apply({ canonicalCommand, fingerprint, actorId: operator.actorId }));
+        if (result.outcome === "committed" || result.outcome === "replayed") {
+          if (result.record.draftId !== command.draftId || result.record.commandKey !== command.commandKey
+            || result.record.fingerprint !== fingerprint || result.record.actorId !== operator.actorId) return unavailable();
+          return { ...result, ...(readiness ? { readiness } : {}) };
+        }
+        return result;
+      } catch (error) { return failure(error); }
+    },
+    async get(input: unknown, context: Context): Promise<{ outcome: "found"; record: CatalogDraftRecord | null } | CatalogDraftRefusal> {
+      const operator = await actor(context);
+      if ("outcome" in operator) return operator;
+      const parsed = catalogDraftGetQuerySchema.safeParse(input);
+      if (!parsed.success) return invalid();
+      try {
+        const value = await deps.store.get(parsed.data, operator.actorId);
+        const record = value === null ? null : catalogDraftRecordSchema.parse(value);
+        if (record && (record.draftId !== parsed.data.draftId
+          || (parsed.data.revision !== undefined && record.revision !== parsed.data.revision)
+          || (parsed.data.commandKey !== undefined && record.commandKey !== parsed.data.commandKey))) return unavailable();
+        return { outcome: "found", record };
+      } catch (error) { return failure(error); }
+    },
+    async list(input: unknown, context: Context): Promise<{ outcome: "listed"; page: CatalogDraftPage } | CatalogDraftRefusal> {
+      const operator = await actor(context);
+      if ("outcome" in operator) return operator;
+      const parsed = catalogDraftListQuerySchema.safeParse(input);
+      if (!parsed.success) return invalid();
+      try {
+        const page = catalogDraftPageSchema.parse(await deps.store.list(parsed.data, operator.actorId));
+        if (page.items.length > parsed.data.limit || (parsed.data.afterDraftId
+          && page.items.some(({ draftId }) => draftId <= parsed.data.afterDraftId!))) return unavailable();
+        return { outcome: "listed", page };
+      } catch (error) { return failure(error); }
+    },
+  };
+}

package/src/catalog/draftPorts.ts

@@ -0,0 +1,18 @@
+import type {
+  CatalogDraftApplyResult, CatalogDraftGetQuery, CatalogDraftListQuery,
+  CatalogDraftPage, CatalogDraftRecord, CatalogDraftRefusal,
+} from "./draftSchemas.js";
+
+/** Portable adapters accept this actor only after the injected operator authorizer succeeds. */
+export interface CatalogDraftOperator { actorId: string }
+export interface CatalogDraftStorePort {
+  apply(input: { canonicalCommand: string; fingerprint: string; actorId: string }): Promise<CatalogDraftApplyResult>;
+  get(query: CatalogDraftGetQuery, actorId: string): Promise<CatalogDraftRecord | null>;
+  list(query: CatalogDraftListQuery, actorId: string): Promise<CatalogDraftPage>;
+}
+export class CatalogDraftStoreError extends Error {
+  constructor(readonly refusal: CatalogDraftRefusal) {
+    super(refusal.reason);
+    this.name = "CatalogDraftStoreError";
+  }
+}

package/src/catalog/draftSchemas.ts

@@ -0,0 +1,88 @@
+import { z } from "./validation.js";
+import { CATALOG_DRAFT_MAX_PAGE, canonicalCatalogDraftJson } from "./contracts/draft.js";
+export { CATALOG_DRAFT_MAX_BYTES, CATALOG_DRAFT_MAX_PAGE, canonicalCatalogDraftJson } from "./contracts/draft.js";
+export type { CatalogDraftPayload, CatalogDraftCommand, CatalogDraftRecord, CatalogDraftSummary, CatalogDraftPage, CatalogDraftRefusal, CatalogDraftApplyResult, CatalogDraftGetQuery, CatalogDraftListQuery } from "./contracts/draft.js";
+import { catalogDocumentRevisionRefSchema } from "./foundationSchemas.js";
+import {
+  catalogDimensionKeySchema, catalogNamespacedKeySchema, catalogOptionValueSchema,
+  catalogProductTypeRefSchema, catalogQuantitySchema,
+} from "./productTypeSchemas.js";
+
+const id = z.guid().refine((value) => value === value.toLowerCase(), "UUID must be lowercase");
+const reference = z.string().min(1).max(240).refine((value) => value.trim() === value);
+const code = z.string().min(1).max(160).regex(/^[A-Za-z0-9._:-]+$/u);
+const revision = z.number().int().min(0).max(2_147_483_646);
+const persistedRevision = z.number().int().positive().max(2_147_483_647);
+const commandKey = reference;
+const jsonContent = z.unknown().refine((value) => value !== undefined, "content must be JSON");
+export const catalogDraftPayloadSchema = z.object({
+  schemaVersion: z.literal(1),
+  product: z.object({
+    id, type: catalogProductTypeRefSchema, slug: code.optional(), primarySkuId: id.optional(),
+    dimensions: z.array(catalogDimensionKeySchema).max(16),
+    sharedContent: jsonContent.optional(), documentRevision: catalogDocumentRevisionRefSchema.optional(),
+  }).strict(),
+  skus: z.array(z.object({
+    id, productId: id, code: code.optional(),
+    options: z.record(catalogDimensionKeySchema, catalogOptionValueSchema),
+    netContent: catalogQuantitySchema.optional(),
+    identifiers: z.array(z.object({
+      scheme: catalogNamespacedKeySchema, issuer: reference, value: z.string().min(1).max(128),
+      packagingLevel: z.enum(["unit", "case"]), quantity: z.number().int().min(1).max(2_147_483_647).optional(),
+    }).strict()).max(32).optional(),
+    assetRefs: z.array(reference).max(32).optional(), grossMass: catalogQuantitySchema.optional(),
+    priceRef: reference.optional(), logisticsRef: reference.optional(),
+  }).strict()).max(10_000),
+}).strict().superRefine((payload, context) => {
+  try { canonicalCatalogDraftJson(payload); } catch { context.addIssue({ code: "custom", message: "payload must be bounded safe JSON" }); }
+  if (payload.product.documentRevision && payload.product.documentRevision.productId !== payload.product.id) {
+    context.addIssue({ code: "custom", path: ["product", "documentRevision", "productId"], message: "document must belong to product" });
+  }
+  if (payload.product.primarySkuId && !payload.skus.some((sku) => sku.id === payload.product.primarySkuId)) {
+    context.addIssue({ code: "custom", path: ["product", "primarySkuId"], message: "primary must belong to product" });
+  }
+  payload.skus.forEach((sku, index) => {
+    if (sku.productId !== payload.product.id) context.addIssue({ code: "custom", path: ["skus", index, "productId"], message: "SKU must belong to product" });
+  });
+});
+export const catalogDraftCommandSchema = z.object({
+  schemaVersion: z.literal(1), action: z.enum(["create", "revise", "abandon"]),
+  draftId: id, commandKey, expectedRevision: revision, payload: catalogDraftPayloadSchema.optional(),
+}).strict().superRefine((command, context) => {
+  if ((command.action === "abandon") === (command.payload !== undefined)) {
+    context.addIssue({ code: "custom", path: ["payload"], message: "payload is required only for create and revise" });
+  }
+  if ((command.action === "create") !== (command.expectedRevision === 0)) {
+    context.addIssue({ code: "custom", path: ["expectedRevision"], message: "create starts at revision zero; other commands require a persisted revision" });
+  }
+});
+export const catalogDraftGetQuerySchema = z.object({
+  draftId: id, revision: persistedRevision.optional(), commandKey: commandKey.optional(),
+}).strict().refine((query) => query.revision === undefined || query.commandKey === undefined, "selectors are mutually exclusive");
+export const catalogDraftListQuerySchema = z.object({
+  afterDraftId: id.optional(), limit: z.number().int().min(1).max(CATALOG_DRAFT_MAX_PAGE),
+}).strict();
+export const catalogDraftSummarySchema = z.object({
+  draftId: id, productId: id, revision: persistedRevision, status: z.enum(["open", "abandoned"]),
+  commandKey, fingerprint: z.string().regex(/^[a-f0-9]{64}$/u), actorId: reference,
+  createdAt: z.string().datetime({ offset: true }),
+}).strict();
+export const catalogDraftRecordSchema = catalogDraftSummarySchema.extend({ payload: catalogDraftPayloadSchema }).strict()
+  .refine((record) => record.productId === record.payload.product.id, "record product must own payload");
+export const catalogDraftPageSchema = z.object({
+  items: z.array(catalogDraftSummarySchema).max(CATALOG_DRAFT_MAX_PAGE), nextCursor: id.nullable(),
+}).strict().superRefine((page, context) => {
+  const ids = page.items.map((item) => item.draftId);
+  if (ids.some((value, index) => index > 0 && value <= ids[index - 1])
+    || (page.nextCursor !== null && page.nextCursor !== ids[ids.length - 1])) {
+    context.addIssue({ code: "custom", message: "page must have ordered unique heads and a matching cursor" });
+  }
+});
+export const catalogDraftRefusalSchema = z.object({
+  outcome: z.enum(["conflict", "validation_issue", "unauthorized", "dependency_unavailable"]),
+  reason: z.string().min(1).max(160).regex(/^[a-z][a-z0-9_]*$/u), currentRevision: z.number().int().min(0).max(2_147_483_647).optional(),
+}).strict();
+export const catalogDraftApplyResultSchema = z.union([
+  z.object({ outcome: z.enum(["committed", "replayed"]), record: catalogDraftRecordSchema }).strict(),
+  catalogDraftRefusalSchema,
+]);