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

package/src/lib/availability/types.ts

@@ -0,0 +1,86 @@
+/**
+ * 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>
+}
+
+/** Narrow DI port a provider resolves its per-call dependencies (`em`, cache, services) from. */
+export type AvailabilityDependencyResolver = {
+  resolve: <T = unknown>(name: string) => T
+}
+
+/**
+ * Per-call context handed to a provider. `container` is the calling
+ * request's DI container; a provider MUST resolve its dependencies from it
+ * (or build its own when absent) and never from a container captured at
+ * registration time — the registry is process-wide.
+ */
+export type AvailabilityProviderContext = {
+  container?: AvailabilityDependencyResolver | null
+}
+
+export interface AvailabilityProvider {
+  id: string
+  getAvailability(query: AvailabilityQuery, context?: AvailabilityProviderContext): 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 ?? ''}`
+}

package/src/lib/catalog-visibility/__tests__/intersectScopes.test.ts

@@ -0,0 +1,168 @@
+import { intersectScopes } from '../intersectScopes'
+import { unionScopes } from '../unionScopes'
+import { matchesOne } from '../matchesOne'
+import { matchesScope } from '../matchesScope'
+import type { AssortmentScope, EffectiveAssortmentScope, ScopedProduct } from '../types'
+import { mulberry32, randomAssortmentScope, randomProduct, randomSource } from './testFixtures'
+
+function expectedMatch(product: ScopedProduct, channel: AssortmentScope | null, group: EffectiveAssortmentScope): boolean {
+  const channelMatches = channel === null ? true : matchesOne(product, channel)
+  return channelMatches && matchesScope(product, group)
+}
+
+describe('intersectScopes — null handling (§11 item 4)', () => {
+  it('intersectScopes(A, null) is equivalent to [A]: matches iff matchesOne(product, A)', () => {
+    const channel: AssortmentScope = { categoryIds: ['cat-a'] }
+    const result = intersectScopes(channel, null)
+    expect(result).toEqual([channel])
+
+    const rng = mulberry32(11)
+    for (let i = 0; i < 100; i += 1) {
+      const product = randomProduct(rng, i)
+      expect(matchesScope(product, result)).toBe(matchesOne(product, channel))
+    }
+  })
+
+  it('intersectScopes(null, null) is null', () => {
+    expect(intersectScopes(null, null)).toBeNull()
+  })
+
+  it('intersectScopes(null, group) returns group unchanged', () => {
+    const group: EffectiveAssortmentScope = [{ categoryIds: ['cat-a'] }, { tagIds: ['tag-b'] }]
+    expect(intersectScopes(null, group)).toBe(group)
+    expect(intersectScopes(null, [])).toEqual([])
+  })
+})
+
+describe('intersectScopes — distributive law (§11 item 2, property-based)', () => {
+  const CASE_COUNT = 5000
+
+  it('holds exactly for every generated fixture: matchesScope(p, channel ∩ group) === matchesOne(p, channel) && matchesScope(p, group)', () => {
+    const rng = mulberry32(202)
+    let matchedCases = 0
+    for (let i = 0; i < CASE_COUNT; i += 1) {
+      const channel = rng() < 0.15 ? null : randomAssortmentScope(rng)
+      const sourceCount = Math.floor(rng() * 3)
+      const sources = Array.from({ length: sourceCount }, () => randomSource(rng))
+      const group = unionScopes(sources)
+      const product = randomProduct(rng, i)
+
+      const expected = expectedMatch(product, channel, group)
+      expect(matchesScope(product, intersectScopes(channel, group))).toBe(expected)
+      if (expected) matchedCases += 1
+    }
+    expect(matchedCases).toBeGreaterThan(CASE_COUNT / 20)
+    expect(matchedCases).toBeLessThan(CASE_COUNT)
+  })
+
+  it('stays exact when composed repeatedly (branches that already carry allOf)', () => {
+    const rng = mulberry32(303)
+    for (let i = 0; i < CASE_COUNT; i += 1) {
+      const outer = rng() < 0.15 ? null : randomAssortmentScope(rng)
+      const inner = rng() < 0.15 ? null : randomAssortmentScope(rng)
+      const sourceCount = Math.floor(rng() * 3)
+      const group = unionScopes(Array.from({ length: sourceCount }, () => randomSource(rng)))
+      const product = randomProduct(rng, i)
+
+      const composed = intersectScopes(outer, intersectScopes(inner, group))
+      const expected = expectedMatch(product, outer, group) && (inner === null || matchesOne(product, inner))
+      expect(matchesScope(product, composed)).toBe(expected)
+    }
+  })
+
+  it('never drops a branch: the result is [] only when the group itself is []', () => {
+    const rng = mulberry32(404)
+    for (let i = 0; i < CASE_COUNT; i += 1) {
+      const channel = randomAssortmentScope(rng)
+      const sourceCount = Math.floor(rng() * 3)
+      const group = unionScopes(Array.from({ length: sourceCount }, () => randomSource(rng)))
+      const result = intersectScopes(channel, group)
+      if (group === null) {
+        expect(result).toEqual([channel])
+      } else {
+        expect(result).toHaveLength(group.length)
+      }
+    }
+    expect(intersectScopes({ categoryIds: ['cat-a'] }, [])).toEqual([])
+  })
+})
+
+describe('intersectScopes — incomparable category/tag sets are ANDed exactly via allOf', () => {
+  it('regression: channel [Electronics] ∩ group [Clearance] grants a product in both categories', () => {
+    const channel: AssortmentScope = { categoryIds: ['electronics'] }
+    const group = unionScopes([{ categoryIds: ['clearance'] }])
+    const result = intersectScopes(channel, group)
+
+    expect(result).toEqual([{ categoryIds: ['electronics'], allOf: [{ categoryIds: ['clearance'] }] }])
+
+    const inBoth: ScopedProduct = { id: 'tv', categoryIds: ['electronics', 'clearance'], tagIds: [] }
+    const electronicsOnly: ScopedProduct = { id: 'phone', categoryIds: ['electronics'], tagIds: [] }
+    const clearanceOnly: ScopedProduct = { id: 'sofa', categoryIds: ['clearance'], tagIds: [] }
+    expect(matchesScope(inBoth, result)).toBe(true)
+    expect(matchesScope(electronicsOnly, result)).toBe(false)
+    expect(matchesScope(clearanceOnly, result)).toBe(false)
+  })
+
+  it('a product satisfying channel and group via two different, non-overlapping tag ids is granted', () => {
+    const channel: AssortmentScope = { tagIds: ['channel-only'] }
+    const group = unionScopes([{ tagIds: ['group-only'] }])
+    const product: ScopedProduct = { id: 'p', categoryIds: [], tagIds: ['channel-only', 'group-only'] }
+    expect(matchesScope(product, intersectScopes(channel, group))).toBe(true)
+  })
+
+  it('a product satisfying only one side is denied', () => {
+    const channel: AssortmentScope = { tagIds: ['channel-only'] }
+    const group = unionScopes([{ tagIds: ['group-only'] }])
+    const productChannelOnly: ScopedProduct = { id: 'p', categoryIds: [], tagIds: ['channel-only'] }
+    expect(matchesScope(productChannelOnly, intersectScopes(channel, group))).toBe(false)
+  })
+
+  it('overlapping but non-subset sets match through different ids on each side', () => {
+    const channel: AssortmentScope = { tagIds: ['t2', 't4', 't5'] }
+    const group = unionScopes([{ tagIds: ['t2', 't3'] }])
+    const product: ScopedProduct = { id: 'p2', categoryIds: [], tagIds: ['t3', 't4'] }
+    expect(matchesScope(product, intersectScopes(channel, group))).toBe(true)
+  })
+
+  it('keeps the other dimension and excludes merged flat alongside the allOf residual', () => {
+    const channel: AssortmentScope = { categoryIds: ['cat-a'], tagIds: ['tag-a'], excludeProductIds: ['p-x'] }
+    const group = unionScopes([{ categoryIds: ['cat-b'], excludeTagIds: ['tag-z'] }])
+    expect(intersectScopes(channel, group)).toEqual([
+      {
+        categoryIds: ['cat-a'],
+        tagIds: ['tag-a'],
+        excludeProductIds: ['p-x'],
+        excludeTagIds: ['tag-z'],
+        allOf: [{ categoryIds: ['cat-b'] }],
+      },
+    ])
+  })
+})
+
+describe('intersectScopes — exact flat merges', () => {
+  it('one side unrestricted on a dimension: the other side wins unmodified', () => {
+    const channel: AssortmentScope = { categoryIds: ['cat-a'] }
+    const group = unionScopes([{ tagIds: ['tag-a'] }])
+    const result = intersectScopes(channel, group)
+    expect(result).toEqual([{ categoryIds: ['cat-a'], tagIds: ['tag-a'] }])
+  })
+
+  it('one set is a subset of the other: the subset wins, exactly', () => {
+    const channel: AssortmentScope = { categoryIds: ['cat-a', 'cat-b'] }
+    const group = unionScopes([{ categoryIds: ['cat-a'] }])
+    const result = intersectScopes(channel, group)
+    expect(result).toEqual([{ categoryIds: ['cat-a'] }])
+
+    const productWithOnlyCatA: ScopedProduct = { id: 'p', categoryIds: ['cat-a'], tagIds: [] }
+    const productWithOnlyCatB: ScopedProduct = { id: 'p2', categoryIds: ['cat-b'], tagIds: [] }
+    expect(matchesScope(productWithOnlyCatA, result)).toBe(true)
+    expect(matchesScope(productWithOnlyCatB, result)).toBe(false)
+  })
+
+  it('excludes always union exactly', () => {
+    const channel: AssortmentScope = { excludeCategoryIds: ['cat-x'] }
+    const group = unionScopes([{ excludeTagIds: ['tag-y'] }])
+    const result = intersectScopes(channel, group)
+    expect(result).toEqual([{ excludeCategoryIds: ['cat-x'], excludeTagIds: ['tag-y'] }])
+  })
+})

package/src/lib/catalog-visibility/__tests__/matchesOne.test.ts

@@ -0,0 +1,116 @@
+import { matchesOne } from '../matchesOne'
+import type { ScopedProduct } from '../types'
+
+const product = (overrides: Partial<ScopedProduct> = {}): ScopedProduct => ({
+  id: 'product-1',
+  categoryIds: ['cat-a'],
+  tagIds: ['tag-a'],
+  ...overrides,
+})
+
+describe('matchesOne — within-one-scope AND/OR semantics (§11 item 6)', () => {
+  it('categoryIds OR-matches: any overlapping id is enough', () => {
+    expect(matchesOne(product({ categoryIds: ['cat-a', 'cat-b'] }), { categoryIds: ['cat-b', 'cat-c'] })).toBe(true)
+    expect(matchesOne(product({ categoryIds: ['cat-x'] }), { categoryIds: ['cat-b', 'cat-c'] })).toBe(false)
+  })
+
+  it('tagIds OR-matches: any overlapping id is enough', () => {
+    expect(matchesOne(product({ tagIds: ['tag-a', 'tag-b'] }), { tagIds: ['tag-b', 'tag-c'] })).toBe(true)
+    expect(matchesOne(product({ tagIds: ['tag-x'] }), { tagIds: ['tag-b', 'tag-c'] })).toBe(false)
+  })
+
+  it('categoryIds AND tagIds both required when both are present on the scope', () => {
+    const scope = { categoryIds: ['cat-a'], tagIds: ['tag-a'] }
+    expect(matchesOne(product({ categoryIds: ['cat-a'], tagIds: ['tag-a'] }), scope)).toBe(true)
+    expect(matchesOne(product({ categoryIds: ['cat-a'], tagIds: ['tag-z'] }), scope)).toBe(false)
+    expect(matchesOne(product({ categoryIds: ['cat-z'], tagIds: ['tag-a'] }), scope)).toBe(false)
+  })
+
+  it('excludeProductIds vetoes a match already granted by inclusion', () => {
+    const scope = { categoryIds: ['cat-a'], excludeProductIds: ['product-1'] }
+    expect(matchesOne(product({ id: 'product-1', categoryIds: ['cat-a'] }), scope)).toBe(false)
+    expect(matchesOne(product({ id: 'product-2', categoryIds: ['cat-a'] }), scope)).toBe(true)
+  })
+
+  it('excludeCategoryIds vetoes a match already granted by inclusion', () => {
+    const scope = { tagIds: ['tag-a'], excludeCategoryIds: ['cat-x'] }
+    expect(matchesOne(product({ tagIds: ['tag-a'], categoryIds: ['cat-x'] }), scope)).toBe(false)
+    expect(matchesOne(product({ tagIds: ['tag-a'], categoryIds: ['cat-y'] }), scope)).toBe(true)
+  })
+
+  it('excludeTagIds vetoes a match already granted by inclusion', () => {
+    const scope = { categoryIds: ['cat-a'], excludeTagIds: ['tag-x'] }
+    expect(matchesOne(product({ categoryIds: ['cat-a'], tagIds: ['tag-x'] }), scope)).toBe(false)
+    expect(matchesOne(product({ categoryIds: ['cat-a'], tagIds: ['tag-y'] }), scope)).toBe(true)
+  })
+
+  it('excludes combine independently — each can veto on its own', () => {
+    const scope = {
+      excludeProductIds: ['product-1'],
+      excludeCategoryIds: ['cat-x'],
+      excludeTagIds: ['tag-x'],
+    }
+    expect(matchesOne(product({ id: 'other', categoryIds: ['cat-y'], tagIds: ['tag-y'] }), scope)).toBe(true)
+    expect(matchesOne(product({ id: 'product-1', categoryIds: ['cat-y'], tagIds: ['tag-y'] }), scope)).toBe(false)
+    expect(matchesOne(product({ id: 'other', categoryIds: ['cat-x'], tagIds: ['tag-y'] }), scope)).toBe(false)
+    expect(matchesOne(product({ id: 'other', categoryIds: ['cat-y'], tagIds: ['tag-x'] }), scope)).toBe(false)
+  })
+})
+
+describe('matchesOne — empty array and absent key equivalence (§11 item 7)', () => {
+  it('absent categoryIds and empty categoryIds both mean unrestricted', () => {
+    const p = product({ categoryIds: ['anything'] })
+    expect(matchesOne(p, {})).toBe(true)
+    expect(matchesOne(p, { categoryIds: [] })).toBe(true)
+  })
+
+  it('absent tagIds and empty tagIds both mean unrestricted', () => {
+    const p = product({ tagIds: ['anything'] })
+    expect(matchesOne(p, {})).toBe(true)
+    expect(matchesOne(p, { tagIds: [] })).toBe(true)
+  })
+
+  it('absent excludeProductIds and empty excludeProductIds both mean no veto', () => {
+    const p = product({ id: 'product-1' })
+    expect(matchesOne(p, {})).toBe(true)
+    expect(matchesOne(p, { excludeProductIds: [] })).toBe(true)
+  })
+
+  it('absent excludeCategoryIds and empty excludeCategoryIds both mean no veto', () => {
+    const p = product({ categoryIds: ['cat-a'] })
+    expect(matchesOne(p, {})).toBe(true)
+    expect(matchesOne(p, { excludeCategoryIds: [] })).toBe(true)
+  })
+
+  it('absent excludeTagIds and empty excludeTagIds both mean no veto', () => {
+    const p = product({ tagIds: ['tag-a'] })
+    expect(matchesOne(p, {})).toBe(true)
+    expect(matchesOne(p, { excludeTagIds: [] })).toBe(true)
+  })
+
+  it('a fully empty scope object matches every product', () => {
+    expect(matchesOne(product({ categoryIds: [], tagIds: [] }), {})).toBe(true)
+    expect(matchesOne(product({ categoryIds: ['x', 'y'], tagIds: ['z'] }), {})).toBe(true)
+  })
+})
+
+describe('matchesOne — allOf conjunction', () => {
+  it('requires every allOf scope to match in addition to the scope itself', () => {
+    const scope = { categoryIds: ['cat-a'], allOf: [{ categoryIds: ['cat-b'] }, { tagIds: ['tag-a'] }] }
+    expect(matchesOne(product({ categoryIds: ['cat-a', 'cat-b'], tagIds: ['tag-a'] }), scope)).toBe(true)
+    expect(matchesOne(product({ categoryIds: ['cat-a'], tagIds: ['tag-a'] }), scope)).toBe(false)
+    expect(matchesOne(product({ categoryIds: ['cat-a', 'cat-b'], tagIds: ['tag-z'] }), scope)).toBe(false)
+  })
+
+  it('an allOf entry can veto through its own excludes, including nested allOf', () => {
+    const scope = { allOf: [{ allOf: [{ excludeProductIds: ['product-1'] }] }] }
+    expect(matchesOne(product({ id: 'product-1' }), scope)).toBe(false)
+    expect(matchesOne(product({ id: 'product-2' }), scope)).toBe(true)
+  })
+
+  it('absent and empty allOf both add no condition', () => {
+    const p = product()
+    expect(matchesOne(p, {})).toBe(true)
+    expect(matchesOne(p, { allOf: [] })).toBe(true)
+  })
+})

package/src/lib/catalog-visibility/__tests__/matchesScope.test.ts

@@ -0,0 +1,35 @@
+import { matchesScope } from '../matchesScope'
+import type { ScopedProduct } from '../types'
+import { CATEGORY_UNIVERSE, mulberry32, randomProduct } from './testFixtures'
+
+describe('matchesScope — list-level OR and the null/[] distinction (§11 item 5)', () => {
+  it('null means unrestricted: matches every product', () => {
+    const rng = mulberry32(1)
+    for (let i = 0; i < 50; i += 1) {
+      expect(matchesScope(randomProduct(rng, i), null)).toBe(true)
+    }
+  })
+
+  it('[] (empty list) means deny-all: matches no product, for many varied products', () => {
+    const rng = mulberry32(2)
+    for (let i = 0; i < 200; i += 1) {
+      expect(matchesScope(randomProduct(rng, i), [])).toBe(false)
+    }
+    const emptyProduct: ScopedProduct = { id: 'empty', categoryIds: [], tagIds: [] }
+    expect(matchesScope(emptyProduct, [])).toBe(false)
+    const fullProduct: ScopedProduct = { id: 'full', categoryIds: [...CATEGORY_UNIVERSE], tagIds: [] }
+    expect(matchesScope(fullProduct, [])).toBe(false)
+  })
+
+  it('matches if ANY branch matches (OR across the DNF list)', () => {
+    const product: ScopedProduct = { id: 'p', categoryIds: ['cat-b'], tagIds: [] }
+    const effective = [{ categoryIds: ['cat-a'] }, { categoryIds: ['cat-b'] }, { categoryIds: ['cat-c'] }]
+    expect(matchesScope(product, effective)).toBe(true)
+  })
+
+  it('matches nothing when no branch matches', () => {
+    const product: ScopedProduct = { id: 'p', categoryIds: ['cat-z'], tagIds: [] }
+    const effective = [{ categoryIds: ['cat-a'] }, { categoryIds: ['cat-b'] }]
+    expect(matchesScope(product, effective)).toBe(false)
+  })
+})

package/src/lib/catalog-visibility/__tests__/testFixtures.ts

@@ -0,0 +1,66 @@
+import type { AssortmentScope, ScopedProduct } from '../types'
+
+/**
+ * Deterministic PRNG (mulberry32) so property-based runs are reproducible across CI runs
+ * without pulling in a third-party dependency — no `fast-check`-equivalent library is
+ * present anywhere in this monorepo's workspaces (checked via `yarn why fast-check` /
+ * grepping every `package.json`), so this hand-rolled generator is the documented fallback
+ * per `.ai/specs/2026-04-24-agentic-property-based-testing.md`.
+ */
+export function mulberry32(seed: number): () => number {
+  let state = seed | 0
+  return function next(): number {
+    state = (state + 0x6d2b79f5) | 0
+    let t = Math.imul(state ^ (state >>> 15), 1 | state)
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296
+  }
+}
+
+export const CATEGORY_UNIVERSE = ['c1', 'c2', 'c3', 'c4', 'c5']
+export const TAG_UNIVERSE = ['t1', 't2', 't3', 't4', 't5']
+export const PRODUCT_ID_UNIVERSE = ['p1', 'p2', 'p3', 'p4', 'p5']
+
+function randomSubset(rng: () => number, universe: string[], inclusionRate = 0.4): string[] {
+  return universe.filter(() => rng() < inclusionRate)
+}
+
+/** Generates a random `AssortmentScope | null` "source" (as `unionScopes` consumes). */
+export function randomSource(rng: () => number): AssortmentScope | null {
+  if (rng() < 0.2) return null
+  const scope: AssortmentScope = {}
+  if (rng() < 0.6) {
+    const categoryIds = randomSubset(rng, CATEGORY_UNIVERSE)
+    if (categoryIds.length > 0) scope.categoryIds = categoryIds
+  }
+  if (rng() < 0.6) {
+    const tagIds = randomSubset(rng, TAG_UNIVERSE)
+    if (tagIds.length > 0) scope.tagIds = tagIds
+  }
+  if (rng() < 0.2) {
+    const excludeProductIds = randomSubset(rng, PRODUCT_ID_UNIVERSE)
+    if (excludeProductIds.length > 0) scope.excludeProductIds = excludeProductIds
+  }
+  if (rng() < 0.2) {
+    const excludeCategoryIds = randomSubset(rng, CATEGORY_UNIVERSE)
+    if (excludeCategoryIds.length > 0) scope.excludeCategoryIds = excludeCategoryIds
+  }
+  if (rng() < 0.2) {
+    const excludeTagIds = randomSubset(rng, TAG_UNIVERSE)
+    if (excludeTagIds.length > 0) scope.excludeTagIds = excludeTagIds
+  }
+  return scope
+}
+
+/** Generates a random `AssortmentScope` (never `null`) for use as a channel scope. */
+export function randomAssortmentScope(rng: () => number): AssortmentScope {
+  return (randomSource(rng) ?? {}) as AssortmentScope
+}
+
+export function randomProduct(rng: () => number, index: number): ScopedProduct {
+  return {
+    id: PRODUCT_ID_UNIVERSE[index % PRODUCT_ID_UNIVERSE.length],
+    categoryIds: randomSubset(rng, CATEGORY_UNIVERSE),
+    tagIds: randomSubset(rng, TAG_UNIVERSE),
+  }
+}

package/src/lib/catalog-visibility/__tests__/unionScopes.test.ts

@@ -0,0 +1,62 @@
+import { unionScopes } from '../unionScopes'
+import { matchesScope } from '../matchesScope'
+import type { ScopedProduct } from '../types'
+
+describe('unionScopes — R2 regression: union is OR across dimensions, not flattened AND', () => {
+  it('keeps each source as its own unmodified OR-branch, exact shape', () => {
+    const result = unionScopes([{ categoryIds: ['A'] }, { tagIds: ['B'] }])
+    expect(result).toEqual([{ categoryIds: ['A'] }, { tagIds: ['B'] }])
+  })
+
+  it('a product in category A but NOT tagged B is granted by the category-A branch alone', () => {
+    const result = unionScopes([{ categoryIds: ['A'] }, { tagIds: ['B'] }])
+    const product: ScopedProduct = { id: 'p1', categoryIds: ['A'], tagIds: [] }
+    expect(matchesScope(product, result)).toBe(true)
+  })
+
+  it('a product tagged B but NOT in category A is granted by the tag-B branch alone', () => {
+    const result = unionScopes([{ categoryIds: ['A'] }, { tagIds: ['B'] }])
+    const product: ScopedProduct = { id: 'p2', categoryIds: [], tagIds: ['B'] }
+    expect(matchesScope(product, result)).toBe(true)
+  })
+
+  it('a product with neither category A nor tag B is granted by neither branch', () => {
+    const result = unionScopes([{ categoryIds: ['A'] }, { tagIds: ['B'] }])
+    const product: ScopedProduct = { id: 'p3', categoryIds: ['Z'], tagIds: ['Y'] }
+    expect(matchesScope(product, result)).toBe(false)
+  })
+
+  it('the naive flattened-AND mistake would have wrongly rejected the category-A-only product', () => {
+    // Documented as a regression guard: the first draft merged sources into one flat
+    // AssortmentScope ({ categoryIds: ['A'], tagIds: ['B'] }), which AND's the two
+    // dimensions together instead of OR-ing the two sources. Assert that shape is NOT
+    // what unionScopes produces, and that evaluating against it would give the wrong answer.
+    const flattenedWrong = { categoryIds: ['A'], tagIds: ['B'] }
+    const product: ScopedProduct = { id: 'p1', categoryIds: ['A'], tagIds: [] }
+    expect(matchesScope(product, [flattenedWrong])).toBe(false) // the bug: wrongly denied
+    expect(matchesScope(product, unionScopes([{ categoryIds: ['A'] }, { tagIds: ['B'] }]))).toBe(true) // the fix
+  })
+})
+
+describe('unionScopes — null propagation (§11 item 3)', () => {
+  it('any unrestricted (null) source makes the whole union unrestricted', () => {
+    expect(unionScopes([null, { categoryIds: ['A'] }])).toBeNull()
+    expect(unionScopes([{ categoryIds: ['A'] }, null])).toBeNull()
+  })
+
+  it('no sources at all is unrestricted', () => {
+    expect(unionScopes([])).toBeNull()
+  })
+
+  it('multiple non-null sources with no null among them stay a DNF list', () => {
+    const result = unionScopes([{ categoryIds: ['A'] }, { categoryIds: ['B'] }])
+    expect(result).toEqual([{ categoryIds: ['A'] }, { categoryIds: ['B'] }])
+  })
+
+  it("returns a fresh array, never the caller's own list", () => {
+    const input = [{ categoryIds: ['A'] }, { tagIds: ['B'] }]
+    const result = unionScopes(input)
+    expect(result).not.toBe(input)
+    expect(result).toEqual(input)
+  })
+})

package/src/lib/catalog-visibility/index.ts

@@ -0,0 +1,5 @@
+export type { AssortmentScope, EffectiveAssortmentScope, ScopedProduct } from './types'
+export { matchesOne } from './matchesOne'
+export { matchesScope } from './matchesScope'
+export { unionScopes } from './unionScopes'
+export { intersectScopes } from './intersectScopes'

package/src/lib/catalog-visibility/intersectScopes.ts

@@ -0,0 +1,93 @@
+import type { AssortmentScope, EffectiveAssortmentScope } from './types'
+
+type FieldCombination = { ids: string[] | undefined; residual: string[] | undefined }
+
+/**
+ * Combines one dimension (categoryIds or tagIds) from two independent AND-scopes. Every
+ * outcome is exact — `overlap(P, ids) && overlap(P, residual)` equals
+ * `overlap(P, channelIds) && overlap(P, groupIds)` for every product:
+ *
+ * - Both absent/empty -> unrestricted (`undefined`).
+ * - Only one side restricts -> that side's set, unmodified (the other side is vacuously true).
+ * - Both restrict and one set is a subset of the other (including equal sets) -> the subset,
+ *   because overlapping the subset already implies overlapping the superset.
+ * - Both restrict with incomparable sets -> the channel's set stays on the branch and the
+ *   group's set is returned as `residual`, to be ANDed via `allOf`. Set-intersecting the two
+ *   would wrongly deny a product that satisfies each side through a different id (e.g. a
+ *   product in both Electronics and Clearance under channel [Electronics] ∩ group [Clearance]).
+ */
+function combineField(channelIds: string[] | undefined, groupIds: string[] | undefined): FieldCombination {
+  const a = channelIds && channelIds.length > 0 ? channelIds : undefined
+  const b = groupIds && groupIds.length > 0 ? groupIds : undefined
+  if (!a && !b) return { ids: undefined, residual: undefined }
+  if (!a) return { ids: b, residual: undefined }
+  if (!b) return { ids: a, residual: undefined }
+  const bSet = new Set(b)
+  if (a.every((id) => bSet.has(id))) return { ids: a, residual: undefined }
+  const aSet = new Set(a)
+  if (b.every((id) => aSet.has(id))) return { ids: b, residual: undefined }
+  return { ids: a, residual: b }
+}
+
+/**
+ * Excludes are always safe to union: `NOT excluded_a AND NOT excluded_b` is exactly
+ * `NOT (excluded_a OR excluded_b)`, i.e. avoiding the union of both exclude sets.
+ */
+function unionIds(a: string[] | undefined, b: string[] | undefined): string[] | undefined {
+  const merged = [...(a ?? []), ...(b ?? [])]
+  if (merged.length === 0) return undefined
+  return Array.from(new Set(merged))
+}
+
+/**
+ * Builds one branch equivalent to "matches `channel` AND matches `group`". Dimensions and
+ * excludes are merged into flat fields where that is exact; whatever cannot be merged
+ * exactly (incomparable inclusion sets, and any `allOf` either side already carries) is
+ * kept as `allOf` entries, which `matchesOne` ANDs at match time. Never returns an
+ * unsatisfiable-looking or dropped branch.
+ */
+function mergeAsConjunction(channel: AssortmentScope, group: AssortmentScope): AssortmentScope {
+  const categoryCombination = combineField(channel.categoryIds, group.categoryIds)
+  const tagCombination = combineField(channel.tagIds, group.tagIds)
+
+  const merged: AssortmentScope = {}
+  if (categoryCombination.ids) merged.categoryIds = categoryCombination.ids
+  if (tagCombination.ids) merged.tagIds = tagCombination.ids
+
+  const excludeProductIds = unionIds(channel.excludeProductIds, group.excludeProductIds)
+  if (excludeProductIds) merged.excludeProductIds = excludeProductIds
+  const excludeCategoryIds = unionIds(channel.excludeCategoryIds, group.excludeCategoryIds)
+  if (excludeCategoryIds) merged.excludeCategoryIds = excludeCategoryIds
+  const excludeTagIds = unionIds(channel.excludeTagIds, group.excludeTagIds)
+  if (excludeTagIds) merged.excludeTagIds = excludeTagIds
+
+  const residual: AssortmentScope = {}
+  if (categoryCombination.residual) residual.categoryIds = categoryCombination.residual
+  if (tagCombination.residual) residual.tagIds = tagCombination.residual
+
+  const allOf: AssortmentScope[] = [
+    ...(Object.keys(residual).length > 0 ? [residual] : []),
+    ...(channel.allOf ?? []),
+    ...(group.allOf ?? []),
+  ]
+  if (allOf.length > 0) merged.allOf = allOf
+
+  return merged
+}
+
+/**
+ * Distributes a single channel-level scope across every branch of an already-unioned
+ * group-level effective scope: (channel) ∩ (g1 ∪ g2 ∪ ... ∪ gn) = (channel∩g1) ∪ (channel∩g2) ∪ ...
+ * Each branch is exact by construction (spec §3.3 / §11):
+ * `matchesScope(p, intersectScopes(channel, group)) === (channel === null || matchesOne(p, channel)) && matchesScope(p, group)`
+ * for every product. See `mergeAsConjunction` for how a branch carries both conditions.
+ *
+ * Branches are never dropped, so the result is `[]` (deny-all) only when `group` is `[]`.
+ * Merging raw category/tag arrays by plain union or intersection is wrong for the same
+ * structural reason flattening the union was wrong (R2) — do not reintroduce it.
+ */
+export function intersectScopes(channel: AssortmentScope | null, group: EffectiveAssortmentScope): EffectiveAssortmentScope {
+  if (channel === null) return group
+  if (group === null) return [channel]
+  return group.map((branch) => mergeAsConjunction(channel, branch))
+}

package/src/lib/catalog-visibility/matchesOne.ts

@@ -0,0 +1,28 @@
+import type { AssortmentScope, ScopedProduct } from './types'
+
+function overlaps(productIds: string[], scopeIds: string[]): boolean {
+  if (productIds.length === 0 || scopeIds.length === 0) return false
+  const set = new Set(scopeIds)
+  return productIds.some((id) => set.has(id))
+}
+
+function included(product: ScopedProduct, scope: AssortmentScope): boolean {
+  const categoryIds = scope.categoryIds ?? []
+  const tagIds = scope.tagIds ?? []
+  const categoryOk = categoryIds.length === 0 || overlaps(product.categoryIds, categoryIds)
+  const tagOk = tagIds.length === 0 || overlaps(product.tagIds, tagIds)
+  return categoryOk && tagOk
+}
+
+/** AND match of one scope, including every nested `allOf` scope. */
+export function matchesOne(product: ScopedProduct, scope: AssortmentScope): boolean {
+  if (!included(product, scope)) return false
+  const excludeProductIds = scope.excludeProductIds ?? []
+  if (excludeProductIds.includes(product.id)) return false
+  const excludeCategoryIds = scope.excludeCategoryIds ?? []
+  if (excludeCategoryIds.length > 0 && overlaps(product.categoryIds, excludeCategoryIds)) return false
+  const excludeTagIds = scope.excludeTagIds ?? []
+  if (excludeTagIds.length > 0 && overlaps(product.tagIds, excludeTagIds)) return false
+  const allOf = scope.allOf ?? []
+  return allOf.every((nested) => matchesOne(product, nested))
+}