@bespokeagentics/microdots-host 0.1.0

package/src/rules.ts

@@ -0,0 +1,448 @@
+import { Array, Option } from 'effect'
+
+import type {
+  HostTopology,
+  PlacementCondition,
+  PlacementSpan,
+  RouteRule,
+  TopologyPlacement,
+  WireEnv,
+} from './wire.ts'
+
+/**
+ * Rules, THE matcher, and the reading-B resolution — Phase 5 work item 3 of
+ * `wiki/plans/shipped/microdots-platform-phase-5-pages-design.md`.
+ *
+ * The `RouteRule` record itself is schema and lives with the other topology
+ * records in `./wire.ts`; this module is the behaviour: `ruleMatches` (the one
+ * matcher, ruling 1 — the runtime and the Pages screen's match counts both
+ * call it, nothing else may reimplement it) and `resolvePlacements` (the
+ * reading-B override resolution of
+ * `wiki/framework/composition/question-does-the-override-contest-consider-condition.md`).
+ *
+ * Everything here derives fresh from the topology — nothing below is ever
+ * stored, for the same reason `deriveWireState` stores nothing: a stored
+ * resolution is stale the moment a rule or a placement changes without it
+ * being touched.
+ */
+
+/* ============================================================
+   The matcher.
+   ============================================================ */
+
+/** `'/docs/rpc-contracts'` → `['docs', 'rpc-contracts']`; `'/'` → `[]`. */
+const segmentsOf = (path: string): ReadonlyArray<string> =>
+  path.split('/').filter(segment => segment !== '')
+
+/**
+ * Pattern semantics, pinned: only the `/*` SUFFIX wildcard exists. Stripping
+ * it leaves a prefix, and the path matches when it continues past that prefix
+ * through a `/` — so `/blog/*` matches `/blog/effect-first-ports` and
+ * `/blog/a/b` but NOT `/blog` itself, and `/*` (empty prefix) matches every
+ * normalized path. A pattern without the suffix is an exact match.
+ */
+const patternMatches = (pattern: string, path: string): boolean => {
+  if (pattern.endsWith('/*')) {
+    const prefix = pattern.slice(0, -2)
+    return path.startsWith(`${prefix}/`)
+  }
+  return pattern === path
+}
+
+/**
+ * Dynamic semantics, pinned: segment-wise, equal length. A `:param` segment
+ * matches exactly ONE segment — `/docs/:slug` matches `/docs/anything` but
+ * not `/docs` and not `/docs/a/b`; a template wanting two segments says so
+ * (`/docs/:a/:b`). Literal segments match exactly.
+ */
+const templateMatches = (template: string, path: string): boolean => {
+  const templateSegments = segmentsOf(template)
+  const pathSegments = segmentsOf(path)
+  if (templateSegments.length !== pathSegments.length) {
+    return false
+  }
+  return Array.every(
+    Array.zip(templateSegments, pathSegments),
+    ([templateSegment, pathSegment]) =>
+      templateSegment.startsWith(':') || templateSegment === pathSegment,
+  )
+}
+
+/**
+ * THE matcher (ruling 1). Serves all three rule kinds; used by the runtime
+ * resolution below AND by the Pages screen's per-rule match counts, so the
+ * screen cannot claim a count the runtime disagrees with.
+ */
+export const ruleMatches = (rule: RouteRule, path: string): boolean => {
+  switch (rule.kind) {
+    case 'pattern':
+      return patternMatches(rule.pattern, path)
+    case 'group':
+      return Array.contains(rule.paths, path)
+    case 'dynamic':
+      return templateMatches(rule.template, path)
+  }
+}
+
+/* ============================================================
+   Conditions — the overlap algebra the resolution and the checks share.
+   ============================================================ */
+
+/**
+ * A condition with every axis explicit — the derived counterpart of the
+ * record's `PlacementCondition`, where an absent axis means `'any'`. Derived
+ * at resolution time rather than stored, so a record only ever says what
+ * narrows.
+ */
+export type ResolvedCondition = {
+  readonly who: string
+  readonly device: string
+  readonly locale: string
+}
+
+export const resolveCondition = (
+  condition: PlacementCondition | undefined,
+): ResolvedCondition => ({
+  who: condition?.who ?? 'any',
+  device: condition?.device ?? 'any',
+  locale: condition?.locale ?? 'any',
+})
+
+/** One axis overlaps when either side is `'any'` or they are equal — the
+ *  fixture's `axisOk`, verbatim. */
+const axisOverlaps = (a: string, b: string): boolean =>
+  a === 'any' || b === 'any' || a === b
+
+/** Conditions overlap when ALL three axes do — the fixture's `overlaps`. */
+export const conditionsOverlap = (
+  a: ResolvedCondition,
+  b: ResolvedCondition,
+): boolean =>
+  axisOverlaps(a.who, b.who) &&
+  axisOverlaps(a.device, b.device) &&
+  axisOverlaps(a.locale, b.locale)
+
+/** The narrower of two overlapping axes. Only meaningful when the axes
+ *  overlap — `'any'` yields the other side, equals yield themselves. */
+const axisIntersection = (a: string, b: string): string => (a === 'any' ? b : a)
+
+/** The region two OVERLAPPING conditions share — what an override badge
+ *  names ("overridden for fr"), per reading B's requirement that the loser's
+ *  badge says which visitors it lost. */
+export const conditionIntersection = (
+  a: ResolvedCondition,
+  b: ResolvedCondition,
+): ResolvedCondition => ({
+  who: axisIntersection(a.who, b.who),
+  device: axisIntersection(a.device, b.device),
+  locale: axisIntersection(a.locale, b.locale),
+})
+
+/** Whether `winner` covers ALL of `loser` — `'any'` or equal on every axis.
+ *  Covered entirely means the loser renders for nobody. */
+const conditionCovers = (
+  winner: ResolvedCondition,
+  loser: ResolvedCondition,
+): boolean =>
+  (winner.who === 'any' || winner.who === loser.who) &&
+  (winner.device === 'any' || winner.device === loser.device) &&
+  (winner.locale === 'any' || winner.locale === loser.locale)
+
+/** The non-`'any'` axes joined for a badge or a sentence — the fixture's
+ *  `condLabel`, generalised to free axis values. `'everyone'` when nothing
+ *  narrows. */
+export const conditionLabel = (condition: ResolvedCondition): string => {
+  const parts = Array.filter(
+    [condition.who, condition.device, condition.locale],
+    axis => axis !== 'any',
+  )
+  return parts.length === 0 ? 'everyone' : parts.join(' · ')
+}
+
+/* ============================================================
+   The reading-B resolution.
+   ============================================================ */
+
+/**
+ * Where a resolved placement was declared. `rule` carries the label alongside
+ * the id so a badge or a check sentence can name the rule the way a human
+ * does ("from Product pages") without a join back into the topology — never
+ * show a storage key where a human expects a name.
+ */
+export type PlacementSource =
+  | { readonly _tag: 'route' }
+  | { readonly _tag: 'rule'; readonly ruleId: string; readonly label: string }
+
+/**
+ * One override this placement lost: who beat it, and WHERE. `where` is the
+ * overlap of the two conditions — under reading B the winner only takes that
+ * region, so the badge names it ("overridden for fr") rather than claiming
+ * the whole placement. `entire` is true when the overlap covers this
+ * placement's whole condition — it renders for nobody.
+ */
+export type PlacementOverride = {
+  readonly by: PlacementSource
+  readonly winnerId: string
+  readonly where: ResolvedCondition
+  readonly entire: boolean
+}
+
+/**
+ * - `active`                — renders wherever its condition holds.
+ * - `partially-overridden`  — a later layer took part of its region; it still
+ *                             renders for everybody outside the overlap, so
+ *                             the checks still check it.
+ * - `overridden`            — some later placement covers its whole region;
+ *                             it renders for nobody and raises no issues.
+ */
+export type ResolvedState = 'active' | 'partially-overridden' | 'overridden'
+
+/**
+ * One placement as the RESOLUTION sees it: record defaults made explicit
+ * (condition axes to `'any'`, `envs` to all three, `values` to `{}`),
+ * provenance attached, override state decided. The losers of an override stay
+ * in this list — the screen renders them struck-through, not deleted — which
+ * is why `state` exists instead of the losers being filtered out.
+ *
+ * `id` is UNIQUE within one resolution and stable across re-resolutions of the
+ * same topology — the Pages screen selects by it across polls and env
+ * switches, `overriddenBy.winnerId` matches on it, and every check issue is
+ * routed to a placement by it, so a shared id is simultaneously two cards
+ * highlighted for one selection, one inspector merging two placements' issues,
+ * and a check-4 warning silently suppressed (`overridePair` matches
+ * `winnerId === other.id`).
+ *
+ * It is the declared id when the record has one AND that id is declared
+ * exactly once in this resolution; otherwise it is (or is qualified by) a
+ * synthesized fallback — `/price|0|route:price-ticker@main-slot#0`: route
+ * path, layer, source key, tag, slot, index within its layer. See
+ * `resolvedIdOf` for the collision rule.
+ */
+export type ResolvedPlacement = {
+  readonly id: string
+  readonly tag: string
+  readonly slotId: string
+  readonly source: PlacementSource
+  readonly condition: ResolvedCondition
+  readonly envs: ReadonlyArray<WireEnv>
+  readonly values: Readonly<Record<string, string>>
+  readonly span: Option.Option<PlacementSpan>
+  readonly order: Option.Option<number>
+  readonly state: ResolvedState
+  readonly overriddenBy: ReadonlyArray<PlacementOverride>
+}
+
+const ALL_ENVS: ReadonlyArray<WireEnv> = ['dev', 'preview', 'prod']
+
+/** A placement mid-resolution: flattened out of its layer, defaults applied,
+ *  id not yet settled, contest not yet run. */
+type LayeredPlacement = {
+  readonly layer: number
+  /** The record's own `id`, or `undefined` for a Phase-4 record without one. */
+  readonly declaredId: string | undefined
+  /** The synthesized key — unique within a resolution BY CONSTRUCTION, see
+   *  `fallbackId`. */
+  readonly fallbackId: string
+  readonly source: PlacementSource
+  readonly condition: ResolvedCondition
+  readonly placement: TopologyPlacement
+}
+
+/** …with its id settled against the whole layered set. */
+type IdentifiedPlacement = LayeredPlacement & { readonly id: string }
+
+const sourceKey = (source: PlacementSource): string =>
+  source._tag === 'route' ? 'route' : source.ruleId
+
+/**
+ * The synthesized key, unique within one resolution by construction.
+ *
+ * `layer` is what makes that a proof rather than a hope: layers are numbered
+ * 0…n over the MATCHING rules in declared order with the route's own layer
+ * last, so `(layer, index)` addresses exactly one placement — which is why the
+ * layer number is here even though `sourceKey` reads better. Without it a rule
+ * whose id is literally `"route"`, or two rules sharing an id, synthesize the
+ * route layer's keys verbatim.
+ *
+ * `path` is what makes it unique ACROSS routes, which the demo host's derived
+ * overview needs: that route resolves as the union of every component route's
+ * resolution, and a rule placement matching all six of them would otherwise
+ * carry one id six times.
+ *
+ * `index` is within the UNFILTERED layer, so a placement's id does not move
+ * when the env filter drops a sibling — the Pages screen keeps its selection
+ * across an env switch.
+ */
+const fallbackId = (
+  path: string,
+  layer: number,
+  source: PlacementSource,
+  placement: TopologyPlacement,
+  index: number,
+): string =>
+  `${path}|${layer}|${sourceKey(source)}:${placement.tag}@${placement.slotId}#${index}`
+
+const layerPlacements = (
+  path: string,
+  layer: number,
+  source: PlacementSource,
+  placements: ReadonlyArray<TopologyPlacement>,
+): ReadonlyArray<LayeredPlacement> =>
+  placements.map((placement, index) => ({
+    layer,
+    declaredId: placement.id,
+    fallbackId: fallbackId(path, layer, source, placement, index),
+    source,
+    condition: resolveCondition(placement.condition),
+    placement,
+  }))
+
+/** How many times each DECLARED id appears across the whole layered set —
+ *  computed before the env filter so the collision verdict, and therefore the
+ *  id, does not change when the environment does. */
+const declaredIdCounts = (
+  items: ReadonlyArray<LayeredPlacement>,
+): ReadonlyMap<string, number> => {
+  const counts = new Map<string, number>()
+  items.forEach(item => {
+    if (item.declaredId !== undefined) {
+      counts.set(item.declaredId, (counts.get(item.declaredId) ?? 0) + 1)
+    }
+  })
+  return counts
+}
+
+/**
+ * The collision rule, chosen deliberately (2026-08-18 review finding 2):
+ * **duplicate declared ids are DISAMBIGUATED, symmetrically, not rejected and
+ * not first-wins.**
+ *
+ * - Rejecting an authoring typo would turn it into a blank page in both
+ *   shells' `activate` — this repo's signature failure mode — for a mistake
+ *   that has a perfectly good rendering.
+ * - A check reporting the duplicate would still hand every consumer the
+ *   colliding ids; the contest's `winnerId` matching and the checks' own
+ *   issue routing would stay wrong, and the shells never run the checks.
+ * - First-wins would let one of the pair keep the declared id, which reads as
+ *   authoritative and hides that a second placement is masquerading as it.
+ *
+ * So BOTH members of a collision are qualified with their synthesized key.
+ * The result is deterministic in the topology alone: re-resolving the same
+ * topology yields the same ids, so the screen's selection survives the poll.
+ */
+const resolvedIdOf = (
+  item: LayeredPlacement,
+  counts: ReadonlyMap<string, number>,
+): string => {
+  if (item.declaredId === undefined) {
+    return item.fallbackId
+  }
+  return (counts.get(item.declaredId) ?? 0) > 1
+    ? `${item.declaredId}~${item.fallbackId}`
+    : item.declaredId
+}
+
+/**
+ * The reading-B resolution — the function
+ * `wiki/framework/composition/question-does-the-override-contest-consider-condition.md`
+ * describes, pinned:
+ *
+ * 1. Layers broadest-first: every matching rule in DECLARED order, then the
+ *    route's own placements last. A topology with no `rules` key resolves to
+ *    exactly its route mounts — the identity, byte-identical to Phase 4.
+ * 2. A placement is filtered out when its `envs` (default all three) exclude
+ *    `env` — a placement that does not exist in this environment cannot
+ *    render here and cannot override anything here either.
+ * 3. The contest: a placement in a strictly LATER layer with the same
+ *    `(tag, slotId)` whose condition overlaps an earlier one overrides it —
+ *    but only WHERE they overlap. The loser survives where not overlapped
+ *    (`partially-overridden`), and is `overridden` only when some winner
+ *    covers its whole condition. Two placements in the SAME layer never
+ *    override each other — they are peers at one specificity, and colliding
+ *    peers are the checks' business (checks 4/7), not the contest's.
+ * 4. Losers are KEPT in the output with provenance and `overriddenBy` — the
+ *    spec renders them struck-through with a badge naming the condition, not
+ *    deleted.
+ */
+export const resolvePlacements = (
+  topology: HostTopology,
+  path: string,
+  env: WireEnv,
+): ReadonlyArray<ResolvedPlacement> => {
+  const matchingRules = Array.filter(topology.rules ?? [], rule =>
+    ruleMatches(rule, path),
+  )
+  const routeMounts = Option.match(
+    Array.findFirst(topology.routes, route => route.path === path),
+    {
+      onNone: (): ReadonlyArray<TopologyPlacement> => [],
+      onSome: route => route.mounts,
+    },
+  )
+
+  const ruleLayers = matchingRules.map((rule, index) =>
+    layerPlacements(
+      path,
+      index,
+      { _tag: 'rule', ruleId: rule.id, label: rule.label },
+      rule.placements,
+    ),
+  )
+  const routeLayer = layerPlacements(
+    path,
+    matchingRules.length,
+    { _tag: 'route' },
+    routeMounts,
+  )
+
+  // Ids settle over the WHOLE layered set, before the env filter — see
+  // `declaredIdCounts`. Every downstream reference (`winnerId`, the checks'
+  // `placementId`, the screen's selection) then names exactly one placement.
+  const all = [...Array.flatten(ruleLayers), ...routeLayer]
+  const counts = declaredIdCounts(all)
+  const layered: ReadonlyArray<IdentifiedPlacement> = Array.filter(
+    all.map(item => ({ ...item, id: resolvedIdOf(item, counts) })),
+    item => Array.contains(item.placement.envs ?? ALL_ENVS, env),
+  )
+
+  return layered.map(item => {
+    // `getSomes` over `map`, not `filterMap` — v4's `filterMap` wants a
+    // `Result` and silently drops `Option`s (the AGENTS.md trap).
+    const overriddenBy = Array.getSomes(
+      Array.map(layered, (other): Option.Option<PlacementOverride> =>
+        other.layer > item.layer &&
+        other.placement.tag === item.placement.tag &&
+        other.placement.slotId === item.placement.slotId &&
+        conditionsOverlap(other.condition, item.condition)
+          ? Option.some({
+              by: other.source,
+              winnerId: other.id,
+              where: conditionIntersection(other.condition, item.condition),
+              entire: conditionCovers(other.condition, item.condition),
+            })
+          : Option.none(),
+      ),
+    )
+    const state: ResolvedState = Array.some(
+      overriddenBy,
+      override => override.entire,
+    )
+      ? 'overridden'
+      : overriddenBy.length > 0
+        ? 'partially-overridden'
+        : 'active'
+    return {
+      id: item.id,
+      tag: item.placement.tag,
+      slotId: item.placement.slotId,
+      source: item.source,
+      condition: item.condition,
+      envs: item.placement.envs ?? ALL_ENVS,
+      values: item.placement.values ?? {},
+      span: Option.fromNullishOr(item.placement.span),
+      order: Option.fromNullishOr(item.placement.order),
+      state,
+      overriddenBy,
+    }
+  })
+}

package/src/slots.test.ts

@@ -0,0 +1,46 @@
+import { Option, Schema as S } from 'effect'
+import { describe, expect, test } from 'vitest'
+
+import { HostSlotManifest } from './slots.ts'
+
+const decodeManifest = S.decodeUnknownOption(HostSlotManifest)
+
+/**
+ * A real-shaped manifest, exercising every slot kind: the demo host's
+ * per-section `band`s, the platform's three `rail`s (fixed-width sidebar per
+ * `apps/platform/index.html`), a `bar`, and a `grid` — the grid kind is
+ * fixture-only per the design page ("no invented grid slots" on real hosts).
+ */
+const RAW_MANIFEST = {
+  theme: { name: '@bespokeagentics/microdots-theme', version: '1.4.0' },
+  slots: [
+    { id: 'top-bar', kind: 'bar', row: 0 },
+    { id: 'hero-band', kind: 'band', row: 1 },
+    { id: 'app-list-slot', kind: 'rail', row: 2, width: '280px' },
+    { id: 'main-grid', kind: 'grid', row: 2, capacity: 4 },
+  ],
+}
+
+// The failure mode: the slot manifest is what placement check 2 joins
+// `slotId` against — a manifest the schema silently mangles (a dropped
+// `width`, a defaulted `capacity`) or loosely admits (an invented kind) makes
+// check 2 lie in both directions: real slots reported missing, or misspelled
+// kinds laid out as something they are not.
+describe('HostSlotManifest', () => {
+  test('decodes a real-shaped manifest byte-identically', () => {
+    const parsed: unknown = JSON.parse(JSON.stringify(RAW_MANIFEST))
+    // `toEqual(Option.some(parsed))` pins that decoding neither drops the
+    // optional `width`/`capacity` keys nor invents defaults for them.
+    expect(decodeManifest(parsed)).toEqual(Option.some(parsed))
+  })
+
+  test('rejects a slot whose kind is not bar, band, rail or grid', () => {
+    const parsed: unknown = JSON.parse(
+      JSON.stringify({
+        theme: RAW_MANIFEST.theme,
+        slots: [{ id: 'top-ribbon', kind: 'ribbon', row: 0 }],
+      }),
+    )
+    expect(Option.isNone(decodeManifest(parsed))).toBe(true)
+  })
+})

package/src/slots.ts

@@ -0,0 +1,58 @@
+import { Schema as S } from 'effect'
+
+/**
+ * The host SLOT MANIFEST — a host declaring, as data, where MicroDots may go.
+ *
+ * Phase 5 makes placement data the way Phase 4 made wires data, and the slot
+ * manifest is the half the HOST owns: the theme's declared slots, versioned.
+ * It lives inside `host-topology.json` as `HostTopology.slotManifest` rather
+ * than in a second per-host file — the topology is already "a whole host, as
+ * data", and a second file would be a second thing to drift. See
+ * `wiki/plans/shipped/microdots-platform-phase-5-pages-design.md`
+ * work item 1.
+ *
+ * The `theme.version` is load-bearing: placement check 2's "valid under an
+ * earlier theme version" sentence cannot exist without a version to have been
+ * earlier than.
+ */
+
+/**
+ * What shape a slot is, which decides how placements lay out inside it:
+ *
+ * - `bar` / `band` — a full-width horizontal strip; placements stack, position
+ *   is `order`.
+ * - `rail`  — a fixed-width vertical column; placements stack full-width.
+ * - `grid`  — twelve columns; placements carry a `span` (12/8/6/4/3 of 12).
+ */
+export const SlotKind = S.Literals(['bar', 'band', 'rail', 'grid'])
+export type SlotKind = typeof SlotKind.Type
+
+/**
+ * One declared slot. `row` is the vertical band the slot occupies — slots
+ * sharing a row sit side by side (the fixture's sidebar / main / aside).
+ * `width` is a CSS length for a fixed `rail` (`'280px'`); `capacity` is how
+ * many placements the slot is meant to hold. Both `optionalKey` (not
+ * `optional`) so the decoded Type is exact-optional under
+ * `exactOptionalPropertyTypes`, matching the rest of the topology schemas.
+ */
+export const SlotSpec = S.Struct({
+  id: S.String,
+  kind: SlotKind,
+  row: S.Number,
+  width: S.optionalKey(S.String),
+  capacity: S.optionalKey(S.Number),
+})
+export type SlotSpec = typeof SlotSpec.Type
+
+/**
+ * The whole manifest: which theme (at which version) declared which slots.
+ * Placement check 2 joins `TopologyPlacement.slotId` against `slots[].id`; a
+ * topology WITHOUT a slot manifest predates this record, and the checks
+ * degrade honestly — slot checks are reported unverifiable, never silently
+ * green (see `./placementChecks.ts`).
+ */
+export const HostSlotManifest = S.Struct({
+  theme: S.Struct({ name: S.String, version: S.String }),
+  slots: S.Array(SlotSpec),
+})
+export type HostSlotManifest = typeof HostSlotManifest.Type