@bespokeagentics/microdots-host 0.1.0

package/src/wireEngine.ts

@@ -0,0 +1,468 @@
+import { Array, Option, Schema as S } from 'effect'
+
+import { setMicroDotAttribute } from './loader.ts'
+import type { Wire, WireEnv, WireTransform, WireValueType } from './wire.ts'
+
+/**
+ * The wire ENGINE — the runtime half of `./wire`'s record.
+ *
+ * Split in two on purpose. `planWires` is pure: an event in, attribute writes
+ * out, and its output TYPE is the design constraint — `{toTag, input, value}`
+ * can only ever become an attribute write, so a wire calling a method on a
+ * MicroDot is unrepresentable, not merely forbidden. `attachWireEngine` is
+ * the DOM adapter that feeds `planWires` from `document` events and performs
+ * the writes; a different transport (the cross-origin bridge's `postMessage`
+ * envelope, say) feeds the same planner and needs nothing from this file's
+ * DOM half — beyond naming the tag that emitted the event, which every
+ * transport must carry now that `from` is part of the match. See
+ * `wiki/framework/composition/wire-execution-and-transforms.md` for the four properties
+ * this keeps.
+ */
+
+/**
+ * The event as the planner sees it: a name, the tag that EMITTED it, and an
+ * untrusted payload.
+ *
+ * `sourceTag` is an `Option` because identifying the emitter is the
+ * transport's job and a transport may fail at it — a DOM event whose `target`
+ * is not an element, a bridge envelope that names no sender. `None` means "no
+ * emitter could be confirmed", which is not the same as "some emitter", and
+ * `planWires` treats the difference as load-bearing: see the match site below.
+ */
+export type WireEventInput = {
+  readonly name: string
+  readonly sourceTag: Option.Option<string>
+  readonly payload: unknown
+}
+
+/** The only thing a wire can produce: one attribute write. */
+export type WireWrite = {
+  readonly toTag: string
+  readonly input: string
+  readonly value: string
+}
+
+/**
+ * Why a matched wire produced no write. `source` comes first and is the
+ * match gate: the event's name matched but the transport could not say which
+ * tag emitted it, so no wire's `from` can be confirmed. `env` and `disabled`
+ * are the two gates checked before the payload is even looked at; `no-field`
+ * covers a payload that is not a record, lacks the wire's field, or carries a
+ * value that fails the declared `fieldType` decode.
+ */
+export type WireSkipReason = 'source' | 'env' | 'disabled' | 'no-field'
+
+/**
+ * One matched wire's fate, for tracing. `planned` carries the write;
+ * `held` is a condition that did not hold and names the value it wanted;
+ * `skipped` names its gate. Distinct tags rather than a nullable write,
+ * so a trace formatter cannot conflate "held" with "skipped".
+ */
+export type WireOutcome =
+  | {
+      readonly _tag: 'planned'
+      readonly wireId: string
+      readonly write: WireWrite
+    }
+  | { readonly _tag: 'held'; readonly wireId: string; readonly wanted: string }
+  | {
+      readonly _tag: 'skipped'
+      readonly wireId: string
+      readonly reason: WireSkipReason
+    }
+
+/** Everything one event produced: the writes to perform, and why. */
+export type WirePlan = {
+  readonly writes: ReadonlyArray<WireWrite>
+  readonly outcomes: ReadonlyArray<WireOutcome>
+}
+
+// Decoders hoisted once — planWires runs on every brokered event.
+const decodeRecord = S.decodeUnknownOption(S.Record(S.String, S.Unknown))
+const decodeString = S.decodeUnknownOption(S.String)
+const decodeNumber = S.decodeUnknownOption(S.Number)
+const decodeBoolean = S.decodeUnknownOption(S.Boolean)
+
+/**
+ * `JSON.stringify` has two failure shapes and both mean "this value has no
+ * JSON encoding": it RETURNS undefined for undefined/function/symbol, and it
+ * THROWS for circular structures and BigInt. The payload is untrusted (a
+ * `CustomEvent` detail, a `postMessage` structured clone — which legally
+ * carries cycles), and a throw here would escape `planWires` into the DOM
+ * listener and kill every other wire's trace on the same event, so both
+ * shapes collapse to `Option.none`.
+ */
+const safeStringify = (raw: unknown): Option.Option<string> => {
+  try {
+    return Option.fromNullishOr(JSON.stringify(raw))
+  } catch {
+    return Option.none()
+  }
+}
+
+/**
+ * Engine-owned encoding — the `String(version)` ruling. The type CHECK
+ * compares declared types (`deriveWireState`); once a value passes its
+ * declared `fieldType` decode, encoding it onto the attribute string is the
+ * engine's job: `number → String(n)`, `boolean → String(b)`, `string`/`enum`
+ * pass through, `json → JSON.stringify`. `Option.none` means the value did
+ * not match its declaration and nothing is written.
+ */
+const encodeFieldValue = (
+  fieldType: WireValueType,
+  raw: unknown,
+): Option.Option<string> => {
+  switch (fieldType) {
+    case 'string':
+    case 'enum':
+      return decodeString(raw)
+    case 'number':
+      return Option.map(decodeNumber(raw), value => String(value))
+    case 'boolean':
+      return Option.map(decodeBoolean(raw), value => String(value))
+    case 'json':
+      return safeStringify(raw)
+  }
+}
+
+/**
+ * Encodes a value whose type the wire does NOT declare — a condition's gate
+ * field. The condition compares encoded strings, so any primitive is admitted
+ * through the same encodings `encodeFieldValue` would apply.
+ */
+const encodeUnknown = (raw: unknown): Option.Option<string> =>
+  Option.orElse(decodeString(raw), () =>
+    Option.orElse(
+      Option.map(decodeNumber(raw), value => String(value)),
+      () => Option.map(decodeBoolean(raw), value => String(value)),
+    ),
+  )
+
+/**
+ * Applies a wire's transform to an already-encoded source value. Exported so
+ * a host's immediate-apply path (the demo host's link toggle re-applying `w1`
+ * between quotes) runs THIS code against the recorded transform instead of
+ * re-implementing the rows/fallback semantics and drifting from the engine.
+ */
+export const applyTransform = (
+  transform: WireTransform,
+  encoded: string,
+): string => {
+  switch (transform._tag) {
+    case 'direct':
+    case 'condition':
+      return encoded
+    case 'lookup': {
+      // `Object.hasOwn` before indexing: the key is an untrusted payload
+      // value, and a bare `rows[encoded]` with a key like 'constructor'
+      // reads an Object.prototype member instead of missing — leaking a
+      // Function into the write where the fallback belongs.
+      if (!Object.hasOwn(transform.rows, encoded)) {
+        return transform.fallback
+      }
+      return Option.getOrElse(
+        Option.fromNullishOr(transform.rows[encoded]),
+        () => transform.fallback,
+      )
+    }
+  }
+}
+
+const skipped = (wireId: string, reason: WireSkipReason): WireOutcome => ({
+  _tag: 'skipped',
+  wireId,
+  reason,
+})
+
+const outcomeFor = (
+  wire: Wire,
+  payload: unknown,
+  context: {
+    readonly env: WireEnv
+    readonly isEnabled: (wireId: string) => boolean
+  },
+): WireOutcome => {
+  if (!Array.contains(wire.envs, context.env)) {
+    return skipped(wire.id, 'env')
+  }
+  if (!context.isEnabled(wire.id)) {
+    return skipped(wire.id, 'disabled')
+  }
+  return Option.match(decodeRecord(payload), {
+    onNone: () => skipped(wire.id, 'no-field'),
+    onSome: (record): WireOutcome => {
+      if (wire.transform._tag === 'condition') {
+        const wanted = wire.transform.value
+        const gate = wire.transform.field
+        const actual = Object.hasOwn(record, gate)
+          ? encodeUnknown(record[gate])
+          : Option.none()
+        const holds = Option.match(actual, {
+          onNone: () => false,
+          onSome: encoded => encoded === wanted,
+        })
+        if (!holds) {
+          return { _tag: 'held', wireId: wire.id, wanted }
+        }
+      }
+      if (!Object.hasOwn(record, wire.field)) {
+        return skipped(wire.id, 'no-field')
+      }
+      return Option.match(
+        encodeFieldValue(wire.fieldType, record[wire.field]),
+        {
+          onNone: () => skipped(wire.id, 'no-field'),
+          onSome: (encoded): WireOutcome => ({
+            _tag: 'planned',
+            wireId: wire.id,
+            write: {
+              toTag: wire.to,
+              input: wire.input,
+              value: applyTransform(wire.transform, encoded),
+            },
+          }),
+        },
+      )
+    },
+  })
+}
+
+/**
+ * PURE. Matches a wire on BOTH halves of its source: the event NAME and the
+ * `from` tag that emitted it. No DOM, no transport: whatever delivered
+ * `{name, sourceTag, payload}` — a `document` event's `target` + `detail`, a
+ * bridge envelope off `postMessage` — the plan is the same.
+ *
+ * Phase 4 matched by name alone, on the reasoning that the hand-written
+ * listeners it replaced never checked the source element either and a wire's
+ * `from` was a claim `deriveWireState` verifies rather than a runtime filter.
+ * That held only while every event name had exactly one emitter. Phase 5 ended
+ * it: `host-changed` is emitted by BOTH `wiring-canvas` and `pages-rail` with
+ * the same `{hostId}` payload, so a name-only match let the Pages rail's host
+ * switch drive the hidden Wiring screen (pw12) and the Wiring canvas's drive
+ * the Pages panes (pg6/pg7) — panes resolving a host their own picker was not
+ * showing, with all four wires deriving `live`. `from` is load-bearing; see
+ * the Decision in `wiki/framework/composition/wire-execution-and-transforms.md`.
+ *
+ * A wire whose source cannot be CONFIRMED must not fire — an unidentifiable
+ * emitter is exactly the ambiguity this match exists to remove, so `None`
+ * skips (`'source'`) rather than falling back to the old name-only behaviour.
+ * It still produces an outcome, because a name-matched wire going quiet is
+ * the failure a trace has to be able to show. A wire whose source is
+ * confirmed to be a DIFFERENT tag is not matched at all and traces nothing:
+ * that event belongs to another dot.
+ */
+export const planWires = (
+  wires: ReadonlyArray<Wire>,
+  event: WireEventInput,
+  context: {
+    readonly env: WireEnv
+    readonly isEnabled: (wireId: string) => boolean
+  },
+): WirePlan => {
+  const outcomes = Array.getSomes(
+    wires.map((wire): Option.Option<WireOutcome> => {
+      if (wire.event !== event.name) {
+        return Option.none()
+      }
+      return Option.match(event.sourceTag, {
+        onNone: () => Option.some(skipped(wire.id, 'source')),
+        onSome: tag =>
+          tag === wire.from
+            ? Option.some(outcomeFor(wire, event.payload, context))
+            : Option.none(),
+      })
+    }),
+  )
+  const writes = Array.getSomes(
+    outcomes.map(outcome =>
+      outcome._tag === 'planned' ? Option.some(outcome.write) : Option.none(),
+    ),
+  )
+  return { writes, outcomes }
+}
+
+/* ============================================================
+   The DOM adapter.
+   ============================================================ */
+
+/**
+ * A planned write's fate once the DOM is consulted. `target-unmounted` is a
+ * SKIPPED write, deliberately: a brokered nudge is an optimisation and the
+ * poll is the floor, so an absent element converges on its own when it next
+ * mounts — the trace records that the nudge went nowhere. `written` means
+ * EVERY mounted instance of the target tag received the write — a topology
+ * may place one tag in two slots, and "the first one in document order" is
+ * not what the record says. `write-failed` is the DOM refusing the write
+ * itself — a wire `input` the schema admits but `setAttribute` rejects —
+ * traced distinctly so a hand-edited record surfaces instead of vanishing.
+ */
+export type WireDelivery =
+  | { readonly _tag: 'written'; readonly write: WireWrite }
+  | { readonly _tag: 'target-unmounted'; readonly write: WireWrite }
+  | { readonly _tag: 'write-failed'; readonly write: WireWrite }
+  | { readonly _tag: 'held'; readonly wanted: string }
+  | { readonly _tag: 'skipped'; readonly reason: WireSkipReason }
+
+/**
+ * What `onTrace` surfaces: every wire firing with its delivery, and every
+ * `watch[]` tap with the raw payload. The host's log formatter consumes the
+ * taps; the Wiring screen's Watch mode will consume both.
+ */
+export type WireTrace =
+  | {
+      readonly _tag: 'wire'
+      readonly event: string
+      readonly wireId: string
+      readonly delivery: WireDelivery
+    }
+  | {
+      readonly _tag: 'watch'
+      readonly event: string
+      readonly payload: unknown
+    }
+
+export type WireEngineOptions = {
+  /** The wires and watch taps to run — a whole `HostTopology` is assignable. */
+  readonly topology: {
+    readonly wires: ReadonlyArray<Wire>
+    readonly watch: ReadonlyArray<{ readonly event: string }>
+  }
+  readonly env: WireEnv
+  readonly onTrace?: (trace: WireTrace) => void
+}
+
+export type WireEngine = {
+  /** All wires start enabled; this is the runtime kill switch per wire. */
+  readonly setEnabled: (wireId: string, enabled: boolean) => void
+  readonly detach: () => void
+}
+
+/**
+ * Listens on `document` for every distinct wire event name AND every watch
+ * tap, plans each event with `planWires`, and performs the planned writes —
+ * ONLY through `setMicroDotAttribute`, whose no-op guard is what keeps a
+ * recurring event from resetting a MicroDot on every tick. No second write
+ * path exists, and this adapter does not add one.
+ */
+export const attachWireEngine = (options: WireEngineOptions): WireEngine => {
+  const { wires, watch } = options.topology
+  const onTrace = options.onTrace ?? (() => undefined)
+
+  // Target resolution is pinned: by tag name, among mounted elements, EVERY
+  // instance — not an injection point. `wire.to` is record data the schema
+  // cannot prove is a valid selector ('' or '1-foo' would make querySelectorAll
+  // throw), and a throw here would abort trace emission for every remaining
+  // wire on the same event, so an unresolvable tag resolves to nothing.
+  const resolveTargets = (tag: string): ReadonlyArray<Element> => {
+    try {
+      return Array.fromIterable(document.querySelectorAll(tag))
+    } catch {
+      return []
+    }
+  }
+
+  // Which tag emitted this event. `defineMicroDot` dispatches on the custom
+  // element itself with `bubbles: true`
+  // (packages/microdots-element/src/defineMicroDot.ts:281-283), so a listener
+  // on `document` sees the emitting element as `event.target` and its
+  // lowercased `tagName` IS the `from` a wire names.
+  //
+  // Anything else is `None` — an event dispatched straight at `document` or
+  // `window`, a retargeted node that is not an element, a null target on an
+  // already-dispatched event. `planWires` will not fire a wire it cannot
+  // confirm the source of; guessing here would reintroduce exactly the
+  // name-only match this replaced.
+  const sourceTagOf = (domEvent: Event): Option.Option<string> => {
+    const target = domEvent.target
+    return target instanceof Element
+      ? Option.some(target.tagName.toLowerCase())
+      : Option.none()
+  }
+
+  // Absent means enabled: every wire is live until someone flips it off.
+  const disabled = new Set<string>()
+  const isEnabled = (wireId: string): boolean => !disabled.has(wireId)
+
+  const watched = new Set(watch.map(tap => tap.event))
+  const eventNames = Array.dedupe([
+    ...wires.map(wire => wire.event),
+    ...watched,
+  ])
+
+  const deliver = (outcome: WireOutcome): WireDelivery => {
+    switch (outcome._tag) {
+      case 'planned': {
+        const targets = resolveTargets(outcome.write.toTag)
+        if (targets.length === 0) {
+          return { _tag: 'target-unmounted', write: outcome.write }
+        }
+        // `wire.input` is record data too: a name `setAttribute` rejects
+        // ('' or 'refresh token') throws InvalidCharacterError, and an
+        // uncaught throw here would abort trace emission for every remaining
+        // wire on the same event — the same reason `resolveTargets` guards
+        // its selector.
+        try {
+          targets.forEach(target => {
+            setMicroDotAttribute(
+              target,
+              outcome.write.input,
+              outcome.write.value,
+            )
+          })
+          return { _tag: 'written', write: outcome.write }
+        } catch {
+          return { _tag: 'write-failed', write: outcome.write }
+        }
+      }
+      case 'held':
+        return { _tag: 'held', wanted: outcome.wanted }
+      case 'skipped':
+        return { _tag: 'skipped', reason: outcome.reason }
+    }
+  }
+
+  const listeners = eventNames.map(name => {
+    const listener = (domEvent: Event): void => {
+      const payload: unknown =
+        domEvent instanceof CustomEvent ? domEvent.detail : undefined
+      // The tap first: today's hosts log before they act, and a wire's write
+      // must never be a precondition of the log line. A watch tap is the
+      // HOST'S LOG, not a wire — it fires for every emitter of the name, and
+      // an unidentifiable source does not silence it.
+      if (watched.has(name)) {
+        onTrace({ _tag: 'watch', event: name, payload })
+      }
+      const plan = planWires(
+        wires,
+        { name, sourceTag: sourceTagOf(domEvent), payload },
+        { env: options.env, isEnabled },
+      )
+      plan.outcomes.forEach(outcome => {
+        onTrace({
+          _tag: 'wire',
+          event: name,
+          wireId: outcome.wireId,
+          delivery: deliver(outcome),
+        })
+      })
+    }
+    document.addEventListener(name, listener)
+    return { name, listener }
+  })
+
+  return {
+    setEnabled: (wireId, enabled) => {
+      if (enabled) {
+        disabled.delete(wireId)
+      } else {
+        disabled.add(wireId)
+      }
+    },
+    detach: () => {
+      listeners.forEach(({ name, listener }) => {
+        document.removeEventListener(name, listener)
+      })
+    },
+  }
+}