@bespokeagentics/microdots-host 0.1.0

package/src/rules.test.ts

@@ -0,0 +1,598 @@
+import { Option } from 'effect'
+import { describe, expect, test } from 'vitest'
+
+import { resolvePlacements, ruleMatches } from './rules.ts'
+import type {
+  HostTopology,
+  RouteRule,
+  TopologyPlacement,
+  TopologyRoute,
+} from './wire.ts'
+
+/* ============================================================
+   Fixture builders — the smallest topology that can host a contest: one or
+   two routes, zero or more rules, placements with explicit ids so the
+   override assertions can name winners and losers without re-deriving the
+   synthesized fallback.
+   ============================================================ */
+
+const route = (
+  path: string,
+  mounts: ReadonlyArray<TopologyPlacement>,
+): TopologyRoute => ({
+  path,
+  label: path,
+  title: path,
+  sectionIds: [],
+  mounts,
+})
+
+const topologyOf = (
+  routes: readonly [TopologyRoute, ...Array<TopologyRoute>],
+  rules?: ReadonlyArray<RouteRule>,
+): HostTopology => ({
+  host: { id: 'test-host', label: 'Test host', ownedInputs: [] },
+  routes,
+  ...(rules === undefined ? {} : { rules }),
+  wires: [],
+  watch: [],
+})
+
+const patternRule = (
+  id: string,
+  pattern: string,
+  placements: ReadonlyArray<TopologyPlacement>,
+): RouteRule => ({
+  id,
+  kind: 'pattern',
+  label: `Rule ${id}`,
+  pattern,
+  placements,
+})
+
+const groupRule = (
+  id: string,
+  paths: ReadonlyArray<string>,
+  placements: ReadonlyArray<TopologyPlacement>,
+): RouteRule => ({ id, kind: 'group', label: `Rule ${id}`, paths, placements })
+
+const dynamicRule = (
+  id: string,
+  template: string,
+  placements: ReadonlyArray<TopologyPlacement>,
+): RouteRule => ({
+  id,
+  kind: 'dynamic',
+  label: `Rule ${id}`,
+  template,
+  placements,
+})
+
+// The failure mode: this is THE matcher (the phase's ruling 1) — the runtime
+// resolution and the Pages screen's per-rule match counts both call it, so a
+// wrong match here is simultaneously a dot mounted on the wrong page and a
+// screen count nobody can reconcile with what actually renders.
+describe('ruleMatches', () => {
+  test('the bare /* glob matches every path', () => {
+    const rule = patternRule('r1', '/*', [])
+    expect(ruleMatches(rule, '/')).toBe(true)
+    expect(ruleMatches(rule, '/apps')).toBe(true)
+    expect(ruleMatches(rule, '/docs/rpc-contracts')).toBe(true)
+  })
+
+  test('a prefixed glob matches strict descendants of the prefix only', () => {
+    const rule = patternRule('r1', '/blog/*', [])
+    expect(ruleMatches(rule, '/blog/effect-first-ports')).toBe(true)
+    expect(ruleMatches(rule, '/blog/2026/august')).toBe(true)
+    expect(ruleMatches(rule, '/blog')).toBe(false)
+    expect(ruleMatches(rule, '/blogging')).toBe(false)
+  })
+
+  test('a pattern without the wildcard is an exact match', () => {
+    const rule = patternRule('r1', '/pricing', [])
+    expect(ruleMatches(rule, '/pricing')).toBe(true)
+    expect(ruleMatches(rule, '/pricing/plans')).toBe(false)
+  })
+
+  test('a group rule matches exactly its listed paths', () => {
+    const rule = groupRule('r1', ['/apps', '/builds', '/deploys'], [])
+    expect(ruleMatches(rule, '/apps')).toBe(true)
+    expect(ruleMatches(rule, '/deploys')).toBe(true)
+    expect(ruleMatches(rule, '/wiring')).toBe(false)
+  })
+
+  test('a dynamic template matches segment-wise, one segment per param', () => {
+    const rule = dynamicRule('r1', '/docs/:slug', [])
+    expect(ruleMatches(rule, '/docs/rpc-contracts')).toBe(true)
+    expect(ruleMatches(rule, '/docs')).toBe(false)
+    expect(ruleMatches(rule, '/docs/a/b')).toBe(false)
+    expect(ruleMatches(rule, '/blog/rpc-contracts')).toBe(false)
+  })
+})
+
+/* ============================================================
+   resolvePlacements — layering, the reading-B contest, provenance.
+   ============================================================ */
+
+// The failure mode: both shells' `activate` mounts THIS function's output
+// instead of raw `route.mounts` (the ruling-A dogfood), so a resolution that
+// invents, drops or mis-attributes a placement is a page rendering the wrong
+// dots — and the Pages screen's override badges narrating a contest that
+// never happened.
+describe('resolvePlacements', () => {
+  test('a no-rules topology resolves a single mount to the fully-defaulted identity', () => {
+    const topology = topologyOf([
+      route('/price', [{ tag: 'price-ticker', slotId: 'price-slot' }]),
+    ])
+    // The whole record, pinned: defaults made explicit (condition axes to
+    // 'any', envs to all three, values to {}), route provenance, and the
+    // synthesized stable id Phase-4 records get — screen selection and check
+    // issues depend on that id never changing shape.
+    expect(resolvePlacements(topology, '/price', 'dev')).toEqual([
+      {
+        id: '/price|0|route:price-ticker@price-slot#0',
+        tag: 'price-ticker',
+        slotId: 'price-slot',
+        source: { _tag: 'route' },
+        condition: { who: 'any', device: 'any', locale: 'any' },
+        envs: ['dev', 'preview', 'prod'],
+        values: {},
+        span: Option.none(),
+        order: Option.none(),
+        state: 'active',
+        overriddenBy: [],
+      },
+    ])
+  })
+
+  test('a no-rules topology resolves to exactly the route’s own mounts — the Phase-4 identity', () => {
+    const mounts: ReadonlyArray<TopologyPlacement> = [
+      { tag: 'price-ticker', slotId: 'price-slot' },
+      { tag: 'fleet-health', slotId: 'fleet-slot' },
+    ]
+    const topology = topologyOf([route('/all', mounts)])
+    const resolved = resolvePlacements(topology, '/all', 'dev')
+    // The backward-compat pin: what the shells mount is the (tag, slotId)
+    // projection, and with no rules it must equal `route.mounts` byte for
+    // byte — Phase 4 behaviour, unchanged.
+    expect(
+      resolved.map(item => ({ tag: item.tag, slotId: item.slotId })),
+    ).toEqual(mounts)
+    expect(resolved.map(item => item.state)).toEqual(['active', 'active'])
+  })
+
+  test('layers matching rules in declared order with the route’s own placements last', () => {
+    const topology = topologyOf(
+      [
+        route('/apps', [
+          { id: 'from-route', tag: 'workbench-brief', slotId: 'brief-slot' },
+        ]),
+      ],
+      [
+        patternRule('r0', '/blog/*', [
+          { id: 'never-here', tag: 'blog-toc', slotId: 'side-slot' },
+        ]),
+        patternRule('r1', '/*', [
+          { id: 'from-r1', tag: 'promo-banner', slotId: 'hero-slot' },
+        ]),
+        groupRule(
+          'r2',
+          ['/apps'],
+          [{ id: 'from-r2', tag: 'nav-crumbs', slotId: 'top-bar' }],
+        ),
+      ],
+    )
+    const resolved = resolvePlacements(topology, '/apps', 'dev')
+    expect(resolved.map(item => item.id)).toEqual([
+      'from-r1',
+      'from-r2',
+      'from-route',
+    ])
+    expect(resolved.map(item => item.source)).toEqual([
+      { _tag: 'rule', ruleId: 'r1', label: 'Rule r1' },
+      { _tag: 'rule', ruleId: 'r2', label: 'Rule r2' },
+      { _tag: 'route' },
+    ])
+  })
+
+  test('the route’s own placement overrides a rule’s entirely when it covers its whole condition', () => {
+    const topology = topologyOf(
+      [
+        route('/home', [
+          { id: 'winner', tag: 'promo-banner', slotId: 'hero-slot' },
+        ]),
+      ],
+      [
+        patternRule('r1', '/*', [
+          { id: 'loser', tag: 'promo-banner', slotId: 'hero-slot' },
+        ]),
+      ],
+    )
+    const resolved = resolvePlacements(topology, '/home', 'dev')
+    // The loser is KEPT — the spec renders it struck-through, not deleted —
+    // with provenance naming who beat it and where. A resolution that drops
+    // losers passes every "what renders" assertion and fails here.
+    expect(resolved.map(item => ({ id: item.id, state: item.state }))).toEqual([
+      { id: 'loser', state: 'overridden' },
+      { id: 'winner', state: 'active' },
+    ])
+    expect(resolved.map(item => item.overriddenBy)).toEqual([
+      [
+        {
+          by: { _tag: 'route' },
+          winnerId: 'winner',
+          where: { who: 'any', device: 'any', locale: 'any' },
+          entire: true,
+        },
+      ],
+      [],
+    ])
+  })
+
+  test('a conditioned winner overrides only where the conditions overlap, and the badge names that region', () => {
+    const topology = topologyOf(
+      [
+        route('/home', [
+          {
+            id: 'winner',
+            tag: 'promo-banner',
+            slotId: 'hero-slot',
+            condition: { locale: 'fr' },
+          },
+        ]),
+      ],
+      [
+        patternRule('r1', '/*', [
+          { id: 'loser', tag: 'promo-banner', slotId: 'hero-slot' },
+        ]),
+      ],
+    )
+    const resolved = resolvePlacements(topology, '/home', 'dev')
+    // Reading B: the unconditioned loser still renders for everyone outside
+    // `fr`, so it is partially overridden — and `where` carries the exact
+    // overlap so the screen's badge can say "overridden for fr".
+    expect(
+      resolved.map(item => ({
+        id: item.id,
+        state: item.state,
+        overriddenBy: item.overriddenBy,
+      })),
+    ).toEqual([
+      {
+        id: 'loser',
+        state: 'partially-overridden',
+        overriddenBy: [
+          {
+            by: { _tag: 'route' },
+            winnerId: 'winner',
+            where: { who: 'any', device: 'any', locale: 'fr' },
+            entire: false,
+          },
+        ],
+      },
+      { id: 'winner', state: 'active', overriddenBy: [] },
+    ])
+  })
+
+  test('disjoint conditions do not contest — both placements stay active', () => {
+    const topology = topologyOf(
+      [
+        route('/home', [
+          {
+            id: 'english',
+            tag: 'promo-banner',
+            slotId: 'hero-slot',
+            condition: { locale: 'en' },
+          },
+        ]),
+      ],
+      [
+        patternRule('r1', '/*', [
+          {
+            id: 'french',
+            tag: 'promo-banner',
+            slotId: 'hero-slot',
+            condition: { locale: 'fr' },
+          },
+        ]),
+      ],
+    )
+    const resolved = resolvePlacements(topology, '/home', 'dev')
+    // The overlap-inversion kill: `fr` vs `en` differ on one axis, so under
+    // the real rule (every axis either-side-'any'-or-equal) there is NO
+    // overlap and NO override. An inverted overlap predicate would contest
+    // exactly this pair and fail here.
+    expect(resolved.map(item => ({ id: item.id, state: item.state }))).toEqual([
+      { id: 'french', state: 'active' },
+      { id: 'english', state: 'active' },
+    ])
+    expect(resolved.map(item => item.overriddenBy)).toEqual([[], []])
+  })
+
+  test("the literal string 'any' on an axis overlaps exactly like an absent axis", () => {
+    const topology = topologyOf(
+      [
+        route('/home', [
+          {
+            id: 'winner',
+            tag: 'promo-banner',
+            slotId: 'hero-slot',
+            condition: { who: 'any', device: 'any' },
+          },
+        ]),
+      ],
+      [
+        patternRule('r1', '/*', [
+          {
+            id: 'loser',
+            tag: 'promo-banner',
+            slotId: 'hero-slot',
+            condition: { who: 'admin', locale: 'any' },
+          },
+        ]),
+      ],
+    )
+    const resolved = resolvePlacements(topology, '/home', 'dev')
+    // Every axis pair here mixes a literal 'any' with an absent axis or a
+    // narrow value — if the literal were treated as its own value ('any' ≠
+    // absence), no axis would equal its counterpart and the contest would
+    // never fire.
+    expect(resolved.map(item => ({ id: item.id, state: item.state }))).toEqual([
+      { id: 'loser', state: 'overridden' },
+      { id: 'winner', state: 'active' },
+    ])
+    expect(resolved.map(item => item.overriddenBy)).toEqual([
+      [
+        {
+          by: { _tag: 'route' },
+          winnerId: 'winner',
+          where: { who: 'admin', device: 'any', locale: 'any' },
+          entire: true,
+        },
+      ],
+      [],
+    ])
+  })
+
+  test('filters placements to the requested environment', () => {
+    const topology = topologyOf([
+      route('/home', [
+        { id: 'everywhere', tag: 'promo-banner', slotId: 'hero-slot' },
+        {
+          id: 'dev-only',
+          tag: 'debug-panel',
+          slotId: 'side-slot',
+          envs: ['dev'],
+        },
+      ]),
+    ])
+    expect(
+      resolvePlacements(topology, '/home', 'dev').map(item => item.id),
+    ).toEqual(['everywhere', 'dev-only'])
+    expect(
+      resolvePlacements(topology, '/home', 'prod').map(item => item.id),
+    ).toEqual(['everywhere'])
+  })
+
+  test('a placement absent from the environment cannot override there either', () => {
+    const topology = topologyOf(
+      [
+        route('/home', [
+          {
+            id: 'dev-winner',
+            tag: 'promo-banner',
+            slotId: 'hero-slot',
+            envs: ['dev'],
+          },
+        ]),
+      ],
+      [
+        patternRule('r1', '/*', [
+          { id: 'base', tag: 'promo-banner', slotId: 'hero-slot' },
+        ]),
+      ],
+    )
+    // In dev the route placement exists and wins; in prod it does not exist,
+    // so the rule's placement must come back ACTIVE — an override by a
+    // placement that cannot render here would blank the slot for real users.
+    expect(
+      resolvePlacements(topology, '/home', 'dev').map(item => ({
+        id: item.id,
+        state: item.state,
+      })),
+    ).toEqual([
+      { id: 'base', state: 'overridden' },
+      { id: 'dev-winner', state: 'active' },
+    ])
+    expect(
+      resolvePlacements(topology, '/home', 'prod').map(item => ({
+        id: item.id,
+        state: item.state,
+      })),
+    ).toEqual([{ id: 'base', state: 'active' }])
+  })
+
+  test('rule order is load-bearing: the later-declared rule wins the contest', () => {
+    const topology = topologyOf(
+      [route('/apps', [])],
+      [
+        patternRule('r1', '/*', [
+          { id: 'first', tag: 'promo-banner', slotId: 'hero-slot' },
+        ]),
+        groupRule(
+          'r2',
+          ['/apps'],
+          [{ id: 'second', tag: 'promo-banner', slotId: 'hero-slot' }],
+        ),
+      ],
+    )
+    const resolved = resolvePlacements(topology, '/apps', 'dev')
+    // The order-mutation kill: ignoring declared order puts both rules in one
+    // layer (no override at all), and reversing it flips winner and loser —
+    // either way this exact pairing fails.
+    expect(resolved.map(item => ({ id: item.id, state: item.state }))).toEqual([
+      { id: 'first', state: 'overridden' },
+      { id: 'second', state: 'active' },
+    ])
+    expect(
+      resolved.flatMap(item =>
+        item.overriddenBy.map(override => override.winnerId),
+      ),
+    ).toEqual(['second'])
+  })
+
+  /* ============================================================
+     Resolved ids. The failure mode: EVERY downstream reference to a
+     placement is its id — `overriddenBy.winnerId`, every check issue's
+     `placementId`, and the Pages screen's selection across polls and env
+     switches. Two placements sharing one id is therefore three bugs at
+     once: the inspector shows the first while merging BOTH placements'
+     issues onto it, the canvas highlights two cards for one selection, and
+     `overridePair` (placementChecks.ts) matches `winnerId === other.id` and
+     SUPPRESSES a legitimate check-4 warning. None of it is caught by
+     anything downstream — this is the only place it can be.
+     ============================================================ */
+  describe('resolved ids are unique and stable', () => {
+    test('a rule placement matching two routes gets a DIFFERENT id on each', () => {
+      const topology = topologyOf(
+        [route('/price', []), route('/fleet', [])],
+        [
+          patternRule('r1', '/*', [
+            { tag: 'promo-banner', slotId: 'hero-slot' },
+          ]),
+        ],
+      )
+      // The demo host's derived overview resolves as the UNION of every
+      // component route's resolution, so a `/*` rule's one placement lands in
+      // that union once per route. Without the path component every one of
+      // them carries the same id and the union is a pile of collisions.
+      const onPrice = resolvePlacements(topology, '/price', 'dev').map(
+        item => item.id,
+      )
+      const onFleet = resolvePlacements(topology, '/fleet', 'dev').map(
+        item => item.id,
+      )
+      expect(onPrice).toEqual(['/price|0|r1:promo-banner@hero-slot#0'])
+      expect(onFleet).toEqual(['/fleet|0|r1:promo-banner@hero-slot#0'])
+    })
+
+    test('a rule whose id is literally "route" does not collide with the route layer', () => {
+      const topology = topologyOf(
+        [route('/home', [{ tag: 'promo-banner', slotId: 'hero-slot' }])],
+        [
+          patternRule('route', '/*', [
+            { tag: 'promo-banner', slotId: 'hero-slot' },
+          ]),
+        ],
+      )
+      // Same tag, same slot, index 0 in both layers, and the rule's id IS the
+      // route layer's source key — everything but the layer number is equal,
+      // which is why the layer number is in the synthesized key.
+      const ids = resolvePlacements(topology, '/home', 'dev').map(
+        item => item.id,
+      )
+      expect(new Set(ids).size).toBe(2)
+      expect(ids).toEqual([
+        '/home|0|route:promo-banner@hero-slot#0',
+        '/home|1|route:promo-banner@hero-slot#0',
+      ])
+    })
+
+    test('two placements declaring the SAME id are both disambiguated, neither keeping the bare id', () => {
+      const topology = topologyOf(
+        [
+          route('/home', [
+            { id: 'dup', tag: 'promo-banner', slotId: 'hero-slot' },
+          ]),
+        ],
+        [
+          patternRule('r1', '/*', [
+            { id: 'dup', tag: 'nav-crumbs', slotId: 'top-bar' },
+          ]),
+        ],
+      )
+      const ids = resolvePlacements(topology, '/home', 'dev').map(
+        item => item.id,
+      )
+      // Symmetric on purpose: a first-wins rule would let one of the pair keep
+      // `dup`, which reads as authoritative and hides that a second placement
+      // is masquerading as it.
+      expect(ids).toEqual([
+        'dup~/home|0|r1:nav-crumbs@top-bar#0',
+        'dup~/home|1|route:promo-banner@hero-slot#0',
+      ])
+      expect(new Set(ids).size).toBe(2)
+    })
+
+    test('a UNIQUE declared id is handed back verbatim — the screen selects by it', () => {
+      const topology = topologyOf([
+        route('/home', [
+          { id: 'hero', tag: 'promo-banner', slotId: 'hero-slot' },
+          { id: 'crumbs', tag: 'nav-crumbs', slotId: 'top-bar' },
+        ]),
+      ])
+      expect(
+        resolvePlacements(topology, '/home', 'dev').map(item => item.id),
+      ).toEqual(['hero', 'crumbs'])
+    })
+
+    test('an id does not move when the ENV filter drops a sibling', () => {
+      const topology = topologyOf([
+        route('/home', [
+          { tag: 'debug-panel', slotId: 'side-slot', envs: ['dev'] },
+          { tag: 'promo-banner', slotId: 'hero-slot' },
+        ]),
+      ])
+      // The Pages screen keeps its selection across an env switch, so the
+      // synthesized index must be the index within the UNFILTERED layer — a
+      // running index over the filtered set would renumber the banner from #1
+      // to #0 the moment the reader switched to prod.
+      const inDev = resolvePlacements(topology, '/home', 'dev')
+      const inProd = resolvePlacements(topology, '/home', 'prod')
+      expect(inProd.map(item => item.id)).toEqual([
+        '/home|0|route:promo-banner@hero-slot#1',
+      ])
+      expect(
+        inDev.filter(item => item.tag === 'promo-banner').map(item => item.id),
+      ).toEqual(inProd.map(item => item.id))
+    })
+
+    test('the override contest names the winner by its RESOLVED id, collisions included', () => {
+      const topology = topologyOf(
+        [
+          route('/home', [
+            { id: 'dup', tag: 'promo-banner', slotId: 'hero-slot' },
+          ]),
+        ],
+        [
+          patternRule('r1', '/*', [
+            { id: 'dup', tag: 'promo-banner', slotId: 'hero-slot' },
+          ]),
+        ],
+      )
+      const resolved = resolvePlacements(topology, '/home', 'dev')
+      const winnerIds = resolved.flatMap(item =>
+        item.overriddenBy.map(override => override.winnerId),
+      )
+      // A `winnerId` that matched more than one member of the output would
+      // make `overridePair` true for pairs that never contested.
+      expect(winnerIds).toEqual(['dup~/home|1|route:promo-banner@hero-slot#0'])
+      expect(resolved.map(item => item.id)).toContain(winnerIds[0])
+    })
+  })
+
+  test('two placements in the same layer never override each other', () => {
+    const topology = topologyOf([
+      route('/home', [
+        { id: 'twin-a', tag: 'promo-banner', slotId: 'hero-slot' },
+        { id: 'twin-b', tag: 'promo-banner', slotId: 'hero-slot' },
+      ]),
+    ])
+    // Peers at one specificity are the CHECKS' business (checks 4/7), not the
+    // contest's — resolving them as overrides would silence the duplicate
+    // warning the spec renders for exactly this mistake.
+    expect(
+      resolvePlacements(topology, '/home', 'dev').map(item => item.state),
+    ).toEqual(['active', 'active'])
+  })
+})