@bespokeagentics/microdots-host 0.1.0

package/src/wireEngine.test.ts

@@ -0,0 +1,810 @@
+import { Option } from 'effect'
+import { beforeEach, describe, expect, test, vi } from 'vitest'
+
+import type { Wire } from './wire.ts'
+import {
+  type WireEngine,
+  type WireEngineOptions,
+  type WireTrace,
+  applyTransform,
+  attachWireEngine,
+  planWires,
+} from './wireEngine.ts'
+
+/* ============================================================
+   The recorded demo-host wires — w1/w2/w3 exactly as
+   `apps/host/src/entry.ts` hand-wrote them before Phase 4.
+   ============================================================ */
+
+const w1: Wire = {
+  id: 'w1',
+  from: 'price-ticker',
+  event: 'quote-changed',
+  field: 'symbol',
+  fieldType: 'string',
+  to: 'fleet-health',
+  input: 'region',
+  inputType: 'string',
+  transform: {
+    _tag: 'lookup',
+    rows: { FOLD: 'us-east', EFCT: 'eu-west', ELMX: 'ap-south-1' },
+    fallback: 'us-east',
+  },
+  envs: ['dev', 'preview', 'prod'],
+  plain: 'When the quote changes, point the fleet at the symbol’s region.',
+}
+
+const w2: Wire = {
+  id: 'w2',
+  from: 'bespoke-contact-form',
+  event: 'submission-created',
+  field: 'id',
+  fieldType: 'string',
+  to: 'bespoke-contact-dashboard',
+  input: 'refresh-token',
+  inputType: 'string',
+  transform: { _tag: 'direct' },
+  envs: ['dev', 'preview', 'prod'],
+  plain: 'When a submission is stored, nudge the dashboard to reload.',
+}
+
+const w3: Wire = {
+  id: 'w3',
+  from: 'bespoke-contact-dashboard',
+  event: 'definition-changed',
+  field: 'version',
+  fieldType: 'number',
+  to: 'bespoke-contact-form',
+  input: 'definition-token',
+  inputType: 'number',
+  transform: { _tag: 'direct' },
+  envs: ['dev', 'preview', 'prod'],
+  plain: 'When the definition changes, nudge the form to refetch it.',
+}
+
+const DEMO_WIRES: ReadonlyArray<Wire> = [w1, w2, w3]
+
+/* ============================================================
+   The `host-changed` collision — pw12 and pg6/pg7, copied field-for-field
+   from `apps/platform/host-topology.json`. TWO dots emit `host-changed`
+   (`wiring-canvas` and `pages-rail`, `microdots/wiring/src/surface.ts:30` and
+   `microdots/pages/src/surface.ts:49`) with an identically shaped `{hostId}`
+   payload, and three panes across two screens expose a `host-id` attribute.
+   Both screens stay mounted — `activate` only toggles `section.hidden` — so
+   a name-only match crossed them.
+   ============================================================ */
+
+const pw12: Wire = {
+  id: 'pw12',
+  from: 'wiring-canvas',
+  event: 'host-changed',
+  field: 'hostId',
+  fieldType: 'string',
+  to: 'wiring-table',
+  input: 'host-id',
+  inputType: 'string',
+  transform: { _tag: 'direct' },
+  envs: ['dev', 'preview', 'prod'],
+  plain: 'When the canvas switches host, list that host’s wires.',
+}
+
+const pg6: Wire = {
+  id: 'pg6',
+  from: 'pages-rail',
+  event: 'host-changed',
+  field: 'hostId',
+  fieldType: 'string',
+  to: 'pages-canvas',
+  input: 'host-id',
+  inputType: 'string',
+  transform: { _tag: 'direct' },
+  envs: ['dev', 'preview', 'prod'],
+  plain: 'When the rail switches host, draw that host’s routes.',
+}
+
+const pg7: Wire = { ...pg6, id: 'pg7', to: 'pages-inspector' }
+
+/** A `json` wire — the one declared fieldType the demo records never use. */
+const wJson: Wire = {
+  id: 'w-json',
+  from: 'bespoke-contact-dashboard',
+  event: 'snapshot-changed',
+  field: 'snapshot',
+  fieldType: 'json',
+  to: 'fleet-health',
+  input: 'snapshot',
+  inputType: 'json',
+  transform: { _tag: 'direct' },
+  envs: ['dev', 'preview', 'prod'],
+  plain: 'When the snapshot changes, hand the fleet the whole document.',
+}
+
+const enginesToDetach: Array<{ detach: () => void }> = []
+
+/** Every DOM test runs the shells' environment, `dev`. */
+const attach = (options: Omit<WireEngineOptions, 'env'>): WireEngine => {
+  const engine = attachWireEngine({ ...options, env: 'dev' })
+  enginesToDetach.push(engine)
+  return engine
+}
+
+const mount = (tag: string): HTMLElement => {
+  const element = document.createElement(tag)
+  document.body.appendChild(element)
+  return element
+}
+
+/**
+ * Dispatches the way a MicroDot does: ON the emitting element, bubbling up to
+ * the engine's `document` listener, so `event.target` names the source exactly
+ * as `defineMicroDot` produces it
+ * (`packages/microdots-element/src/defineMicroDot.ts:281-283`). A wire's
+ * `from` is matched against that tag, so every test that expects a write must
+ * emit from the tag its wire names.
+ */
+const dispatch = (sourceTag: string, name: string, detail: unknown): void => {
+  const existing = document.querySelector(sourceTag)
+  const source = existing ?? mount(sourceTag)
+  source.dispatchEvent(new CustomEvent(name, { detail, bubbles: true }))
+}
+
+/**
+ * An event with NO identifiable emitter: dispatched straight at `document`,
+ * whose `target` is a Document and not an Element. Nothing in this repo emits
+ * this way — it stands for the shapes that reach a `document` listener anyway
+ * (a foreign page's synthetic event, a retargeted non-element node).
+ */
+const dispatchAnonymously = (name: string, detail: unknown): void => {
+  document.dispatchEvent(new CustomEvent(name, { detail }))
+}
+
+/** The wire ids a trace list carries, in order — watch taps excluded. */
+const firedWireIds = (
+  traces: ReadonlyArray<WireTrace>,
+): ReadonlyArray<string> =>
+  traces.flatMap(trace => (trace._tag === 'wire' ? [trace.wireId] : []))
+
+/** The payloads the watch taps logged, in order — wire traces excluded. */
+const tappedPayloads = (
+  traces: ReadonlyArray<WireTrace>,
+): ReadonlyArray<unknown> =>
+  traces.flatMap(trace => (trace._tag === 'watch' ? [trace.payload] : []))
+
+beforeEach(() => {
+  document.body.replaceChildren()
+  enginesToDetach.splice(0).forEach(engine => {
+    engine.detach()
+  })
+})
+
+// The failure mode this whole file guards: the hand-written listener blocks
+// in apps/host/src/entry.ts are being REPLACED by these records, and any
+// drift between what they did and what the engine does is a silently broken
+// demo — the events still fire, the log still scrolls, and nothing arrives.
+describe('attachWireEngine', () => {
+  test('routes EFCT to eu-west through the w1 lookup rows', () => {
+    const fleet = mount('fleet-health')
+    attach({ topology: { wires: DEMO_WIRES, watch: [] } })
+
+    dispatch('price-ticker', 'quote-changed', { symbol: 'EFCT', cents: 12345 })
+
+    expect(fleet.getAttribute('region')).toBe('eu-west')
+  })
+
+  test('falls back to us-east for a symbol outside the lookup rows', () => {
+    const fleet = mount('fleet-health')
+    attach({ topology: { wires: DEMO_WIRES, watch: [] } })
+
+    dispatch('price-ticker', 'quote-changed', { symbol: 'ZZZZ', cents: 1 })
+
+    expect(fleet.getAttribute('region')).toBe('us-east')
+  })
+
+  test('a disabled wire writes nothing and traces the skip', () => {
+    const fleet = mount('fleet-health')
+    const traces: Array<WireTrace> = []
+    const engine = attach({
+      topology: { wires: DEMO_WIRES, watch: [] },
+      onTrace: trace => traces.push(trace),
+    })
+
+    engine.setEnabled('w1', false)
+    dispatch('price-ticker', 'quote-changed', { symbol: 'EFCT', cents: 12345 })
+
+    expect(fleet.getAttribute('region')).toBeNull()
+    expect(traces).toEqual([
+      {
+        _tag: 'wire',
+        event: 'quote-changed',
+        wireId: 'w1',
+        delivery: { _tag: 'skipped', reason: 'disabled' },
+      },
+    ])
+
+    // The kill switch is not a detach: flipping it back restores the wire.
+    engine.setEnabled('w1', true)
+    dispatch('price-ticker', 'quote-changed', { symbol: 'EFCT', cents: 12345 })
+    expect(fleet.getAttribute('region')).toBe('eu-west')
+  })
+
+  test('encodes the numeric version 7 as the attribute string "7"', () => {
+    const form = mount('bespoke-contact-form')
+    attach({ topology: { wires: DEMO_WIRES, watch: [] } })
+
+    dispatch('bespoke-contact-dashboard', 'definition-changed', { version: 7 })
+
+    expect(form.getAttribute('definition-token')).toBe('7')
+  })
+
+  /**
+   * `setAttribute` fires `attributeChangedCallback` even when the value is
+   * unchanged, so two identical events must reach the element as ONE write —
+   * the guard lives in `setMicroDotAttribute` and the engine must go through
+   * it (apps/host/src/loader.test.ts pins the same guard directly).
+   */
+  test('two identical events produce exactly one setAttribute call', () => {
+    const form = mount('bespoke-contact-form')
+    attach({ topology: { wires: DEMO_WIRES, watch: [] } })
+
+    dispatch('bespoke-contact-dashboard', 'definition-changed', { version: 7 })
+    expect(form.getAttribute('definition-token')).toBe('7')
+
+    const spy = vi.spyOn(form, 'setAttribute')
+    dispatch('bespoke-contact-dashboard', 'definition-changed', { version: 7 })
+
+    expect(spy).not.toHaveBeenCalled()
+    spy.mockRestore()
+  })
+
+  test('falls back for a lookup key inherited from Object.prototype', () => {
+    // 'constructor' is not in w1's rows, but a bare `rows[encoded]` index
+    // would find Object.prototype.constructor and write
+    // 'function Object() { [native code] }' where the fallback belongs.
+    const fleet = mount('fleet-health')
+    attach({ topology: { wires: DEMO_WIRES, watch: [] } })
+
+    dispatch('price-ticker', 'quote-changed', {
+      symbol: 'constructor',
+      cents: 1,
+    })
+
+    expect(fleet.getAttribute('region')).toBe('us-east')
+  })
+
+  test('a payload that is not a record skips as no-field', () => {
+    const form = mount('bespoke-contact-form')
+    const traces: Array<WireTrace> = []
+    attach({
+      topology: { wires: DEMO_WIRES, watch: [] },
+      onTrace: trace => traces.push(trace),
+    })
+
+    dispatch('bespoke-contact-dashboard', 'definition-changed', 'seven')
+
+    expect(form.getAttribute('definition-token')).toBeNull()
+    expect(traces).toEqual([
+      {
+        _tag: 'wire',
+        event: 'definition-changed',
+        wireId: 'w3',
+        delivery: { _tag: 'skipped', reason: 'no-field' },
+      },
+    ])
+  })
+
+  test("a payload missing the wire's field skips as no-field", () => {
+    const form = mount('bespoke-contact-form')
+    const traces: Array<WireTrace> = []
+    attach({
+      topology: { wires: DEMO_WIRES, watch: [] },
+      onTrace: trace => traces.push(trace),
+    })
+
+    dispatch('bespoke-contact-dashboard', 'definition-changed', { revision: 7 })
+
+    expect(form.getAttribute('definition-token')).toBeNull()
+    expect(traces).toEqual([
+      {
+        _tag: 'wire',
+        event: 'definition-changed',
+        wireId: 'w3',
+        delivery: { _tag: 'skipped', reason: 'no-field' },
+      },
+    ])
+  })
+
+  test('a value that fails its declared fieldType decode skips as no-field', () => {
+    const form = mount('bespoke-contact-form')
+    const traces: Array<WireTrace> = []
+    attach({
+      topology: { wires: DEMO_WIRES, watch: [] },
+      onTrace: trace => traces.push(trace),
+    })
+
+    dispatch('bespoke-contact-dashboard', 'definition-changed', {
+      version: 'seven',
+    })
+
+    expect(form.getAttribute('definition-token')).toBeNull()
+    expect(traces).toEqual([
+      {
+        _tag: 'wire',
+        event: 'definition-changed',
+        wireId: 'w3',
+        delivery: { _tag: 'skipped', reason: 'no-field' },
+      },
+    ])
+  })
+
+  test('a json field writes its JSON.stringify encoding', () => {
+    const fleet = mount('fleet-health')
+    attach({ topology: { wires: [wJson], watch: [] } })
+
+    dispatch('bespoke-contact-dashboard', 'snapshot-changed', {
+      snapshot: { id: 7, tags: ['a'] },
+    })
+
+    expect(fleet.getAttribute('snapshot')).toBe('{"id":7,"tags":["a"]}')
+  })
+
+  test('an unencodable json value skips its wire without killing siblings on the same event', () => {
+    // A postMessage structured clone legally carries cycles, and
+    // JSON.stringify THROWS on them — an uncaught throw inside the listener
+    // would drop the sibling's write and trace too.
+    const fleet = mount('fleet-health')
+    const sibling: Wire = {
+      ...wJson,
+      id: 'w-sibling',
+      field: 'label',
+      fieldType: 'string',
+      input: 'label',
+      inputType: 'string',
+    }
+    const traces: Array<WireTrace> = []
+    attach({
+      topology: { wires: [wJson, sibling], watch: [] },
+      onTrace: trace => traces.push(trace),
+    })
+
+    const cyclic: Record<string, unknown> = {}
+    cyclic['self'] = cyclic
+    dispatch('bespoke-contact-dashboard', 'snapshot-changed', {
+      snapshot: cyclic,
+      label: 'ok',
+    })
+
+    expect(fleet.getAttribute('snapshot')).toBeNull()
+    expect(fleet.getAttribute('label')).toBe('ok')
+    expect(traces).toEqual([
+      {
+        _tag: 'wire',
+        event: 'snapshot-changed',
+        wireId: 'w-json',
+        delivery: { _tag: 'skipped', reason: 'no-field' },
+      },
+      {
+        _tag: 'wire',
+        event: 'snapshot-changed',
+        wireId: 'w-sibling',
+        delivery: {
+          _tag: 'written',
+          write: { toTag: 'fleet-health', input: 'label', value: 'ok' },
+        },
+      },
+    ])
+  })
+
+  test('every mounted instance of the target tag receives the write', () => {
+    // A topology may place one tag in two slots; "the first in document
+    // order" is not what the record says, and 'written' must mean all of them.
+    const first = mount('fleet-health')
+    const second = mount('fleet-health')
+    attach({ topology: { wires: DEMO_WIRES, watch: [] } })
+
+    dispatch('price-ticker', 'quote-changed', { symbol: 'EFCT', cents: 12345 })
+
+    expect(first.getAttribute('region')).toBe('eu-west')
+    expect(second.getAttribute('region')).toBe('eu-west')
+  })
+
+  test('a wire whose `to` is not a valid selector is target-unmounted, and later wires still trace', () => {
+    // The schema admits any string as `to`; querySelectorAll('') throws, and
+    // an uncaught throw would abort trace emission for every remaining wire.
+    const fleet = mount('fleet-health')
+    const malformed: Wire = { ...w1, id: 'w-bad', to: '' }
+    const traces: Array<WireTrace> = []
+    attach({
+      topology: { wires: [malformed, w1], watch: [] },
+      onTrace: trace => traces.push(trace),
+    })
+
+    dispatch('price-ticker', 'quote-changed', { symbol: 'EFCT', cents: 12345 })
+
+    expect(fleet.getAttribute('region')).toBe('eu-west')
+    expect(traces).toEqual([
+      {
+        _tag: 'wire',
+        event: 'quote-changed',
+        wireId: 'w-bad',
+        delivery: {
+          _tag: 'target-unmounted',
+          write: { toTag: '', input: 'region', value: 'eu-west' },
+        },
+      },
+      {
+        _tag: 'wire',
+        event: 'quote-changed',
+        wireId: 'w1',
+        delivery: {
+          _tag: 'written',
+          write: { toTag: 'fleet-health', input: 'region', value: 'eu-west' },
+        },
+      },
+    ])
+  })
+
+  test('a wire whose `input` is not a valid attribute name fails its write, and siblings on the same event still land', () => {
+    // The schema admits any string as `input`; setAttribute('refresh token')
+    // throws InvalidCharacterError, and an uncaught throw out of the document
+    // listener would drop the write AND trace of every remaining wire.
+    const fleet = mount('fleet-health')
+    const hostile: Wire = { ...w1, id: 'w-hostile', input: 'refresh token' }
+    const traces: Array<WireTrace> = []
+    attach({
+      topology: { wires: [hostile, w1], watch: [] },
+      onTrace: trace => traces.push(trace),
+    })
+
+    dispatch('price-ticker', 'quote-changed', { symbol: 'EFCT', cents: 12345 })
+
+    expect(fleet.getAttribute('region')).toBe('eu-west')
+    expect(traces).toEqual([
+      {
+        _tag: 'wire',
+        event: 'quote-changed',
+        wireId: 'w-hostile',
+        delivery: {
+          _tag: 'write-failed',
+          write: {
+            toTag: 'fleet-health',
+            input: 'refresh token',
+            value: 'eu-west',
+          },
+        },
+      },
+      {
+        _tag: 'wire',
+        event: 'quote-changed',
+        wireId: 'w1',
+        delivery: {
+          _tag: 'written',
+          write: { toTag: 'fleet-health', input: 'region', value: 'eu-west' },
+        },
+      },
+    ])
+  })
+
+  test('the watch tap traces before the wire delivery when an event is both watched and wired', () => {
+    // Today's hosts log before they act; a wire's write must never become a
+    // precondition of the log line.
+    mount('fleet-health')
+    const traces: Array<WireTrace> = []
+    attach({
+      topology: { wires: DEMO_WIRES, watch: [{ event: 'quote-changed' }] },
+      onTrace: trace => traces.push(trace),
+    })
+
+    dispatch('price-ticker', 'quote-changed', { symbol: 'EFCT', cents: 12345 })
+
+    expect(traces.map(trace => trace._tag)).toEqual(['watch', 'wire'])
+  })
+
+  test('a held condition writes nothing and the trace names the wanted value', () => {
+    const fleet = mount('fleet-health')
+    const conditioned: Wire = {
+      ...w1,
+      id: 'w-linked',
+      transform: {
+        _tag: 'condition',
+        field: 'linked',
+        op: 'is',
+        value: 'true',
+      },
+    }
+    const traces: Array<WireTrace> = []
+    attach({
+      topology: { wires: [conditioned], watch: [] },
+      onTrace: trace => traces.push(trace),
+    })
+
+    dispatch('price-ticker', 'quote-changed', { symbol: 'EFCT', linked: false })
+
+    expect(fleet.getAttribute('region')).toBeNull()
+    expect(traces).toEqual([
+      {
+        _tag: 'wire',
+        event: 'quote-changed',
+        wireId: 'w-linked',
+        delivery: { _tag: 'held', wanted: 'true' },
+      },
+    ])
+
+    // The condition holding is the whole difference: same event, one write.
+    dispatch('price-ticker', 'quote-changed', { symbol: 'EFCT', linked: true })
+    expect(fleet.getAttribute('region')).toBe('EFCT')
+  })
+
+  test('a watch tap traces the event name and raw payload without writing', () => {
+    const traces: Array<WireTrace> = []
+    attach({
+      topology: { wires: [], watch: [{ event: 'progress-changed' }] },
+      onTrace: trace => traces.push(trace),
+    })
+
+    dispatch('cumulative-functional-spec-generator-panel', 'progress-changed', {
+      current: 3,
+      total: 9,
+      stage: 'drafting',
+    })
+
+    expect(traces).toEqual([
+      {
+        _tag: 'watch',
+        event: 'progress-changed',
+        payload: { current: 3, total: 9, stage: 'drafting' },
+      },
+    ])
+  })
+
+  test('an unmounted target is a skipped write, still traced — the poll floor covers it', () => {
+    const traces: Array<WireTrace> = []
+    attach({
+      topology: { wires: DEMO_WIRES, watch: [] },
+      onTrace: trace => traces.push(trace),
+    })
+
+    dispatch('bespoke-contact-form', 'submission-created', { id: 'sub-42' })
+
+    expect(traces).toEqual([
+      {
+        _tag: 'wire',
+        event: 'submission-created',
+        wireId: 'w2',
+        delivery: {
+          _tag: 'target-unmounted',
+          write: {
+            toTag: 'bespoke-contact-dashboard',
+            input: 'refresh-token',
+            value: 'sub-42',
+          },
+        },
+      },
+    ])
+  })
+
+  /**
+   * The Phase 5 defect, pinned. Under a name-only match the Pages rail's host
+   * picker ALSO retargeted the hidden Wiring screen through pw12, and the
+   * Wiring canvas's picker drove the Pages panes through pg6/pg7 — panes
+   * resolving a host the rail's picker was not showing, after which a route
+   * click sent paths from host A into panes rendering host B. All four wires
+   * derive `live`, so the Wiring screen showed nothing wrong.
+   */
+  test('two dots emitting the same event name drive only the wire whose `from` matches', () => {
+    const table = mount('wiring-table')
+    const canvas = mount('pages-canvas')
+    const inspector = mount('pages-inspector')
+    const traces: Array<WireTrace> = []
+    attach({
+      topology: { wires: [pw12, pg6, pg7], watch: [] },
+      onTrace: trace => traces.push(trace),
+    })
+
+    dispatch('pages-rail', 'host-changed', { hostId: 'platform-host' })
+
+    expect(canvas.getAttribute('host-id')).toBe('platform-host')
+    expect(inspector.getAttribute('host-id')).toBe('platform-host')
+    // The other screen is untouched — the whole defect in one assertion.
+    expect(table.getAttribute('host-id')).toBeNull()
+    // …and pw12 does not even appear in the trace: this is not its event.
+    expect(firedWireIds(traces)).toEqual(['pg6', 'pg7'])
+
+    dispatch('wiring-canvas', 'host-changed', { hostId: 'demo-host' })
+
+    expect(table.getAttribute('host-id')).toBe('demo-host')
+    // The Pages panes keep the host their own rail last chose.
+    expect(canvas.getAttribute('host-id')).toBe('platform-host')
+    expect(inspector.getAttribute('host-id')).toBe('platform-host')
+  })
+
+  test('an event with no identifiable source fires no wires and traces the source skip', () => {
+    const canvas = mount('pages-canvas')
+    const traces: Array<WireTrace> = []
+    attach({
+      topology: { wires: [pw12, pg6], watch: [] },
+      onTrace: trace => traces.push(trace),
+    })
+
+    dispatchAnonymously('host-changed', { hostId: 'platform-host' })
+
+    expect(canvas.getAttribute('host-id')).toBeNull()
+    expect(traces).toEqual([
+      {
+        _tag: 'wire',
+        event: 'host-changed',
+        wireId: 'pw12',
+        delivery: { _tag: 'skipped', reason: 'source' },
+      },
+      {
+        _tag: 'wire',
+        event: 'host-changed',
+        wireId: 'pg6',
+        delivery: { _tag: 'skipped', reason: 'source' },
+      },
+    ])
+  })
+
+  test('a watch tap is the host log, not a wire: it fires for every emitter and for none', () => {
+    // The tap is keyed on the event NAME alone, deliberately — a log that
+    // only recorded the one dot a wire happens to name would stop being a
+    // log. Three emitters of `host-changed`, three lines.
+    const traces: Array<WireTrace> = []
+    attach({
+      topology: { wires: [pw12], watch: [{ event: 'host-changed' }] },
+      onTrace: trace => traces.push(trace),
+    })
+
+    dispatch('pages-rail', 'host-changed', { hostId: 'a' })
+    dispatch('wiring-canvas', 'host-changed', { hostId: 'b' })
+    dispatchAnonymously('host-changed', { hostId: 'c' })
+
+    expect(tappedPayloads(traces)).toEqual([
+      { hostId: 'a' },
+      { hostId: 'b' },
+      { hostId: 'c' },
+    ])
+  })
+
+  test('detach removes every listener', () => {
+    const fleet = mount('fleet-health')
+    const engine = attach({ topology: { wires: DEMO_WIRES, watch: [] } })
+
+    engine.detach()
+    dispatch('price-ticker', 'quote-changed', { symbol: 'EFCT', cents: 12345 })
+
+    expect(fleet.getAttribute('region')).toBeNull()
+  })
+})
+
+// The failure mode: a host's immediate-apply path (the demo host's link
+// toggle) re-applies a wire's transform OUTSIDE the engine, and a second
+// implementation of the rows/fallback semantics would drift from what the
+// engine writes when the event actually fires.
+describe('applyTransform', () => {
+  test('agrees with planWires on rows, fallback, and prototype-key misses', () => {
+    const symbols = ['EFCT', 'ZZZZ', 'constructor']
+    symbols.forEach(symbol => {
+      const plan = planWires(
+        [w1],
+        {
+          name: 'quote-changed',
+          sourceTag: Option.some(w1.from),
+          payload: { symbol, cents: 1 },
+        },
+        { env: 'dev', isEnabled: () => true },
+      )
+      expect(
+        plan.writes.map(write => write.value),
+        symbol,
+      ).toEqual([applyTransform(w1.transform, symbol)])
+    })
+  })
+
+  test('direct and condition pass the encoded value straight through', () => {
+    expect(applyTransform({ _tag: 'direct' }, 'sub-42')).toBe('sub-42')
+    expect(
+      applyTransform(
+        { _tag: 'condition', field: 'linked', op: 'is', value: 'true' },
+        'EFCT',
+      ),
+    ).toBe('EFCT')
+  })
+})
+
+// The failure mode: a planner that quietly grew a DOM dependency would make
+// every non-DOM transport (the cross-origin bridge, a future server-side
+// derivation) impossible — transport-blindness is property 2 of
+// wiki/framework/composition/wire-execution-and-transforms.md.
+describe('planWires', () => {
+  test('plans a bridge postMessage envelope with no document and no DOM event', () => {
+    // Shaped like apps/cross-origin-demo/src/bridge.ts's SubmissionCreated —
+    // a postMessage envelope, not a CustomEvent detail. The planner neither
+    // knows nor cares HOW the source was identified, only that it was: with
+    // no `event.target` to read, a non-DOM transport names the emitting tag
+    // in the envelope itself.
+    const envelope = {
+      version: 1,
+      type: 'submission-created',
+      from: 'bespoke-contact-form',
+      submissionId: 'sub-42',
+    }
+    const bridgeWire: Wire = { ...w2, field: 'submissionId' }
+
+    const plan = planWires(
+      [bridgeWire],
+      {
+        name: envelope.type,
+        sourceTag: Option.some(envelope.from),
+        payload: envelope,
+      },
+      { env: 'prod', isEnabled: () => true },
+    )
+
+    expect(plan.writes).toEqual([
+      {
+        toTag: 'bespoke-contact-dashboard',
+        input: 'refresh-token',
+        value: 'sub-42',
+      },
+    ])
+  })
+
+  test('an envelope naming a different sender matches nothing and traces nothing', () => {
+    // The same name, the same payload shape, a different dot. Not a skip:
+    // this event is not this wire's event at all, and a trace line for it
+    // would be noise in every host log that carries a shared event name.
+    const bridgeWire: Wire = { ...w2, field: 'submissionId' }
+
+    const plan = planWires(
+      [bridgeWire],
+      {
+        name: 'submission-created',
+        sourceTag: Option.some('some-other-form'),
+        payload: { submissionId: 'sub-42' },
+      },
+      { env: 'prod', isEnabled: () => true },
+    )
+
+    expect(plan).toEqual({ writes: [], outcomes: [] })
+  })
+
+  test('a source the transport could not identify skips every name-matched wire', () => {
+    // `None` is not a wildcard: a wire whose source cannot be confirmed must
+    // NOT fire, because "some dot emitted host-changed" is exactly the
+    // ambiguity the `from` match exists to remove. It still traces — a
+    // name-matched wire going quiet is what a trace has to be able to show.
+    const plan = planWires(
+      [w2, w3],
+      {
+        name: 'submission-created',
+        sourceTag: Option.none(),
+        payload: { id: 'sub-1' },
+      },
+      { env: 'prod', isEnabled: () => true },
+    )
+
+    expect(plan.writes).toEqual([])
+    expect(plan.outcomes).toEqual([
+      { _tag: 'skipped', wireId: 'w2', reason: 'source' },
+    ])
+  })
+
+  test('skips a wire whose envs exclude the running environment, distinctly from disabled', () => {
+    const devOnly: Wire = { ...w2, envs: ['dev'] }
+
+    const plan = planWires(
+      [devOnly],
+      {
+        name: 'submission-created',
+        sourceTag: Option.some('bespoke-contact-form'),
+        payload: { id: 'sub-1' },
+      },
+      { env: 'prod', isEnabled: () => true },
+    )
+
+    expect(plan.writes).toEqual([])
+    expect(plan.outcomes).toEqual([
+      { _tag: 'skipped', wireId: 'w2', reason: 'env' },
+    ])
+  })
+})