@bespokeagentics/microdots-host 0.1.0

package/src/wire.test.ts

@@ -0,0 +1,631 @@
+import { Option, Schema as S } from 'effect'
+import { readFileSync } from 'node:fs'
+import { describe, expect, test } from 'vitest'
+
+import type {
+  ManifestAttribute,
+  ManifestEvent,
+  ManifestTag,
+} from '@bespokeagentics/microdots-element'
+
+import type { RouteDefinition, RouteTable } from './routes.ts'
+import {
+  HostTopology,
+  TopologyPlacement,
+  type Wire,
+  deriveWireState,
+  topologyRouteTable,
+} from './wire.ts'
+
+/* ============================================================
+   Synthetic manifest + table builders. Everything below is deliberately
+   minimal: one source tag with one event, one target tag with one
+   attribute, and just enough route table to place them.
+   ============================================================ */
+
+const attribute = (
+  name: string,
+  type: ManifestAttribute['type'],
+  values?: ReadonlyArray<string>,
+): ManifestAttribute => ({
+  name,
+  type,
+  required: false,
+  live: true,
+  ownership: 'dot',
+  ...(values === undefined ? {} : { values }),
+})
+
+/**
+ * `properties` mirrors the emitter's draft-2020-12 document shape —
+ * `{schema: {properties}}` — because that is what `deriveWireState` reads.
+ * Omitting it produces an event with no `jsonSchema`, the emitter's
+ * "could not render" case.
+ */
+const manifestEvent = (
+  name: string,
+  properties?: Readonly<Record<string, unknown>>,
+): ManifestEvent => ({
+  name,
+  payload: {
+    ref: `@microdots/test/contract#${name}`,
+    ...(properties === undefined
+      ? {}
+      : {
+          jsonSchema: {
+            dialect: 'draft-2020-12',
+            schema: { type: 'object', properties },
+            definitions: {},
+          },
+        }),
+  },
+})
+
+const sourceTag = (event: ManifestEvent): ManifestTag => ({
+  tag: 'price-ticker',
+  attributes: [],
+  events: [event],
+})
+
+const targetTag = (spec: ManifestAttribute): ManifestTag => ({
+  tag: 'fleet-health',
+  attributes: [spec],
+  events: [],
+})
+
+const route = (path: string, tags: ReadonlyArray<string>): RouteDefinition => ({
+  path,
+  label: path,
+  title: path,
+  sectionIds: tags.map(tag => `${tag}-section`),
+  mounts: tags.map(tag => ({ tag, slotId: `${tag}-slot` })),
+})
+
+const tableOf = (
+  first: RouteDefinition,
+  ...rest: ReadonlyArray<RouteDefinition>
+): RouteTable => ({ routes: [first, ...rest], fallback: first })
+
+/** Both ends on one route: the placement half of `live`. */
+const SHARED_TABLE = tableOf(route('/all', ['price-ticker', 'fleet-health']))
+
+/** Both ends placed, but never together. */
+const SPLIT_TABLE = tableOf(
+  route('/price', ['price-ticker']),
+  route('/fleet', ['fleet-health']),
+)
+
+const STRING_MANIFESTS: ReadonlyArray<ManifestTag> = [
+  sourceTag(manifestEvent('quote-changed', { symbol: { type: 'string' } })),
+  targetTag(attribute('region', 'string')),
+]
+
+const directWire: Wire = {
+  id: 'w1',
+  from: 'price-ticker',
+  event: 'quote-changed',
+  field: 'symbol',
+  fieldType: 'string',
+  to: 'fleet-health',
+  input: 'region',
+  inputType: 'string',
+  transform: { _tag: 'direct' },
+  envs: ['dev'],
+  plain: 'When the quote changes, set the region to its symbol.',
+}
+
+// The failure mode: a wire whose state is wrong is either a red herring on
+// the Wiring screen (live shown as draft) or a silently dead broker (draft
+// shown as live) — and the whole point of DERIVING state is that these tests
+// pin the derivation, not a stored copy that rots.
+describe('deriveWireState', () => {
+  test('derives live when types match and a route mounts both ends', () => {
+    expect(
+      deriveWireState(directWire, {
+        manifests: STRING_MANIFESTS,
+        table: SHARED_TABLE,
+      }),
+    ).toBe('live')
+  })
+
+  test('derives never-fires when no single route mounts both ends', () => {
+    expect(
+      deriveWireState(directWire, {
+        manifests: STRING_MANIFESTS,
+        table: SPLIT_TABLE,
+      }),
+    ).toBe('never-fires')
+  })
+
+  test('derives draft when a direct wire pairs mismatched types', () => {
+    const mismatched: Wire = { ...directWire, fieldType: 'number' }
+    const manifests: ReadonlyArray<ManifestTag> = [
+      sourceTag(manifestEvent('quote-changed', { symbol: { type: 'number' } })),
+      targetTag(attribute('region', 'string')),
+    ]
+    expect(
+      deriveWireState(mismatched, { manifests, table: SHARED_TABLE }),
+    ).toBe('draft')
+  })
+
+  test('derives draft when the declared inputType disagrees with the target attribute type', () => {
+    // fieldType === inputType, so the transform reconciles — ONLY the
+    // target-type conjunct can catch this wire writing a string into a
+    // number-typed attribute.
+    const manifests: ReadonlyArray<ManifestTag> = [
+      sourceTag(manifestEvent('quote-changed', { symbol: { type: 'string' } })),
+      targetTag(attribute('region', 'number')),
+    ]
+    expect(
+      deriveWireState(directWire, { manifests, table: SHARED_TABLE }),
+    ).toBe('draft')
+  })
+
+  test('derives draft when the declared fieldType contradicts the payload schema type', () => {
+    // Both declarations agree with each other AND with the target — the
+    // payload schema is the only witness that `symbol` is not a number.
+    const mistyped: Wire = {
+      ...directWire,
+      fieldType: 'number',
+      inputType: 'number',
+    }
+    const manifests: ReadonlyArray<ManifestTag> = [
+      sourceTag(manifestEvent('quote-changed', { symbol: { type: 'string' } })),
+      targetTag(attribute('region', 'number')),
+    ]
+    expect(deriveWireState(mistyped, { manifests, table: SHARED_TABLE })).toBe(
+      'draft',
+    )
+  })
+
+  test('derives draft when the source tag has no manifest', () => {
+    expect(
+      deriveWireState(directWire, {
+        manifests: [targetTag(attribute('region', 'string'))],
+        table: SHARED_TABLE,
+      }),
+    ).toBe('draft')
+  })
+
+  test('derives draft when the event is missing from the source manifest', () => {
+    const manifests: ReadonlyArray<ManifestTag> = [
+      sourceTag(
+        manifestEvent('status-changed', { region: { type: 'string' } }),
+      ),
+      targetTag(attribute('region', 'string')),
+    ]
+    expect(
+      deriveWireState(directWire, { manifests, table: SHARED_TABLE }),
+    ).toBe('draft')
+  })
+
+  test("derives draft when the field is missing from the event's payload schema", () => {
+    const manifests: ReadonlyArray<ManifestTag> = [
+      sourceTag(manifestEvent('quote-changed', { cents: { type: 'number' } })),
+      targetTag(attribute('region', 'string')),
+    ]
+    expect(
+      deriveWireState(directWire, { manifests, table: SHARED_TABLE }),
+    ).toBe('draft')
+  })
+
+  test('trusts the declared fieldType when the event carries no jsonSchema', () => {
+    // The emitter omits jsonSchema when it cannot render a payload schema —
+    // `ref` alone is still the contract, so the wire's own declaration stands.
+    const manifests: ReadonlyArray<ManifestTag> = [
+      sourceTag(manifestEvent('quote-changed')),
+      targetTag(attribute('region', 'string')),
+    ]
+    expect(
+      deriveWireState(directWire, { manifests, table: SHARED_TABLE }),
+    ).toBe('live')
+  })
+
+  test('derives draft when the target input is missing from the manifest', () => {
+    const manifests: ReadonlyArray<ManifestTag> = [
+      sourceTag(manifestEvent('quote-changed', { symbol: { type: 'string' } })),
+      targetTag(attribute('zone', 'string')),
+    ]
+    expect(
+      deriveWireState(directWire, { manifests, table: SHARED_TABLE }),
+    ).toBe('draft')
+  })
+
+  test("derives draft when a condition's gate field is missing from the payload", () => {
+    const conditioned: Wire = {
+      ...directWire,
+      transform: {
+        _tag: 'condition',
+        field: 'linked',
+        op: 'is',
+        value: 'true',
+      },
+    }
+    expect(
+      deriveWireState(conditioned, {
+        manifests: STRING_MANIFESTS,
+        table: SHARED_TABLE,
+      }),
+    ).toBe('draft')
+  })
+
+  /**
+   * The emitter's REAL rendering of `S.Number` (verified against
+   * `SchemaRepresentation.toJsonSchemaDocument` at effect 4.0.0-rc.108): the
+   * extra branches are literal string encodings of NaN/Infinity, and each
+   * carries an `enum` key. A checker that counted their `type` would let
+   * 'string' corroborate every numeric field.
+   */
+  const EMITTER_NUMBER_ANYOF = {
+    anyOf: [
+      { type: 'number' },
+      { type: 'string', enum: ['NaN'] },
+      { type: 'string', enum: ['Infinity'] },
+      { type: 'string', enum: ['-Infinity'] },
+    ],
+  }
+
+  test('an anyOf-rendered number property corroborates a number declaration', () => {
+    const numberWire: Wire = {
+      ...directWire,
+      field: 'cents',
+      fieldType: 'number',
+      inputType: 'number',
+    }
+    const manifests: ReadonlyArray<ManifestTag> = [
+      sourceTag(
+        manifestEvent('quote-changed', { cents: EMITTER_NUMBER_ANYOF }),
+      ),
+      targetTag(attribute('region', 'number')),
+    ]
+    expect(
+      deriveWireState(numberWire, { manifests, table: SHARED_TABLE }),
+    ).toBe('live')
+  })
+
+  test('a string declaration on an anyOf-rendered number field derives draft', () => {
+    // The NaN/Infinity branches are encoding artifacts, not evidence the
+    // field carries strings — counting them derives this wire live when
+    // `encodeFieldValue('string', 12345)` is None on every event: the
+    // silently dead broker the derivation exists to prevent.
+    const mistyped: Wire = { ...directWire, field: 'cents' }
+    const manifests: ReadonlyArray<ManifestTag> = [
+      sourceTag(
+        manifestEvent('quote-changed', { cents: EMITTER_NUMBER_ANYOF }),
+      ),
+      targetTag(attribute('region', 'string')),
+    ]
+    expect(deriveWireState(mistyped, { manifests, table: SHARED_TABLE })).toBe(
+      'draft',
+    )
+  })
+
+  test('a lookup into a string input reconciles a number source', () => {
+    const lookup: Wire = {
+      ...directWire,
+      field: 'cents',
+      fieldType: 'number',
+      transform: { _tag: 'lookup', rows: { '100': 'cheap' }, fallback: 'dear' },
+    }
+    const manifests: ReadonlyArray<ManifestTag> = [
+      sourceTag(manifestEvent('quote-changed', { cents: { type: 'number' } })),
+      targetTag(attribute('region', 'string')),
+    ]
+    expect(deriveWireState(lookup, { manifests, table: SHARED_TABLE })).toBe(
+      'live',
+    )
+  })
+
+  test('a lookup into an enum input is live iff every row value and the fallback are declared members', () => {
+    const enumTarget = targetTag(
+      attribute('region', 'enum', ['us-east', 'eu-west', 'ap-south-1']),
+    )
+    const manifests: ReadonlyArray<ManifestTag> = [
+      sourceTag(manifestEvent('quote-changed', { symbol: { type: 'string' } })),
+      enumTarget,
+    ]
+    const lookup: Wire = {
+      ...directWire,
+      inputType: 'enum',
+      transform: {
+        _tag: 'lookup',
+        rows: { FOLD: 'us-east', EFCT: 'eu-west' },
+        fallback: 'us-east',
+      },
+    }
+    expect(deriveWireState(lookup, { manifests, table: SHARED_TABLE })).toBe(
+      'live',
+    )
+
+    const escapee: Wire = {
+      ...lookup,
+      transform: {
+        _tag: 'lookup',
+        rows: { FOLD: 'us-east', EFCT: 'mars' },
+        fallback: 'us-east',
+      },
+    }
+    expect(deriveWireState(escapee, { manifests, table: SHARED_TABLE })).toBe(
+      'draft',
+    )
+  })
+})
+
+/* ============================================================
+   topologyRouteTable
+   ============================================================ */
+
+const PRICE_ROUTE = route('/price', ['price-ticker'])
+const FLEET_ROUTE = route('/fleet', ['fleet-health'])
+
+const topologyWith = (overview: HostTopology['overview']): HostTopology => ({
+  host: { id: 'demo-host', label: 'Demo host', ownedInputs: [] },
+  routes: [PRICE_ROUTE, FLEET_ROUTE],
+  ...(overview === undefined ? {} : { overview }),
+  wires: [],
+  watch: [],
+})
+
+// The failure mode: two consumers (a host entry, the Wiring dot) building
+// their tables differently would make the SAME wire derive live in one place
+// and never-fires in the other. One helper, one derivation.
+describe('topologyRouteTable', () => {
+  test('derives an aggregate overview fallback when the descriptor is present', () => {
+    const table = topologyRouteTable(
+      topologyWith({
+        path: '/',
+        label: 'Overview',
+        title: 'Everything',
+        leadingSectionIds: ['intro-section'],
+      }),
+    )
+
+    expect(table.fallback.path).toBe('/')
+    expect(table.fallback.sectionIds).toEqual([
+      'intro-section',
+      'price-ticker-section',
+      'fleet-health-section',
+    ])
+    expect(table.fallback.mounts.map(mount => mount.tag)).toEqual([
+      'price-ticker',
+      'fleet-health',
+    ])
+    // The derived overview leads the table, so `/` wins route matching.
+    expect(table.routes.map(entry => entry.path)).toEqual([
+      '/',
+      '/price',
+      '/fleet',
+    ])
+  })
+
+  test('falls back to the first route when there is no overview', () => {
+    const table = topologyRouteTable(topologyWith(undefined))
+
+    expect(table.fallback).toEqual(PRICE_ROUTE)
+    expect(table.routes.map(entry => entry.path)).toEqual(['/price', '/fleet'])
+  })
+
+  // The failure mode this Phase-5 fold prevents: the platform's workbench
+  // mounts moved into ONE group rule, so without the fold every table-derived
+  // join goes blind to them at once — `unroutedTags` throws at startup for
+  // tags the runtime does mount, and a wire whose two ends ride the rule
+  // derives `never-fires` on the Wiring screen while the broker fires it.
+  test('folds rule-carried placements into every matching route, ahead of its own mounts', () => {
+    const table = topologyRouteTable({
+      ...topologyWith(undefined),
+      rules: [
+        {
+          id: 'ticker-pages',
+          kind: 'group',
+          label: 'Ticker pages',
+          paths: ['/price', '/fleet'],
+          placements: [{ tag: 'promo-banner', slotId: 'hero-slot' }],
+        },
+      ],
+    })
+
+    table.routes.forEach(entry => {
+      expect(entry.mounts.map(mount => mount.tag)[0]).toBe('promo-banner')
+    })
+    // The fallback is a route too — a rule-carried tag must be findable there.
+    expect(table.fallback.mounts.map(mount => mount.tag)).toEqual([
+      'promo-banner',
+      'price-ticker',
+    ])
+  })
+
+  test('a wire whose two ends only share rule-carried mounts still derives live', () => {
+    const table = topologyRouteTable({
+      ...topologyWith(undefined),
+      rules: [
+        {
+          id: 'both-ends',
+          kind: 'pattern',
+          label: 'Everywhere',
+          pattern: '/*',
+          placements: [
+            { tag: 'price-ticker', slotId: 'price-ticker-slot' },
+            { tag: 'fleet-health', slotId: 'fleet-health-slot' },
+          ],
+        },
+      ],
+      routes: [
+        { ...PRICE_ROUTE, mounts: [] },
+        { ...FLEET_ROUTE, mounts: [] },
+      ],
+    })
+
+    expect(
+      deriveWireState(directWire, { manifests: STRING_MANIFESTS, table }),
+    ).toBe('live')
+  })
+
+  test('a rule that matches no route changes nothing', () => {
+    const table = topologyRouteTable({
+      ...topologyWith(undefined),
+      rules: [
+        {
+          id: 'docs',
+          kind: 'dynamic',
+          label: 'Doc pages',
+          template: '/docs/:slug',
+          placements: [{ tag: 'promo-banner', slotId: 'hero-slot' }],
+        },
+      ],
+    })
+
+    expect(table.routes).toEqual([PRICE_ROUTE, FLEET_ROUTE])
+  })
+})
+
+/* ============================================================
+   HostTopology — the schema at its boundary. The stated purpose of these
+   schemas is decoding `host-topology.json`, so a JSON round-trip is the
+   fixture, exactly as a host's entry will feed it.
+   ============================================================ */
+
+const decodeTopology = S.decodeUnknownOption(HostTopology)
+
+const RAW_TOPOLOGY = {
+  host: {
+    id: 'demo-host',
+    label: 'Demo host',
+    ownedInputs: [{ name: 'activity log', type: 'append' }],
+  },
+  routes: [PRICE_ROUTE, FLEET_ROUTE],
+  overview: { path: '/', label: 'Overview', title: 'Everything' },
+  wires: [directWire],
+  watch: [{ event: 'quote-changed' }],
+}
+
+// The failure mode: a topology file the schema silently mangles or loosely
+// admits — `routes` non-empty is load-bearing for `topologyRouteTable`'s
+// assertion-free `routes[0]`, so an empty-routes document MUST be rejected
+// at the decode, not discovered as undefined downstream.
+describe('HostTopology', () => {
+  test('decodes a host-topology.json shaped document', () => {
+    const parsed: unknown = JSON.parse(JSON.stringify(RAW_TOPOLOGY))
+    const decoded = decodeTopology(parsed)
+
+    expect(
+      Option.map(
+        decoded,
+        topology => topologyRouteTable(topology).fallback.path,
+      ),
+    ).toEqual(Option.some('/'))
+    expect(Option.map(decoded, topology => topology.wires)).toEqual(
+      Option.some([directWire]),
+    )
+  })
+
+  test('rejects a document whose routes are empty', () => {
+    const parsed: unknown = JSON.parse(
+      JSON.stringify({ ...RAW_TOPOLOGY, routes: [] }),
+    )
+    expect(Option.isNone(decodeTopology(parsed))).toBe(true)
+  })
+})
+
+/* ============================================================
+   Phase 5 — the widened placement, rules, and the REAL topology files.
+   Work items 1–3 of microdots-platform-phase-5-pages-design.md; the
+   backward-compat pin is the phase's hard requirement.
+   ============================================================ */
+
+/** The shipped files themselves, from disk — not a copy that would keep
+ *  passing after the real file breaks. */
+const topologyOnDisk = (relativePath: string): unknown =>
+  JSON.parse(readFileSync(new URL(relativePath, import.meta.url), 'utf8'))
+
+// The failure mode: the Phase-5 widening is only admissible because BOTH
+// shipped host-topology.json files decode unchanged — a new field declared
+// `optional` instead of `optionalKey`, or one that injects a default at
+// decode, would change what every host mounts without either file being
+// touched. `toEqual(Option.some(parsed))` pins the decode as the identity.
+describe('the shipped host-topology.json files', () => {
+  test('the demo host topology still decodes, unchanged', () => {
+    const parsed = topologyOnDisk('../../../apps/host/host-topology.json')
+    expect(decodeTopology(parsed)).toEqual(Option.some(parsed))
+  })
+
+  test('the platform topology still decodes, unchanged', () => {
+    const parsed = topologyOnDisk('../../../apps/platform/host-topology.json')
+    expect(decodeTopology(parsed)).toEqual(Option.some(parsed))
+  })
+})
+
+const decodePlacement = S.decodeUnknownOption(TopologyPlacement)
+const encodePlacement = S.encodeSync(TopologyPlacement)
+
+/** Every Phase-5 field at once: id, values, condition, envs, span, order. */
+const WIDENED_PLACEMENT = {
+  id: 'promo-hero',
+  tag: 'promo-banner',
+  slotId: 'hero-slot',
+  values: { variant: 'spring' },
+  condition: { who: 'visitor', locale: 'fr' },
+  envs: ['dev', 'preview'],
+  span: 8,
+  order: 2,
+}
+
+// The failure mode: the Pages screen's write mode will eventually save these
+// records back to host-topology.json — a field that decodes but encodes
+// lossily (a dropped optional, an injected default) corrupts a topology file
+// on first save. And `span` outside 12/8/6/4/3 must die at the decode, not
+// render as a broken grid.
+describe('TopologyPlacement — the Phase-5 widening', () => {
+  test('a fully widened placement round-trips decode → encode byte-identically', () => {
+    const parsed: unknown = JSON.parse(JSON.stringify(WIDENED_PLACEMENT))
+    expect(Option.map(decodePlacement(parsed), encodePlacement)).toEqual(
+      Option.some(parsed),
+    )
+  })
+
+  test('rejects a span outside the literal set', () => {
+    const parsed: unknown = JSON.parse(
+      JSON.stringify({ ...WIDENED_PLACEMENT, span: 5 }),
+    )
+    expect(Option.isNone(decodePlacement(parsed))).toBe(true)
+  })
+})
+
+// The failure mode: `rules` and `slotManifest` are the Phase-5 keys the
+// Pages screen and the resolution read — a topology carrying all three rule
+// kinds that fails to decode is a platform host that never starts.
+describe('HostTopology — the Phase-5 keys', () => {
+  test('decodes a topology carrying rules and a slot manifest, unchanged', () => {
+    const raw = {
+      ...RAW_TOPOLOGY,
+      slotManifest: {
+        theme: { name: '@bespokeagentics/microdots-theme', version: '1.4.0' },
+        slots: [{ id: 'hero-slot', kind: 'band', row: 0 }],
+      },
+      rules: [
+        {
+          id: 'r1',
+          kind: 'pattern',
+          label: 'Everywhere',
+          pattern: '/*',
+          placements: [{ tag: 'promo-banner', slotId: 'hero-slot' }],
+        },
+        {
+          id: 'r2',
+          kind: 'group',
+          label: 'Workbench pages',
+          paths: ['/apps', '/builds', '/deploys'],
+          placements: [WIDENED_PLACEMENT],
+        },
+        {
+          id: 'r3',
+          kind: 'dynamic',
+          label: 'Doc pages',
+          template: '/docs/:slug',
+          placements: [],
+        },
+      ],
+    }
+    const parsed: unknown = JSON.parse(JSON.stringify(raw))
+    expect(decodeTopology(parsed)).toEqual(Option.some(parsed))
+  })
+})