@open-mercato/shared 0.8.1-develop.7263.1.bbc6db3437 → 0.8.1-develop.7267.1.2e95af80a6

package/.turbo/turbo-build.log

@@ -1,2 +1,2 @@
-[build:shared] found 297 entry points
+[build:shared] found 293 entry points
 [build:shared] built successfully

package/dist/lib/version.js

@@ -1,4 +1,4 @@
-const APP_VERSION = "0.8.1-develop.7263.1.bbc6db3437";
+const APP_VERSION = "0.8.1-develop.7267.1.2e95af80a6";
 const appVersion = APP_VERSION;
 export {
   APP_VERSION,

package/dist/lib/version.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/lib/version.ts"],
-  "sourcesContent": ["// Build-time generated version\nexport const APP_VERSION = '0.8.1-develop.7263.1.bbc6db3437';\nexport const appVersion = APP_VERSION;\n"],
+  "sourcesContent": ["// Build-time generated version\nexport const APP_VERSION = '0.8.1-develop.7267.1.2e95af80a6';\nexport const appVersion = APP_VERSION;\n"],
   "mappings": "AACO,MAAM,cAAc;AACpB,MAAM,aAAa;",
   "names": []
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/shared",
-  "version": "0.8.1-develop.7263.1.bbc6db3437",
+  "version": "0.8.1-develop.7267.1.2e95af80a6",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -12,10 +12,6 @@
   },
   "exports": {
     ".": "./dist/index.js",
-    "./lib/availability": {
-      "types": "./src/lib/availability/index.ts",
-      "default": "./dist/lib/availability/index.js"
-    },
     "./lib/openapi": {
       "types": "./src/lib/openapi/index.ts",
       "default": "./dist/lib/openapi/index.js"
@@ -117,7 +113,7 @@
     "@mikro-orm/core": "^7.1.14",
     "@mikro-orm/decorators": "^7.1.14",
     "@mikro-orm/postgresql": "^7.1.14",
-    "@open-mercato/cache": "0.8.1-develop.7263.1.bbc6db3437",
+    "@open-mercato/cache": "0.8.1-develop.7267.1.2e95af80a6",
     "@types/html-to-text": "^9.0.4",
     "@types/sanitize-html": "^2.16.1",
     "dotenv": "^17.4.2",

package/dist/lib/availability/catalogOnlyProvider.js

@@ -1,65 +0,0 @@
-import { availabilityItemKey } from "./types.js";
-import { availabilityProviderRegistry, AVAILABILITY_CATALOG_ONLY_PROVIDER_ID } from "./registry.js";
-let policyLookup = null;
-function setCatalogOnlyPolicyLookup(lookup) {
-  policyLookup = lookup;
-}
-function pureFallbackItem() {
-  return {
-    state: "not_tracked",
-    availableQuantity: null,
-    canFulfil: true,
-    leadTimeDays: null,
-    releaseAt: null,
-    isAuthoritative: true,
-    policySourceId: null
-  };
-}
-function applyOverride(override) {
-  const base = pureFallbackItem();
-  if (!override) return base;
-  const policySourceId = override.policySourceId ?? null;
-  if (override.preorderReleaseAt) {
-    const releaseAt = new Date(override.preorderReleaseAt);
-    if (!Number.isNaN(releaseAt.getTime()) && releaseAt.getTime() > Date.now()) {
-      return {
-        ...base,
-        state: "preorder",
-        canFulfil: true,
-        releaseAt: override.preorderReleaseAt,
-        policySourceId
-      };
-    }
-  }
-  if (override.isActive === false) {
-    return { ...base, state: "out_of_stock", canFulfil: false, policySourceId };
-  }
-  if (override.isStockManaged === true) {
-    return { ...base, state: "out_of_stock", canFulfil: false, policySourceId };
-  }
-  return { ...base, policySourceId };
-}
-async function getAvailability(query) {
-  const byItem = {};
-  let overrides = {};
-  if (policyLookup) {
-    try {
-      overrides = await policyLookup(query);
-    } catch {
-      overrides = {};
-    }
-  }
-  for (const item of query.items) {
-    const key = availabilityItemKey(item);
-    byItem[key] = applyOverride(overrides[key]);
-  }
-  return { byItem };
-}
-availabilityProviderRegistry.register({
-  id: AVAILABILITY_CATALOG_ONLY_PROVIDER_ID,
-  getAvailability
-});
-export {
-  setCatalogOnlyPolicyLookup
-};
-//# sourceMappingURL=catalogOnlyProvider.js.map

package/dist/lib/availability/catalogOnlyProvider.js.map

@@ -1,7 +0,0 @@
-{
-  "version": 3,
-  "sources": ["../../../src/lib/availability/catalogOnlyProvider.ts"],
-  "sourcesContent": ["/**\n * The built-in `catalog-only` fallback provider. Always registered so a\n * `wms`-less *and* `availability`-less storefront stays fully functional.\n *\n * @see .ai/specs/2026-08-14-availability-contract.md \u00A74.3\n */\n\nimport { availabilityItemKey } from './types'\nimport type { AvailabilityItemResult, AvailabilityQuery, AvailabilityResult } from './types'\nimport { availabilityProviderRegistry, AVAILABILITY_CATALOG_ONLY_PROVIDER_ID } from './registry'\n\n/** Per-item policy signal the optional lookup hook may report. */\nexport type CatalogOnlyPolicyOverride = {\n  /** `true` \u2192 the item is explicitly opted into stock tracking with no data source behind it (\u00A74.3, out_of_stock). */\n  isStockManaged?: boolean\n  /** `false` \u2192 the policy row is inactive; treated as out_of_stock. */\n  isActive?: boolean\n  /** ISO-8601. In the future \u2192 `preorder`. */\n  preorderReleaseAt?: string | null\n  /** The `AvailabilityPolicy` row id that produced this override. */\n  policySourceId?: string | null\n}\n\n/**\n * Optional soft lookup into `AvailabilityPolicy` when the `availability`\n * module is installed. Keyed by `availabilityItemKey()`. Returning `null` or\n * omitting an item from the map means \"no policy row \u2014 module default\".\n */\nexport type CatalogOnlyPolicyLookup = (\n  query: AvailabilityQuery,\n) => Promise<Record<string, CatalogOnlyPolicyOverride | null | undefined>>\n\nlet policyLookup: CatalogOnlyPolicyLookup | null = null\n\n/**\n * Wired by the `availability` module's `di.ts` at container-build time\n * (closure captures the container, mirroring `wms/di.ts`'s own provider\n * registration) \u2014 never a static import from `packages/shared`. Pass `null`\n * to clear (test isolation).\n */\nexport function setCatalogOnlyPolicyLookup(lookup: CatalogOnlyPolicyLookup | null): void {\n  policyLookup = lookup\n}\n\nfunction pureFallbackItem(): AvailabilityItemResult {\n  return {\n    state: 'not_tracked',\n    availableQuantity: null,\n    canFulfil: true,\n    leadTimeDays: null,\n    releaseAt: null,\n    isAuthoritative: true,\n    policySourceId: null,\n  }\n}\n\n/**\n * Applies decision 7's matrix (see PLAN.md \u00A7 Key design decisions) for a\n * resolved policy override on top of the pure fallback.\n */\nfunction applyOverride(override: CatalogOnlyPolicyOverride | null | undefined): AvailabilityItemResult {\n  const base = pureFallbackItem()\n  if (!override) return base\n\n  const policySourceId = override.policySourceId ?? null\n\n  if (override.preorderReleaseAt) {\n    const releaseAt = new Date(override.preorderReleaseAt)\n    if (!Number.isNaN(releaseAt.getTime()) && releaseAt.getTime() > Date.now()) {\n      return {\n        ...base,\n        state: 'preorder',\n        canFulfil: true,\n        releaseAt: override.preorderReleaseAt,\n        policySourceId,\n      }\n    }\n  }\n\n  if (override.isActive === false) {\n    return { ...base, state: 'out_of_stock', canFulfil: false, policySourceId }\n  }\n\n  if (override.isStockManaged === true) {\n    // Opted into stock tracking with no data source to verify against \u2014 see\n    // decision 7: this is the \"policy explicitly marks the item unavailable\"\n    // case rather than a silent \"in stock\" claim (R5).\n    return { ...base, state: 'out_of_stock', canFulfil: false, policySourceId }\n  }\n\n  return { ...base, policySourceId }\n}\n\nasync function getAvailability(query: AvailabilityQuery): Promise<AvailabilityResult> {\n  const byItem: AvailabilityResult['byItem'] = {}\n\n  let overrides: Record<string, CatalogOnlyPolicyOverride | null | undefined> = {}\n  if (policyLookup) {\n    try {\n      overrides = await policyLookup(query)\n    } catch {\n      // Degrade gracefully to the pure fallback \u2014 never let an optional\n      // policy lookup failure break the always-available fallback provider.\n      overrides = {}\n    }\n  }\n\n  for (const item of query.items) {\n    const key = availabilityItemKey(item)\n    byItem[key] = applyOverride(overrides[key])\n  }\n\n  return { byItem }\n}\n\navailabilityProviderRegistry.register({\n  id: AVAILABILITY_CATALOG_ONLY_PROVIDER_ID,\n  getAvailability,\n})\n"],
-  "mappings": "AAOA,SAAS,2BAA2B;AAEpC,SAAS,8BAA8B,6CAA6C;AAuBpF,IAAI,eAA+C;AAQ5C,SAAS,2BAA2B,QAA8C;AACvF,iBAAe;AACjB;AAEA,SAAS,mBAA2C;AAClD,SAAO;AAAA,IACL,OAAO;AAAA,IACP,mBAAmB;AAAA,IACnB,WAAW;AAAA,IACX,cAAc;AAAA,IACd,WAAW;AAAA,IACX,iBAAiB;AAAA,IACjB,gBAAgB;AAAA,EAClB;AACF;AAMA,SAAS,cAAc,UAAgF;AACrG,QAAM,OAAO,iBAAiB;AAC9B,MAAI,CAAC,SAAU,QAAO;AAEtB,QAAM,iBAAiB,SAAS,kBAAkB;AAElD,MAAI,SAAS,mBAAmB;AAC9B,UAAM,YAAY,IAAI,KAAK,SAAS,iBAAiB;AACrD,QAAI,CAAC,OAAO,MAAM,UAAU,QAAQ,CAAC,KAAK,UAAU,QAAQ,IAAI,KAAK,IAAI,GAAG;AAC1E,aAAO;AAAA,QACL,GAAG;AAAA,QACH,OAAO;AAAA,QACP,WAAW;AAAA,QACX,WAAW,SAAS;AAAA,QACpB;AAAA,MACF;AAAA,IACF;AAAA,EACF;AAEA,MAAI,SAAS,aAAa,OAAO;AAC/B,WAAO,EAAE,GAAG,MAAM,OAAO,gBAAgB,WAAW,OAAO,eAAe;AAAA,EAC5E;AAEA,MAAI,SAAS,mBAAmB,MAAM;AAIpC,WAAO,EAAE,GAAG,MAAM,OAAO,gBAAgB,WAAW,OAAO,eAAe;AAAA,EAC5E;AAEA,SAAO,EAAE,GAAG,MAAM,eAAe;AACnC;AAEA,eAAe,gBAAgB,OAAuD;AACpF,QAAM,SAAuC,CAAC;AAE9C,MAAI,YAA0E,CAAC;AAC/E,MAAI,cAAc;AAChB,QAAI;AACF,kBAAY,MAAM,aAAa,KAAK;AAAA,IACtC,QAAQ;AAGN,kBAAY,CAAC;AAAA,IACf;AAAA,EACF;AAEA,aAAW,QAAQ,MAAM,OAAO;AAC9B,UAAM,MAAM,oBAAoB,IAAI;AACpC,WAAO,GAAG,IAAI,cAAc,UAAU,GAAG,CAAC;AAAA,EAC5C;AAEA,SAAO,EAAE,OAAO;AAClB;AAEA,6BAA6B,SAAS;AAAA,EACpC,IAAI;AAAA,EACJ;AACF,CAAC;",
-  "names": []
-}

package/dist/lib/availability/index.js

@@ -1,8 +0,0 @@
-export * from "./types.js";
-export * from "./registry.js";
-import { setCatalogOnlyPolicyLookup } from "./catalogOnlyProvider.js";
-import "./catalogOnlyProvider.js";
-export {
-  setCatalogOnlyPolicyLookup
-};
-//# sourceMappingURL=index.js.map

package/dist/lib/availability/index.js.map

@@ -1,7 +0,0 @@
-{
-  "version": 3,
-  "sources": ["../../../src/lib/availability/index.ts"],
-  "sourcesContent": ["/**\n * Public entrypoint for the Availability Contract's shared, dependency-free\n * base \u2014 types, the provider registry, `resolveAvailability()`, and the\n * built-in `catalog-only` fallback.\n *\n * Importing from this barrel (rather than `./registry` directly) guarantees\n * the `catalog-only` provider is registered \u2014 it self-registers as an import\n * side effect in `./catalogOnlyProvider`, which this file always pulls in.\n *\n * @see .ai/specs/2026-08-14-availability-contract.md \u00A74.1a\n */\n\nexport * from './types'\nexport * from './registry'\nexport { setCatalogOnlyPolicyLookup } from './catalogOnlyProvider'\nexport type { CatalogOnlyPolicyLookup, CatalogOnlyPolicyOverride } from './catalogOnlyProvider'\n\nimport './catalogOnlyProvider'\n"],
-  "mappings": "AAYA,cAAc;AACd,cAAc;AACd,SAAS,kCAAkC;AAG3C,OAAO;",
-  "names": []
-}

package/dist/lib/availability/registry.js

@@ -1,47 +0,0 @@
-const AVAILABILITY_CATALOG_ONLY_PROVIDER_ID = "catalog-only";
-class AvailabilityProviderRegistryImpl {
-  constructor() {
-    // Preserves registration order via Map iteration semantics.
-    this.providers = /* @__PURE__ */ new Map();
-  }
-  register(provider) {
-    if (!provider || typeof provider.id !== "string" || provider.id.length === 0) {
-      throw new Error("[internal] AvailabilityProviderRegistry: provider must have a non-empty id");
-    }
-    this.providers.set(provider.id, provider);
-  }
-  get(id) {
-    return this.providers.get(id) ?? null;
-  }
-  list() {
-    return Array.from(this.providers.values());
-  }
-  reset() {
-    this.providers.clear();
-  }
-}
-const availabilityProviderRegistry = new AvailabilityProviderRegistryImpl();
-function resolveAutoProvider() {
-  for (const provider of availabilityProviderRegistry.list()) {
-    if (provider.id !== AVAILABILITY_CATALOG_ONLY_PROVIDER_ID) return provider;
-  }
-  return availabilityProviderRegistry.get(AVAILABILITY_CATALOG_ONLY_PROVIDER_ID);
-}
-async function resolveAvailability(query, options) {
-  const selection = options?.moduleConfig ? await options.moduleConfig.getValue("availability", "selectedProvider", {
-    defaultValue: "auto",
-    scope: { tenantId: query.tenantId }
-  }) : "auto";
-  const provider = !selection || selection === "auto" ? resolveAutoProvider() : availabilityProviderRegistry.get(selection) ?? availabilityProviderRegistry.get(AVAILABILITY_CATALOG_ONLY_PROVIDER_ID);
-  const resolved = provider ?? availabilityProviderRegistry.get(AVAILABILITY_CATALOG_ONLY_PROVIDER_ID);
-  if (!resolved) {
-    throw new Error("[internal] No availability provider registered, including the built-in catalog-only fallback");
-  }
-  return resolved.getAvailability(query);
-}
-export {
-  AVAILABILITY_CATALOG_ONLY_PROVIDER_ID,
-  availabilityProviderRegistry,
-  resolveAvailability
-};
-//# sourceMappingURL=registry.js.map

package/dist/lib/availability/registry.js.map

@@ -1,7 +0,0 @@
-{
-  "version": 3,
-  "sources": ["../../../src/lib/availability/registry.ts"],
-  "sourcesContent": ["/**\n * Availability provider registry \u2014 module-level singleton that collects\n * registered providers and dispatches `resolveAvailability()` to the\n * per-tenant selected one, falling back safely to the built-in\n * `catalog-only` provider.\n *\n * Mirrors `packages/shared/src/lib/ai/llm-provider-registry.ts`.\n *\n * @see ./types\n * @see .ai/specs/2026-08-14-availability-contract.md \u00A74.1a\n */\n\nimport type { AvailabilityProvider, AvailabilityQuery, AvailabilityResult } from './types'\n\nexport const AVAILABILITY_CATALOG_ONLY_PROVIDER_ID = 'catalog-only'\n\n/** Public interface of the registry. Exposed as a singleton via {@link availabilityProviderRegistry}. */\nexport interface AvailabilityProviderRegistry {\n  /**\n   * Registers or replaces a provider. Registration is idempotent \u2014 calling\n   * with the same id replaces the existing entry. Never order-dependent.\n   */\n  register(provider: AvailabilityProvider): void\n\n  /** Returns the provider with the given id, or null when not registered. */\n  get(id: string): AvailabilityProvider | null\n\n  /** Returns all registered providers in registration order. */\n  list(): readonly AvailabilityProvider[]\n\n  /** Removes all registered providers. Intended for test isolation. */\n  reset(): void\n}\n\nclass AvailabilityProviderRegistryImpl implements AvailabilityProviderRegistry {\n  // Preserves registration order via Map iteration semantics.\n  private readonly providers = new Map<string, AvailabilityProvider>()\n\n  register(provider: AvailabilityProvider): void {\n    if (!provider || typeof provider.id !== 'string' || provider.id.length === 0) {\n      throw new Error('[internal] AvailabilityProviderRegistry: provider must have a non-empty id')\n    }\n    // Idempotent: replace existing by id.\n    this.providers.set(provider.id, provider)\n  }\n\n  get(id: string): AvailabilityProvider | null {\n    return this.providers.get(id) ?? null\n  }\n\n  list(): readonly AvailabilityProvider[] {\n    return Array.from(this.providers.values())\n  }\n\n  reset(): void {\n    this.providers.clear()\n  }\n}\n\n/** Process-level singleton instance of the registry. */\nexport const availabilityProviderRegistry: AvailabilityProviderRegistry = new AvailabilityProviderRegistryImpl()\n\nexport type AvailabilityProviderSelection = 'auto' | 'catalog-only' | (string & {})\n\n/**\n * Narrow port for per-tenant provider selection \u2014 declared locally so this\n * package stays dependency-free. A caller with DI access (an `availability`\n * module route, a future `ecommerce`/`cart`/`checkout` consumer) passes in\n * its resolved `ModuleConfigService` instance; omitting it always resolves\n * `'auto'`.\n */\nexport interface AvailabilityModuleConfigReader {\n  getValue<T = unknown>(\n    moduleId: string,\n    name: string,\n    options?: { defaultValue?: T | null; scope?: { tenantId?: string | null; organizationId?: string | null } },\n  ): Promise<T | null>\n}\n\nexport interface ResolveAvailabilityOptions {\n  /** `ModuleConfigService('availability', 'selectedProvider')` reader. See {@link AvailabilityModuleConfigReader}. */\n  moduleConfig?: AvailabilityModuleConfigReader\n}\n\nfunction resolveAutoProvider(): AvailabilityProvider | null {\n  // 'auto' = \"the highest-precedence registered provider\" \u2014 the first\n  // non-catalog-only registrant, in registration order.\n  for (const provider of availabilityProviderRegistry.list()) {\n    if (provider.id !== AVAILABILITY_CATALOG_ONLY_PROVIDER_ID) return provider\n  }\n  return availabilityProviderRegistry.get(AVAILABILITY_CATALOG_ONLY_PROVIDER_ID)\n}\n\n/**\n * The entry point every read-side consumer calls. Advisory only \u2014 see \u00A74.1:\n * `resolveAvailability()` is never a stock guarantee, `reserveAvailability()`\n * (the `availability` module, not shipped by this contract) is.\n */\nexport async function resolveAvailability(\n  query: AvailabilityQuery,\n  options?: ResolveAvailabilityOptions,\n): Promise<AvailabilityResult> {\n  const selection = options?.moduleConfig\n    ? await options.moduleConfig.getValue<AvailabilityProviderSelection>('availability', 'selectedProvider', {\n        defaultValue: 'auto',\n        scope: { tenantId: query.tenantId },\n      })\n    : 'auto'\n\n  const provider =\n    !selection || selection === 'auto'\n      ? resolveAutoProvider()\n      : availabilityProviderRegistry.get(selection) ?? availabilityProviderRegistry.get(AVAILABILITY_CATALOG_ONLY_PROVIDER_ID)\n\n  const resolved = provider ?? availabilityProviderRegistry.get(AVAILABILITY_CATALOG_ONLY_PROVIDER_ID)\n  if (!resolved) {\n    throw new Error('[internal] No availability provider registered, including the built-in catalog-only fallback')\n  }\n  return resolved.getAvailability(query)\n}\n"],
-  "mappings": "AAcO,MAAM,wCAAwC;AAoBrD,MAAM,iCAAyE;AAAA,EAA/E;AAEE;AAAA,SAAiB,YAAY,oBAAI,IAAkC;AAAA;AAAA,EAEnE,SAAS,UAAsC;AAC7C,QAAI,CAAC,YAAY,OAAO,SAAS,OAAO,YAAY,SAAS,GAAG,WAAW,GAAG;AAC5E,YAAM,IAAI,MAAM,4EAA4E;AAAA,IAC9F;AAEA,SAAK,UAAU,IAAI,SAAS,IAAI,QAAQ;AAAA,EAC1C;AAAA,EAEA,IAAI,IAAyC;AAC3C,WAAO,KAAK,UAAU,IAAI,EAAE,KAAK;AAAA,EACnC;AAAA,EAEA,OAAwC;AACtC,WAAO,MAAM,KAAK,KAAK,UAAU,OAAO,CAAC;AAAA,EAC3C;AAAA,EAEA,QAAc;AACZ,SAAK,UAAU,MAAM;AAAA,EACvB;AACF;AAGO,MAAM,+BAA6D,IAAI,iCAAiC;AAwB/G,SAAS,sBAAmD;AAG1D,aAAW,YAAY,6BAA6B,KAAK,GAAG;AAC1D,QAAI,SAAS,OAAO,sCAAuC,QAAO;AAAA,EACpE;AACA,SAAO,6BAA6B,IAAI,qCAAqC;AAC/E;AAOA,eAAsB,oBACpB,OACA,SAC6B;AAC7B,QAAM,YAAY,SAAS,eACvB,MAAM,QAAQ,aAAa,SAAwC,gBAAgB,oBAAoB;AAAA,IACrG,cAAc;AAAA,IACd,OAAO,EAAE,UAAU,MAAM,SAAS;AAAA,EACpC,CAAC,IACD;AAEJ,QAAM,WACJ,CAAC,aAAa,cAAc,SACxB,oBAAoB,IACpB,6BAA6B,IAAI,SAAS,KAAK,6BAA6B,IAAI,qCAAqC;AAE3H,QAAM,WAAW,YAAY,6BAA6B,IAAI,qCAAqC;AACnG,MAAI,CAAC,UAAU;AACb,UAAM,IAAI,MAAM,8FAA8F;AAAA,EAChH;AACA,SAAO,SAAS,gBAAgB,KAAK;AACvC;",
-  "names": []
-}

package/dist/lib/availability/types.js

@@ -1,7 +0,0 @@
-function availabilityItemKey(item) {
-  return `${item.catalogProductId}:${item.catalogVariantId ?? ""}`;
-}
-export {
-  availabilityItemKey
-};
-//# sourceMappingURL=types.js.map

package/dist/lib/availability/types.js.map

@@ -1,7 +0,0 @@
-{
-  "version": 3,
-  "sources": ["../../../src/lib/availability/types.ts"],
-  "sourcesContent": ["/**\n * Availability Contract \u2014 base types.\n *\n * Zero module dependencies, so `ecommerce`, `cart`, `checkout` and `catalog`\n * can consume this without a `requires` edge on either `availability` or `wms`.\n *\n * @see .ai/specs/2026-08-14-availability-contract.md \u00A74.1a\n */\n\nexport type AvailabilityState =\n  | 'in_stock'\n  | 'low_stock'\n  | 'out_of_stock'\n  | 'backorder'\n  | 'preorder'\n  | 'not_tracked'\n\nexport type AvailabilityItemQuery = {\n  catalogProductId: string\n  /** `null` or omitted \u2192 product-level rollup over active variants. */\n  catalogVariantId?: string | null\n  /** The quantity being asked about; state is relative to it. */\n  quantity: number\n}\n\nexport type AvailabilityQuery = {\n  tenantId: string\n  organizationId: string\n  items: AvailabilityItemQuery[]\n  /** Selects the policy chain. */\n  storeId?: string | null\n  channelId?: string | null\n  /** `null`/omitted \u2192 every in-scope location. */\n  locationIds?: string[] | null\n  /**\n   * Additive, optional. When true, a provider MUST skip any internal read\n   * cache and compute a live result \u2014 the \u00A76 \"cart re-validation\" row.\n   */\n  bypassCache?: boolean\n}\n\nexport type AvailabilityItemResult = {\n  state: AvailabilityState\n  /** Sellable quantity; `null` when not tracked. */\n  availableQuantity: number | null\n  /** Whether the requested quantity can be met, including a backorder/preorder path. */\n  canFulfil: boolean\n  /** Set for `'backorder'`. */\n  leadTimeDays: number | null\n  /** ISO-8601; set for `'preorder'`. */\n  releaseAt: string | null\n  /** `false` for a cached browse-time read \u2014 never a guarantee. */\n  isAuthoritative: boolean\n  /** The `AvailabilityPolicy` row that decided, or `null` for a module default. */\n  policySourceId: string | null\n}\n\nexport type AvailabilityResult = {\n  /** Key: `${catalogProductId}:${catalogVariantId ?? ''}` \u2014 stable and caller-derivable. */\n  byItem: Record<string, AvailabilityItemResult>\n}\n\nexport interface AvailabilityProvider {\n  id: string\n  getAvailability(query: AvailabilityQuery): Promise<AvailabilityResult>\n}\n\n/** Builds the stable `AvailabilityResult.byItem` key for an item. */\nexport function availabilityItemKey(item: { catalogProductId: string; catalogVariantId?: string | null }): string {\n  return `${item.catalogProductId}:${item.catalogVariantId ?? ''}`\n}\n"],
-  "mappings": "AAoEO,SAAS,oBAAoB,MAA8E;AAChH,SAAO,GAAG,KAAK,gBAAgB,IAAI,KAAK,oBAAoB,EAAE;AAChE;",
-  "names": []
-}

package/src/lib/availability/__tests__/catalogOnlyProvider.test.ts

@@ -1,98 +0,0 @@
-import '../catalogOnlyProvider'
-import { setCatalogOnlyPolicyLookup } from '../catalogOnlyProvider'
-import { availabilityProviderRegistry, resolveAvailability, AVAILABILITY_CATALOG_ONLY_PROVIDER_ID } from '../registry'
-import type { AvailabilityQuery } from '../types'
-
-function makeQuery(overrides: Partial<AvailabilityQuery> = {}): AvailabilityQuery {
-  return {
-    tenantId: 'tenant-1',
-    organizationId: 'org-1',
-    items: [{ catalogProductId: 'product-1', catalogVariantId: 'variant-1', quantity: 1 }],
-    ...overrides,
-  }
-}
-
-describe('catalog-only fallback provider', () => {
-  beforeEach(() => {
-    setCatalogOnlyPolicyLookup(null)
-  })
-
-  afterAll(() => {
-    setCatalogOnlyPolicyLookup(null)
-  })
-
-  it('is always registered under the catalog-only id', () => {
-    expect(availabilityProviderRegistry.get(AVAILABILITY_CATALOG_ONLY_PROVIDER_ID)).not.toBeNull()
-  })
-
-  it('returns not_tracked with canFulfil true and isAuthoritative true for every item with no policy hook (R5)', async () => {
-    const provider = availabilityProviderRegistry.get(AVAILABILITY_CATALOG_ONLY_PROVIDER_ID)!
-    const result = await provider.getAvailability(makeQuery())
-    const item = result.byItem['product-1:variant-1']
-    expect(item.state).toBe('not_tracked')
-    expect(item.canFulfil).toBe(true)
-    expect(item.isAuthoritative).toBe(true)
-    expect(item.availableQuantity).toBeNull()
-    // not_tracked must never collapse into in_stock for a naive consumer.
-    expect(item.state).not.toBe('in_stock')
-  })
-
-  it('reflects a future preorderReleaseAt from the policy hook as preorder', async () => {
-    const future = new Date(Date.now() + 86_400_000).toISOString()
-    setCatalogOnlyPolicyLookup(async () => ({
-      'product-1:variant-1': { preorderReleaseAt: future, policySourceId: 'policy-1' },
-    }))
-    const provider = availabilityProviderRegistry.get(AVAILABILITY_CATALOG_ONLY_PROVIDER_ID)!
-    const result = await provider.getAvailability(makeQuery())
-    const item = result.byItem['product-1:variant-1']
-    expect(item.state).toBe('preorder')
-    expect(item.releaseAt).toBe(future)
-    expect(item.policySourceId).toBe('policy-1')
-  })
-
-  it('treats a past preorderReleaseAt as no longer preorder', async () => {
-    const past = new Date(Date.now() - 86_400_000).toISOString()
-    setCatalogOnlyPolicyLookup(async () => ({
-      'product-1:variant-1': { preorderReleaseAt: past, policySourceId: 'policy-1' },
-    }))
-    const provider = availabilityProviderRegistry.get(AVAILABILITY_CATALOG_ONLY_PROVIDER_ID)!
-    const result = await provider.getAvailability(makeQuery())
-    expect(result.byItem['product-1:variant-1'].state).not.toBe('preorder')
-  })
-
-  it('treats an inactive policy row as out_of_stock', async () => {
-    setCatalogOnlyPolicyLookup(async () => ({
-      'product-1:variant-1': { isActive: false, policySourceId: 'policy-2' },
-    }))
-    const provider = availabilityProviderRegistry.get(AVAILABILITY_CATALOG_ONLY_PROVIDER_ID)!
-    const result = await provider.getAvailability(makeQuery())
-    const item = result.byItem['product-1:variant-1']
-    expect(item.state).toBe('out_of_stock')
-    expect(item.canFulfil).toBe(false)
-  })
-
-  it('treats is_stock_managed true (no real data source) as out_of_stock rather than in_stock', async () => {
-    setCatalogOnlyPolicyLookup(async () => ({
-      'product-1:variant-1': { isStockManaged: true, policySourceId: 'policy-3' },
-    }))
-    const provider = availabilityProviderRegistry.get(AVAILABILITY_CATALOG_ONLY_PROVIDER_ID)!
-    const result = await provider.getAvailability(makeQuery())
-    const item = result.byItem['product-1:variant-1']
-    expect(item.state).toBe('out_of_stock')
-    expect(item.canFulfil).toBe(false)
-  })
-
-  it('degrades to the pure fallback when the policy hook throws', async () => {
-    setCatalogOnlyPolicyLookup(async () => {
-      throw new Error('boom')
-    })
-    const provider = availabilityProviderRegistry.get(AVAILABILITY_CATALOG_ONLY_PROVIDER_ID)!
-    const result = await provider.getAvailability(makeQuery())
-    expect(result.byItem['product-1:variant-1'].state).toBe('not_tracked')
-  })
-
-  it('is reachable end-to-end via resolveAvailability', async () => {
-    const result = await resolveAvailability(makeQuery())
-    expect(result.byItem['product-1:variant-1'].state).toBe('not_tracked')
-  })
-})

package/src/lib/availability/__tests__/registry.test.ts

@@ -1,115 +0,0 @@
-import { availabilityProviderRegistry, resolveAvailability, AVAILABILITY_CATALOG_ONLY_PROVIDER_ID } from '../registry'
-import type { AvailabilityModuleConfigReader } from '../registry'
-import type { AvailabilityProvider, AvailabilityQuery, AvailabilityResult } from '../types'
-
-function makeProvider(id: string, result: Partial<AvailabilityResult['byItem'][string]> = {}): AvailabilityProvider {
-  return {
-    id,
-    async getAvailability(query: AvailabilityQuery): Promise<AvailabilityResult> {
-      const byItem: AvailabilityResult['byItem'] = {}
-      for (const item of query.items) {
-        const key = `${item.catalogProductId}:${item.catalogVariantId ?? ''}`
-        byItem[key] = {
-          state: 'in_stock',
-          availableQuantity: 100,
-          canFulfil: true,
-          leadTimeDays: null,
-          releaseAt: null,
-          isAuthoritative: true,
-          policySourceId: null,
-          ...result,
-        }
-      }
-      return { byItem }
-    },
-  }
-}
-
-function makeQuery(overrides: Partial<AvailabilityQuery> = {}): AvailabilityQuery {
-  return {
-    tenantId: 'tenant-1',
-    organizationId: 'org-1',
-    items: [{ catalogProductId: 'product-1', catalogVariantId: 'variant-1', quantity: 1 }],
-    ...overrides,
-  }
-}
-
-describe('availabilityProviderRegistry', () => {
-  beforeEach(() => {
-    availabilityProviderRegistry.reset()
-  })
-
-  it('registers and retrieves providers by id', () => {
-    const provider = makeProvider('alpha')
-    availabilityProviderRegistry.register(provider)
-    expect(availabilityProviderRegistry.get('alpha')).toBe(provider)
-    expect(availabilityProviderRegistry.get('missing')).toBeNull()
-  })
-
-  it('is idempotent — replaces by id rather than duplicating', () => {
-    const first = makeProvider('alpha')
-    const second = makeProvider('alpha')
-    availabilityProviderRegistry.register(first)
-    availabilityProviderRegistry.register(second)
-    expect(availabilityProviderRegistry.list()).toHaveLength(1)
-    expect(availabilityProviderRegistry.get('alpha')).toBe(second)
-  })
-
-  it('lists providers in registration order', () => {
-    availabilityProviderRegistry.register(makeProvider('first'))
-    availabilityProviderRegistry.register(makeProvider('second'))
-    expect(availabilityProviderRegistry.list().map((p) => p.id)).toEqual(['first', 'second'])
-  })
-
-  it('rejects a provider with an empty id', () => {
-    expect(() => availabilityProviderRegistry.register({ id: '', getAvailability: async () => ({ byItem: {} }) })).toThrow()
-  })
-})
-
-describe('resolveAvailability', () => {
-  beforeEach(() => {
-    availabilityProviderRegistry.reset()
-  })
-
-  it('falls back to catalog-only when nothing else is registered and selection is auto', async () => {
-    availabilityProviderRegistry.register(makeProvider(AVAILABILITY_CATALOG_ONLY_PROVIDER_ID, { state: 'not_tracked', availableQuantity: null }))
-    const result = await resolveAvailability(makeQuery())
-    expect(result.byItem['product-1:variant-1'].state).toBe('not_tracked')
-  })
-
-  it("'auto' picks the highest-precedence non-catalog-only registrant", async () => {
-    availabilityProviderRegistry.register(makeProvider(AVAILABILITY_CATALOG_ONLY_PROVIDER_ID, { state: 'not_tracked' }))
-    availabilityProviderRegistry.register(makeProvider('wms', { state: 'in_stock' }))
-    const result = await resolveAvailability(makeQuery())
-    expect(result.byItem['product-1:variant-1'].state).toBe('in_stock')
-  })
-
-  it('honors an explicit selection via the injected module-config reader', async () => {
-    availabilityProviderRegistry.register(makeProvider(AVAILABILITY_CATALOG_ONLY_PROVIDER_ID, { state: 'not_tracked' }))
-    availabilityProviderRegistry.register(makeProvider('wms', { state: 'in_stock' }))
-    const moduleConfig: AvailabilityModuleConfigReader = {
-      getValue: async () => 'catalog-only',
-    }
-    const result = await resolveAvailability(makeQuery(), { moduleConfig })
-    expect(result.byItem['product-1:variant-1'].state).toBe('not_tracked')
-  })
-
-  it('falls back to catalog-only when the selected id is not currently registered', async () => {
-    availabilityProviderRegistry.register(makeProvider(AVAILABILITY_CATALOG_ONLY_PROVIDER_ID, { state: 'not_tracked' }))
-    const moduleConfig: AvailabilityModuleConfigReader = {
-      getValue: async () => 'some-unregistered-provider',
-    }
-    const result = await resolveAvailability(makeQuery(), { moduleConfig })
-    expect(result.byItem['product-1:variant-1'].state).toBe('not_tracked')
-  })
-
-  it('defaults to auto when the module-config reader is omitted', async () => {
-    availabilityProviderRegistry.register(makeProvider('wms', { state: 'in_stock' }))
-    const result = await resolveAvailability(makeQuery())
-    expect(result.byItem['product-1:variant-1'].state).toBe('in_stock')
-  })
-
-  it('throws when no provider is registered at all', async () => {
-    await expect(resolveAvailability(makeQuery())).rejects.toThrow()
-  })
-})

package/src/lib/availability/catalogOnlyProvider.ts

@@ -1,119 +0,0 @@
-/**
- * The built-in `catalog-only` fallback provider. Always registered so a
- * `wms`-less *and* `availability`-less storefront stays fully functional.
- *
- * @see .ai/specs/2026-08-14-availability-contract.md §4.3
- */
-
-import { availabilityItemKey } from './types'
-import type { AvailabilityItemResult, AvailabilityQuery, AvailabilityResult } from './types'
-import { availabilityProviderRegistry, AVAILABILITY_CATALOG_ONLY_PROVIDER_ID } from './registry'
-
-/** Per-item policy signal the optional lookup hook may report. */
-export type CatalogOnlyPolicyOverride = {
-  /** `true` → the item is explicitly opted into stock tracking with no data source behind it (§4.3, out_of_stock). */
-  isStockManaged?: boolean
-  /** `false` → the policy row is inactive; treated as out_of_stock. */
-  isActive?: boolean
-  /** ISO-8601. In the future → `preorder`. */
-  preorderReleaseAt?: string | null
-  /** The `AvailabilityPolicy` row id that produced this override. */
-  policySourceId?: string | null
-}
-
-/**
- * Optional soft lookup into `AvailabilityPolicy` when the `availability`
- * module is installed. Keyed by `availabilityItemKey()`. Returning `null` or
- * omitting an item from the map means "no policy row — module default".
- */
-export type CatalogOnlyPolicyLookup = (
-  query: AvailabilityQuery,
-) => Promise<Record<string, CatalogOnlyPolicyOverride | null | undefined>>
-
-let policyLookup: CatalogOnlyPolicyLookup | null = null
-
-/**
- * Wired by the `availability` module's `di.ts` at container-build time
- * (closure captures the container, mirroring `wms/di.ts`'s own provider
- * registration) — never a static import from `packages/shared`. Pass `null`
- * to clear (test isolation).
- */
-export function setCatalogOnlyPolicyLookup(lookup: CatalogOnlyPolicyLookup | null): void {
-  policyLookup = lookup
-}
-
-function pureFallbackItem(): AvailabilityItemResult {
-  return {
-    state: 'not_tracked',
-    availableQuantity: null,
-    canFulfil: true,
-    leadTimeDays: null,
-    releaseAt: null,
-    isAuthoritative: true,
-    policySourceId: null,
-  }
-}
-
-/**
- * Applies decision 7's matrix (see PLAN.md § Key design decisions) for a
- * resolved policy override on top of the pure fallback.
- */
-function applyOverride(override: CatalogOnlyPolicyOverride | null | undefined): AvailabilityItemResult {
-  const base = pureFallbackItem()
-  if (!override) return base
-
-  const policySourceId = override.policySourceId ?? null
-
-  if (override.preorderReleaseAt) {
-    const releaseAt = new Date(override.preorderReleaseAt)
-    if (!Number.isNaN(releaseAt.getTime()) && releaseAt.getTime() > Date.now()) {
-      return {
-        ...base,
-        state: 'preorder',
-        canFulfil: true,
-        releaseAt: override.preorderReleaseAt,
-        policySourceId,
-      }
-    }
-  }
-
-  if (override.isActive === false) {
-    return { ...base, state: 'out_of_stock', canFulfil: false, policySourceId }
-  }
-
-  if (override.isStockManaged === true) {
-    // Opted into stock tracking with no data source to verify against — see
-    // decision 7: this is the "policy explicitly marks the item unavailable"
-    // case rather than a silent "in stock" claim (R5).
-    return { ...base, state: 'out_of_stock', canFulfil: false, policySourceId }
-  }
-
-  return { ...base, policySourceId }
-}
-
-async function getAvailability(query: AvailabilityQuery): Promise<AvailabilityResult> {
-  const byItem: AvailabilityResult['byItem'] = {}
-
-  let overrides: Record<string, CatalogOnlyPolicyOverride | null | undefined> = {}
-  if (policyLookup) {
-    try {
-      overrides = await policyLookup(query)
-    } catch {
-      // Degrade gracefully to the pure fallback — never let an optional
-      // policy lookup failure break the always-available fallback provider.
-      overrides = {}
-    }
-  }
-
-  for (const item of query.items) {
-    const key = availabilityItemKey(item)
-    byItem[key] = applyOverride(overrides[key])
-  }
-
-  return { byItem }
-}
-
-availabilityProviderRegistry.register({
-  id: AVAILABILITY_CATALOG_ONLY_PROVIDER_ID,
-  getAvailability,
-})

package/src/lib/availability/index.ts

@@ -1,18 +0,0 @@
-/**
- * Public entrypoint for the Availability Contract's shared, dependency-free
- * base — types, the provider registry, `resolveAvailability()`, and the
- * built-in `catalog-only` fallback.
- *
- * Importing from this barrel (rather than `./registry` directly) guarantees
- * the `catalog-only` provider is registered — it self-registers as an import
- * side effect in `./catalogOnlyProvider`, which this file always pulls in.
- *
- * @see .ai/specs/2026-08-14-availability-contract.md §4.1a
- */
-
-export * from './types'
-export * from './registry'
-export { setCatalogOnlyPolicyLookup } from './catalogOnlyProvider'
-export type { CatalogOnlyPolicyLookup, CatalogOnlyPolicyOverride } from './catalogOnlyProvider'
-
-import './catalogOnlyProvider'

package/src/lib/availability/registry.ts

@@ -1,120 +0,0 @@
-/**
- * Availability provider registry — module-level singleton that collects
- * registered providers and dispatches `resolveAvailability()` to the
- * per-tenant selected one, falling back safely to the built-in
- * `catalog-only` provider.
- *
- * Mirrors `packages/shared/src/lib/ai/llm-provider-registry.ts`.
- *
- * @see ./types
- * @see .ai/specs/2026-08-14-availability-contract.md §4.1a
- */
-
-import type { AvailabilityProvider, AvailabilityQuery, AvailabilityResult } from './types'
-
-export const AVAILABILITY_CATALOG_ONLY_PROVIDER_ID = 'catalog-only'
-
-/** Public interface of the registry. Exposed as a singleton via {@link availabilityProviderRegistry}. */
-export interface AvailabilityProviderRegistry {
-  /**
-   * Registers or replaces a provider. Registration is idempotent — calling
-   * with the same id replaces the existing entry. Never order-dependent.
-   */
-  register(provider: AvailabilityProvider): void
-
-  /** Returns the provider with the given id, or null when not registered. */
-  get(id: string): AvailabilityProvider | null
-
-  /** Returns all registered providers in registration order. */
-  list(): readonly AvailabilityProvider[]
-
-  /** Removes all registered providers. Intended for test isolation. */
-  reset(): void
-}
-
-class AvailabilityProviderRegistryImpl implements AvailabilityProviderRegistry {
-  // Preserves registration order via Map iteration semantics.
-  private readonly providers = new Map<string, AvailabilityProvider>()
-
-  register(provider: AvailabilityProvider): void {
-    if (!provider || typeof provider.id !== 'string' || provider.id.length === 0) {
-      throw new Error('[internal] AvailabilityProviderRegistry: provider must have a non-empty id')
-    }
-    // Idempotent: replace existing by id.
-    this.providers.set(provider.id, provider)
-  }
-
-  get(id: string): AvailabilityProvider | null {
-    return this.providers.get(id) ?? null
-  }
-
-  list(): readonly AvailabilityProvider[] {
-    return Array.from(this.providers.values())
-  }
-
-  reset(): void {
-    this.providers.clear()
-  }
-}
-
-/** Process-level singleton instance of the registry. */
-export const availabilityProviderRegistry: AvailabilityProviderRegistry = new AvailabilityProviderRegistryImpl()
-
-export type AvailabilityProviderSelection = 'auto' | 'catalog-only' | (string & {})
-
-/**
- * Narrow port for per-tenant provider selection — declared locally so this
- * package stays dependency-free. A caller with DI access (an `availability`
- * module route, a future `ecommerce`/`cart`/`checkout` consumer) passes in
- * its resolved `ModuleConfigService` instance; omitting it always resolves
- * `'auto'`.
- */
-export interface AvailabilityModuleConfigReader {
-  getValue<T = unknown>(
-    moduleId: string,
-    name: string,
-    options?: { defaultValue?: T | null; scope?: { tenantId?: string | null; organizationId?: string | null } },
-  ): Promise<T | null>
-}
-
-export interface ResolveAvailabilityOptions {
-  /** `ModuleConfigService('availability', 'selectedProvider')` reader. See {@link AvailabilityModuleConfigReader}. */
-  moduleConfig?: AvailabilityModuleConfigReader
-}
-
-function resolveAutoProvider(): AvailabilityProvider | null {
-  // 'auto' = "the highest-precedence registered provider" — the first
-  // non-catalog-only registrant, in registration order.
-  for (const provider of availabilityProviderRegistry.list()) {
-    if (provider.id !== AVAILABILITY_CATALOG_ONLY_PROVIDER_ID) return provider
-  }
-  return availabilityProviderRegistry.get(AVAILABILITY_CATALOG_ONLY_PROVIDER_ID)
-}
-
-/**
- * The entry point every read-side consumer calls. Advisory only — see §4.1:
- * `resolveAvailability()` is never a stock guarantee, `reserveAvailability()`
- * (the `availability` module, not shipped by this contract) is.
- */
-export async function resolveAvailability(
-  query: AvailabilityQuery,
-  options?: ResolveAvailabilityOptions,
-): Promise<AvailabilityResult> {
-  const selection = options?.moduleConfig
-    ? await options.moduleConfig.getValue<AvailabilityProviderSelection>('availability', 'selectedProvider', {
-        defaultValue: 'auto',
-        scope: { tenantId: query.tenantId },
-      })
-    : 'auto'
-
-  const provider =
-    !selection || selection === 'auto'
-      ? resolveAutoProvider()
-      : availabilityProviderRegistry.get(selection) ?? availabilityProviderRegistry.get(AVAILABILITY_CATALOG_ONLY_PROVIDER_ID)
-
-  const resolved = provider ?? availabilityProviderRegistry.get(AVAILABILITY_CATALOG_ONLY_PROVIDER_ID)
-  if (!resolved) {
-    throw new Error('[internal] No availability provider registered, including the built-in catalog-only fallback')
-  }
-  return resolved.getAvailability(query)
-}

package/src/lib/availability/types.ts

@@ -1,71 +0,0 @@
-/**
- * Availability Contract — base types.
- *
- * Zero module dependencies, so `ecommerce`, `cart`, `checkout` and `catalog`
- * can consume this without a `requires` edge on either `availability` or `wms`.
- *
- * @see .ai/specs/2026-08-14-availability-contract.md §4.1a
- */
-
-export type AvailabilityState =
-  | 'in_stock'
-  | 'low_stock'
-  | 'out_of_stock'
-  | 'backorder'
-  | 'preorder'
-  | 'not_tracked'
-
-export type AvailabilityItemQuery = {
-  catalogProductId: string
-  /** `null` or omitted → product-level rollup over active variants. */
-  catalogVariantId?: string | null
-  /** The quantity being asked about; state is relative to it. */
-  quantity: number
-}
-
-export type AvailabilityQuery = {
-  tenantId: string
-  organizationId: string
-  items: AvailabilityItemQuery[]
-  /** Selects the policy chain. */
-  storeId?: string | null
-  channelId?: string | null
-  /** `null`/omitted → every in-scope location. */
-  locationIds?: string[] | null
-  /**
-   * Additive, optional. When true, a provider MUST skip any internal read
-   * cache and compute a live result — the §6 "cart re-validation" row.
-   */
-  bypassCache?: boolean
-}
-
-export type AvailabilityItemResult = {
-  state: AvailabilityState
-  /** Sellable quantity; `null` when not tracked. */
-  availableQuantity: number | null
-  /** Whether the requested quantity can be met, including a backorder/preorder path. */
-  canFulfil: boolean
-  /** Set for `'backorder'`. */
-  leadTimeDays: number | null
-  /** ISO-8601; set for `'preorder'`. */
-  releaseAt: string | null
-  /** `false` for a cached browse-time read — never a guarantee. */
-  isAuthoritative: boolean
-  /** The `AvailabilityPolicy` row that decided, or `null` for a module default. */
-  policySourceId: string | null
-}
-
-export type AvailabilityResult = {
-  /** Key: `${catalogProductId}:${catalogVariantId ?? ''}` — stable and caller-derivable. */
-  byItem: Record<string, AvailabilityItemResult>
-}
-
-export interface AvailabilityProvider {
-  id: string
-  getAvailability(query: AvailabilityQuery): Promise<AvailabilityResult>
-}
-
-/** Builds the stable `AvailabilityResult.byItem` key for an item. */
-export function availabilityItemKey(item: { catalogProductId: string; catalogVariantId?: string | null }): string {
-  return `${item.catalogProductId}:${item.catalogVariantId ?? ''}`
-}