@open-mercato/shared 0.8.1-develop.7296.1.2111d779db → 0.9.0

package/src/lib/auth/jwt.ts

@@ -118,6 +118,15 @@ function inspectSecret(secret: string | undefined | null): JwtSecretViolation |
   return null
 }
 
+/**
+ * True when `secret` would be refused by the production signing-secret policy: missing, a
+ * published placeholder, or shorter than the minimum length. Lets tooling that launches the app
+ * (e.g. the ephemeral integration runner) swap in a safe value instead of booting into a crash.
+ */
+export function isUnsafeJwtSecret(secret?: string | null): boolean {
+  return inspectSecret(secret) !== null
+}
+
 function describeViolation(name: string, violation: JwtSecretViolation): string {
   switch (violation) {
     case 'missing':

package/src/lib/auth/organizationScope.ts

@@ -1,3 +1,5 @@
+import { forbidden } from '../crud/errors'
+
 type OrganizationScopedAuth = {
   orgId?: string | null
   actorOrgId?: unknown
@@ -5,6 +7,16 @@ type OrganizationScopedAuth = {
   actorTenantId?: unknown
 } | null | undefined
 
+type FiniteOrganizationScope = {
+  selectedId?: string | null
+  filterIds?: readonly string[] | null
+  allowedIds?: readonly string[] | null
+} | null | undefined
+
+type OrganizationHomeAuth = {
+  orgId?: string | null
+} | null | undefined
+
 function normalizeId(value: unknown): string | null {
   if (typeof value !== 'string') return null
   const trimmed = value.trim()
@@ -47,6 +59,33 @@ export function resolveActiveOrganizationId(auth: OrganizationScopedAuth): strin
   return actorOrgId
 }
 
+/**
+ * True when the caller's organization scope was resolved to an explicitly empty set
+ * (`filterIds: []` or `allowedIds: []`), i.e. the principal can see no organization at
+ * all. An empty set is deny-all and MUST NOT be widened back to the home organization.
+ *
+ * Routes that would otherwise reveal a record's existence use this to answer with their
+ * own not-found response instead of letting `resolveSingleOrganizationIdOrDeny` throw —
+ * a thrown deny leaves the route's documented status (and the existence-oracle
+ * collapse of issue #5504) up to whoever catches it.
+ */
+export function isExplicitlyEmptyOrganizationScope(scope: FiniteOrganizationScope): boolean {
+  if (!scope) return false
+  return (Array.isArray(scope.filterIds) && scope.filterIds.length === 0)
+    || (Array.isArray(scope.allowedIds) && scope.allowedIds.length === 0)
+}
+
+export function resolveSingleOrganizationIdOrDeny(
+  scope: FiniteOrganizationScope,
+  auth: OrganizationHomeAuth,
+): string | null {
+  if (isExplicitlyEmptyOrganizationScope(scope)) {
+    throw forbidden()
+  }
+  if (scope?.selectedId) return scope.selectedId
+  return auth?.orgId ?? null
+}
+
 export const ORGANIZATION_SCOPE_REQUIRED_ERROR_CODE = 'organization_scope_required'
 
 /**

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

@@ -0,0 +1,166 @@
+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('keeps an inactive policy row out_of_stock even with a future preorder date (#6806)', async () => {
+    const future = new Date(Date.now() + 7 * 86_400_000).toISOString()
+    setCatalogOnlyPolicyLookup(async () => ({
+      'product-1:variant-1': { isActive: false, preorderReleaseAt: future, policySourceId: 'policy-4' },
+    }))
+    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)
+    expect(item.releaseAt).toBeNull()
+    expect(item.policySourceId).toBe('policy-4')
+  })
+
+  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('blocks a requested quantity above maxOrderQuantity without changing the state', async () => {
+    setCatalogOnlyPolicyLookup(async () => ({
+      'product-1:variant-1': { maxOrderQuantity: 5, policySourceId: 'policy-4' },
+    }))
+    const provider = availabilityProviderRegistry.get(AVAILABILITY_CATALOG_ONLY_PROVIDER_ID)!
+    const result = await provider.getAvailability(makeQuery({
+      items: [{ catalogProductId: 'product-1', catalogVariantId: 'variant-1', quantity: 6 }],
+    }))
+    const item = result.byItem['product-1:variant-1']
+    expect(item.state).toBe('not_tracked')
+    expect(item.canFulfil).toBe(false)
+  })
+
+  it('blocks a requested quantity below minOrderQuantity or off the quantityIncrement', async () => {
+    setCatalogOnlyPolicyLookup(async () => ({
+      'product-1:variant-1': { minOrderQuantity: 4, quantityIncrement: 4 },
+      'product-2:': { quantityIncrement: 4 },
+      'product-3:': { minOrderQuantity: 4, maxOrderQuantity: 12, quantityIncrement: 4 },
+    }))
+    const provider = availabilityProviderRegistry.get(AVAILABILITY_CATALOG_ONLY_PROVIDER_ID)!
+    const result = await provider.getAvailability(makeQuery({
+      items: [
+        { catalogProductId: 'product-1', catalogVariantId: 'variant-1', quantity: 2 },
+        { catalogProductId: 'product-2', catalogVariantId: null, quantity: 6 },
+        { catalogProductId: 'product-3', catalogVariantId: null, quantity: 8 },
+      ],
+    }))
+    expect(result.byItem['product-1:variant-1'].canFulfil).toBe(false)
+    expect(result.byItem['product-2:'].canFulfil).toBe(false)
+    expect(result.byItem['product-3:'].canFulfil).toBe(true)
+  })
+
+  it('keeps a future preorder fulfillable only within the order-quantity rules', async () => {
+    const future = new Date(Date.now() + 86_400_000).toISOString()
+    setCatalogOnlyPolicyLookup(async () => ({
+      'product-1:variant-1': { preorderReleaseAt: future, maxOrderQuantity: 1 },
+    }))
+    const provider = availabilityProviderRegistry.get(AVAILABILITY_CATALOG_ONLY_PROVIDER_ID)!
+    const result = await provider.getAvailability(makeQuery({
+      items: [{ catalogProductId: 'product-1', catalogVariantId: 'variant-1', quantity: 2 }],
+    }))
+    const item = result.byItem['product-1:variant-1']
+    expect(item.state).toBe('preorder')
+    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('hands the per-call context to the policy hook', async () => {
+    const lookup = jest.fn(async () => ({}))
+    setCatalogOnlyPolicyLookup(lookup)
+    const container = { resolve: <T,>(): T => undefined as T }
+    await resolveAvailability(makeQuery(), { container })
+    expect(lookup).toHaveBeenCalledWith(makeQuery(), { container })
+  })
+
+  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

@@ -0,0 +1,130 @@
+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 <T,>() => 'catalog-only' as T,
+    }
+    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 <T,>() => 'some-unregistered-provider' as T,
+    }
+    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('forwards the calling request container to the selected provider', async () => {
+    const getAvailability = jest.fn(async () => ({ byItem: {} }))
+    availabilityProviderRegistry.register({ id: 'wms', getAvailability })
+    const container = { resolve: <T,>(): T => undefined as T }
+    await resolveAvailability(makeQuery(), { container })
+    expect(getAvailability).toHaveBeenCalledWith(makeQuery(), { container })
+  })
+
+  it('passes a null container when the caller supplies none', async () => {
+    const getAvailability = jest.fn(async () => ({ byItem: {} }))
+    availabilityProviderRegistry.register({ id: 'wms', getAvailability })
+    await resolveAvailability(makeQuery())
+    expect(getAvailability).toHaveBeenCalledWith(makeQuery(), { container: null })
+  })
+
+  it('throws when no provider is registered at all', async () => {
+    await expect(resolveAvailability(makeQuery())).rejects.toThrow()
+  })
+})

package/src/lib/availability/catalogOnlyProvider.ts

@@ -0,0 +1,152 @@
+/**
+ * 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, AvailabilityProviderContext, 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
+  /** Requested quantities below this cannot be fulfilled. */
+  minOrderQuantity?: number | null
+  /** Requested quantities above this cannot be fulfilled — a cap independent of stock. */
+  maxOrderQuantity?: number | null
+  /** Pack size; requested quantities must be a multiple. */
+  quantityIncrement?: number | 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,
+  context?: AvailabilityProviderContext,
+) => Promise<Record<string, CatalogOnlyPolicyOverride | null | undefined>>
+
+let policyLookup: CatalogOnlyPolicyLookup | null = null
+
+/**
+ * Wired by the `availability` module's `di.ts` — never a static import from
+ * `packages/shared`. The lookup MUST resolve its dependencies from the
+ * per-call `context.container`, never from a container captured at
+ * registration time. 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,
+  }
+}
+
+function isWithinOrderQuantityRules(requested: number, override: CatalogOnlyPolicyOverride): boolean {
+  const { minOrderQuantity, maxOrderQuantity, quantityIncrement } = override
+  if (minOrderQuantity != null && requested < minOrderQuantity) return false
+  if (maxOrderQuantity != null && requested > maxOrderQuantity) return false
+  if (quantityIncrement != null && quantityIncrement > 0 && requested % quantityIncrement !== 0) return false
+  return true
+}
+
+/**
+ * Order-quantity rules are a cap independent of stock: a violation blocks
+ * fulfilment without changing the state the policy matrix produced.
+ */
+function applyOverride(
+  override: CatalogOnlyPolicyOverride | null | undefined,
+  requestedQuantity: number,
+): AvailabilityItemResult {
+  const result = applyPolicyMatrix(override)
+  if (!override || isWithinOrderQuantityRules(requestedQuantity, override)) return result
+  return { ...result, canFulfil: false }
+}
+
+/**
+ * Applies decision 7's matrix (see PLAN.md § Key design decisions) for a
+ * resolved policy override on top of the pure fallback.
+ */
+function applyPolicyMatrix(override: CatalogOnlyPolicyOverride | null | undefined): AvailabilityItemResult {
+  const base = pureFallbackItem()
+  if (!override) return base
+
+  const policySourceId = override.policySourceId ?? null
+
+  // An inactive row makes the item unpurchasable before any preorder date, exactly
+  // like the stock-tracked providers.
+  if (override.isActive === false) {
+    return { ...base, state: 'out_of_stock', canFulfil: false, policySourceId }
+  }
+
+  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.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,
+  context?: AvailabilityProviderContext,
+): Promise<AvailabilityResult> {
+  const byItem: AvailabilityResult['byItem'] = {}
+
+  let overrides: Record<string, CatalogOnlyPolicyOverride | null | undefined> = {}
+  if (policyLookup) {
+    try {
+      overrides = await policyLookup(query, context)
+    } 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], item.quantity)
+  }
+
+  return { byItem }
+}
+
+availabilityProviderRegistry.register({
+  id: AVAILABILITY_CATALOG_ONLY_PROVIDER_ID,
+  getAvailability,
+})

package/src/lib/availability/index.ts

@@ -0,0 +1,18 @@
+/**
+ * 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

@@ -0,0 +1,131 @@
+/**
+ * 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 {
+  AvailabilityDependencyResolver,
+  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
+  /**
+   * The calling request's DI container, forwarded to the selected provider
+   * as {@link AvailabilityProviderContext.container}. Omitting it makes a
+   * DI-backed provider build its own request container for the call.
+   */
+  container?: AvailabilityDependencyResolver | null
+}
+
+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, { container: options?.container ?? null })
+}