@bespokeagentics/microdots-host 0.1.0

package/src/wire.ts

@@ -0,0 +1,560 @@
+import { Array, Option, Schema as S } from 'effect'
+
+import type {
+  ManifestAttribute,
+  ManifestEvent,
+  ManifestTag,
+} from '@bespokeagentics/microdots-element'
+
+import { type RouteTable, makeRouteTable } from './routes.ts'
+// Runtime import of the matcher only — `rules.ts` imports this module
+// type-only, so the emitted module graph stays acyclic.
+import { ruleMatches } from './rules.ts'
+import { HostSlotManifest } from './slots.ts'
+
+/**
+ * The wire RECORD — the declarative half of the broker.
+ *
+ * A wire says "when this element's event fires, write this field onto that
+ * element's attribute", which is exactly what the hand-written listener blocks
+ * in `apps/host/src/entry.ts` have been saying in prose. Phase 4 turns the
+ * prose into data this schema decodes, so the same record can drive the DOM
+ * adapter in `./wireEngine`, the Wiring screen's read mode, and any future
+ * transport — a record describes WHAT connects to WHAT, never how the message
+ * arrives. See `wiki/framework/composition/wire-execution-and-transforms.md`.
+ *
+ * Deliberately NOT here: `status` and `lastFired`. A stored status is stale the
+ * moment a placement or a manifest changes without the wire being touched;
+ * `deriveWireState` below computes it fresh from the manifests and the route
+ * table every time it is asked. Canvas coordinates are presentation, not
+ * record, and live with the Wiring dot.
+ */
+
+/** The environments a wire may run in — the fixture's vocabulary, verbatim. */
+export const WireEnv = S.Literals(['dev', 'preview', 'prod'])
+export type WireEnv = typeof WireEnv.Type
+
+/**
+ * What a wire claims a value's string encoding MEANS — the same vocabulary as
+ * the manifest's `AttributeType`, because the type-match check in
+ * `deriveWireState` compares a wire's declaration against a manifest's.
+ */
+export const WireValueType = S.Literals([
+  'string',
+  'number',
+  'boolean',
+  'json',
+  'enum',
+])
+export type WireValueType = typeof WireValueType.Type
+
+/**
+ * The three transforms, each a generalisation of code that already ran by
+ * hand in `apps/host/src/entry.ts`:
+ *
+ * - `direct`    — straight across (wire 5's `id` → `refresh-token`)
+ * - `lookup`    — map source values to target values with a fallback
+ *                 (wire 4's `REGION_BY_SYMBOL` + `DEFAULT_REGION`)
+ * - `condition` — fire only when a payload field `is` a value
+ *                 (wire 4's `if (linkToggle.checked)`)
+ *
+ * `op` is only ever `'is'` because the fixture shows only `'is'` — the
+ * vocabulary is a record of what exists, not an invitation to invent.
+ */
+export const WireTransform = S.Union([
+  S.Struct({ _tag: S.tag('direct') }),
+  S.Struct({
+    _tag: S.tag('lookup'),
+    rows: S.Record(S.String, S.String),
+    fallback: S.String,
+  }),
+  S.Struct({
+    _tag: S.tag('condition'),
+    field: S.String,
+    op: S.Literal('is'),
+    value: S.String,
+  }),
+])
+export type WireTransform = typeof WireTransform.Type
+
+/**
+ * One wire, field-for-field with the prototype fixture's Wire entity minus the
+ * two derived fields (`status`, `lastFired`). `from` and `to` are element TAG
+ * names — the fixture used short dot ids; real records use real tags.
+ * `plain` carries the Plain-English toggle's sentence.
+ */
+export const Wire = S.Struct({
+  id: S.String,
+  from: S.String,
+  event: S.String,
+  field: S.String,
+  fieldType: WireValueType,
+  to: S.String,
+  input: S.String,
+  inputType: WireValueType,
+  transform: WireTransform,
+  envs: S.Array(WireEnv),
+  plain: S.String,
+})
+export type Wire = typeof Wire.Type
+
+/* ============================================================
+   HostTopology — the per-host JSON record (`host-topology.json`) that both a
+   host's entry and the Wiring service decode. The route structs are shaped
+   exactly like `./routes`' `Placement`/`RouteDefinition`, so a decoded
+   topology feeds `makeRouteTable` with no assertion in between.
+   ============================================================ */
+
+/**
+ * A placement condition: WHO sees this placement, on what DEVICE, in what
+ * LOCALE. Three independent axes; an absent axis means `'any'` — the record
+ * stores only what narrows, and the resolution's `resolveCondition` makes the
+ * default explicit when it is asked (derive-fresh, never store). The literal
+ * string `'any'` is also admitted and means the same as absence, per the
+ * fixture's vocabulary. Two placements collide when ALL three axes overlap;
+ * see `./rules.ts` for the overlap rule.
+ */
+export const PlacementCondition = S.Struct({
+  who: S.optionalKey(S.String),
+  device: S.optionalKey(S.String),
+  locale: S.optionalKey(S.String),
+})
+export type PlacementCondition = typeof PlacementCondition.Type
+
+/** The spans a grid placement may take — 12/8/6/4/3 of twelve columns, the
+ *  spec's exact set. Meaningful in `grid` slots only. */
+export const PlacementSpan = S.Literals([12, 8, 6, 4, 3])
+export type PlacementSpan = typeof PlacementSpan.Type
+
+/**
+ * Where one MicroDot element goes — widened in Phase 5 from `{tag, slotId}`
+ * only as far as a shipping check or the reading-B resolution needs, per the
+ * phase design's table (work item 2). Every new field is `S.optionalKey`,
+ * because BOTH existing `host-topology.json` files must decode unchanged —
+ * backward compatibility is a hard requirement, pinned by the Phase-4-shaped
+ * decode test in `./wire.test.ts`.
+ *
+ * - `id`        — override provenance and screen selection. Absent on the
+ *                 Phase-4 records; the resolution synthesizes a stable one.
+ * - `values`    — attribute values this placement supplies (check 3). Absent
+ *                 means `{}`.
+ * - `condition` — who/device/locale (checks 4/7, the resolution). Absent
+ *                 means every axis `'any'`.
+ * - `envs`      — the environments the placement exists in (check 1's
+ *                 vocabulary, the same `WireEnv` wires use). Absent means all
+ *                 three.
+ * - `span`      — grid columns (grid slots only).
+ * - `order`     — stacking order within the slot.
+ *
+ * Deliberately NOT here, with their checks: `'@anchor'` + `selector` +
+ * `resolved` (check 5 needs a crawl) and `loading` (no check needs it and the
+ * runtime has one strategy — a stored `loading` the loader ignores would be a
+ * lie).
+ */
+export const TopologyPlacement = S.Struct({
+  id: S.optionalKey(S.String),
+  tag: S.String,
+  slotId: S.String,
+  values: S.optionalKey(S.Record(S.String, S.String)),
+  condition: S.optionalKey(PlacementCondition),
+  envs: S.optionalKey(S.Array(WireEnv)),
+  span: S.optionalKey(PlacementSpan),
+  order: S.optionalKey(S.Number),
+})
+export type TopologyPlacement = typeof TopologyPlacement.Type
+
+export const TopologyRoute = S.Struct({
+  path: S.String,
+  label: S.String,
+  title: S.String,
+  sectionIds: S.Array(S.String),
+  mounts: S.Array(TopologyPlacement),
+})
+export type TopologyRoute = typeof TopologyRoute.Type
+
+/** The fields every rule kind shares. Spread rather than nested so `kind`
+ *  stays a flat discriminant, matching the fixture's records. */
+const routeRuleFields = {
+  id: S.String,
+  label: S.String,
+  placements: S.Array(TopologyPlacement),
+}
+
+/**
+ * A ROUTE RULE places dots on many routes at once. Three kinds, the spec's
+ * exact vocabulary, each with its own match data:
+ *
+ * - `pattern` — a path glob (`/*`, `/blog/*`); only the `/*` suffix wildcard
+ *   exists.
+ * - `group`   — an explicit path list (the spec's "named collection").
+ * - `dynamic` — a `:param` template (`/docs/:slug`), matched segment-wise.
+ *
+ * The record is SCHEMA here beside the other topology records (a rule is
+ * topology data); the matcher and the resolution that consume it live in
+ * `./rules.ts` — defining the schema there instead would put `wire.ts` and
+ * `rules.ts` in a runtime import cycle, since `HostTopology` below needs this
+ * const at module evaluation.
+ *
+ * `ruleMatches` in `./rules.ts` is THE matcher (the phase's ruling 1): the
+ * runtime resolution and the Pages screen's match counts both call it, and
+ * nothing else may reimplement it.
+ */
+export const RouteRule = S.Union([
+  S.Struct({
+    ...routeRuleFields,
+    kind: S.Literal('pattern'),
+    pattern: S.String,
+  }),
+  S.Struct({
+    ...routeRuleFields,
+    kind: S.Literal('group'),
+    paths: S.Array(S.String),
+  }),
+  S.Struct({
+    ...routeRuleFields,
+    kind: S.Literal('dynamic'),
+    template: S.String,
+  }),
+])
+export type RouteRule = typeof RouteRule.Type
+
+/**
+ * The descriptor `makeRouteTable` derives an aggregate landing route from.
+ * Stored as a DESCRIPTOR rather than as the derived route itself: a stored
+ * copy of the union of every component route rots the day a route changes.
+ * `optionalKey` (not `optional`) so the decoded Type is exact-optional and
+ * assignable to `makeRouteTable`'s overview parameter under
+ * `exactOptionalPropertyTypes`.
+ */
+export const TopologyOverview = S.Struct({
+  path: S.String,
+  label: S.String,
+  title: S.String,
+  leadingSectionIds: S.optionalKey(S.Array(S.String)),
+})
+export type TopologyOverview = typeof TopologyOverview.Type
+
+/**
+ * Inputs the HOST itself owns — the activity log, remembered interview ids.
+ * They render distinctly on the Wiring canvas because no manifest declares
+ * them; `type` is free-form (`'append'` in the prototype) rather than a
+ * `WireValueType`, for the same reason.
+ */
+export const TopologyHost = S.Struct({
+  id: S.String,
+  label: S.String,
+  ownedInputs: S.Array(S.Struct({ name: S.String, type: S.String })),
+})
+export type TopologyHost = typeof TopologyHost.Type
+
+/**
+ * A whole host, as data: who it is, where its elements go, what is wired to
+ * what, and which events it merely watches (log-only taps — the demo host's
+ * wire-7 events). `routes` is non-empty by schema so `topologyRouteTable`
+ * below always has a fallback without an assertion.
+ *
+ * Phase 5 adds two keys, both `optionalKey` because a Phase-4 topology file
+ * must decode unchanged:
+ *
+ * - `slotManifest` — the theme's declared slots (see `./slots.ts`). Absent
+ *   means the topology predates the manifest; slot checks degrade honestly.
+ * - `rules` — route rules resolved by `./rules.ts`. Absent means no rules,
+ *   and `resolvePlacements` degrades to the identity: exactly the route's own
+ *   mounts, byte-identical to Phase 4 behaviour.
+ */
+export const HostTopology = S.Struct({
+  host: TopologyHost,
+  routes: S.NonEmptyArray(TopologyRoute),
+  overview: S.optionalKey(TopologyOverview),
+  slotManifest: S.optionalKey(HostSlotManifest),
+  rules: S.optionalKey(S.Array(RouteRule)),
+  wires: S.Array(Wire),
+  watch: S.Array(S.Struct({ event: S.String })),
+})
+export type HostTopology = typeof HostTopology.Type
+
+/**
+ * The ONE way a route table is built from a topology — both the demo host's
+ * entry and the Wiring dot's client-side derivation go through here, which is
+ * what keeps a wire whose two ends only share the DERIVED overview route
+ * deriving `live` identically everywhere.
+ *
+ * With an overview descriptor the fallback is derived by `makeRouteTable`;
+ * without one the first route is the fallback (`routes` is schema-guaranteed
+ * non-empty, and index 0 of a non-empty tuple type needs no `Option`).
+ *
+ * Phase 5: RULE-CARRIED placements fold into each matching route's mounts,
+ * through `ruleMatches` — THE matcher, never a reimplementation. Every
+ * table-derived join reads `route.mounts`: `unroutedTags`' startup throw,
+ * `findPlacement`, and `deriveWireState`'s mounts-both-ends check. Without
+ * the fold, a wire whose two ends ride a group rule would derive
+ * `never-fires` on the Wiring screen while the runtime mounts both ends —
+ * the screen lying about the runtime, the exact failure ruling 1 of the
+ * phase design exists to prevent. Rule placements come first (broadest
+ * layer, the resolution's own ordering); the table stays env-agnostic, so
+ * the fold is the plain union — the env- and condition-aware contest is
+ * `resolvePlacements`' job. A topology with no rules keeps the exact route
+ * objects it decoded: byte-identical to Phase 4.
+ */
+export const topologyRouteTable = (topology: HostTopology): RouteTable => {
+  const rules = topology.rules ?? []
+  const widen = (route: TopologyRoute): TopologyRoute =>
+    rules.length === 0
+      ? route
+      : {
+          ...route,
+          mounts: [
+            ...rules
+              .filter(rule => ruleMatches(rule, route.path))
+              .flatMap(rule => rule.placements),
+            ...route.mounts,
+          ],
+        }
+  return topology.overview === undefined
+    ? {
+        routes: topology.routes.map(widen),
+        fallback: widen(topology.routes[0]),
+      }
+    : makeRouteTable(topology.routes.map(widen), topology.overview)
+}
+
+/* ============================================================
+   Derived wire state — computed, never stored.
+   ============================================================ */
+
+/**
+ * - `live`        — verified against manifest data, types reconciled, and some
+ *                   route mounts both ends.
+ * - `never-fires` — well-formed, but no single route mounts both ends, so the
+ *                   event and its target are never on screen together.
+ * - `draft`       — a referenced tag/event/field/input is missing from the
+ *                   manifest data, the manifest for a referenced tag is absent
+ *                   (unverifiable ⇒ draft), or the type pairing is not
+ *                   reconciled by the transform.
+ */
+export type WireState = 'live' | 'never-fires' | 'draft'
+
+/**
+ * The slice of an emitted JSON Schema document this module reads: the
+ * top-level object schema's property map. Everything else in the document
+ * (`dialect`, `required`, `definitions`, …) is irrelevant to "does this field
+ * exist, and what primitive does it carry".
+ */
+const JsonSchemaDocument = S.Struct({
+  schema: S.Struct({
+    properties: S.optionalKey(S.Record(S.String, S.Unknown)),
+  }),
+})
+const decodeJsonSchemaDocument = S.decodeUnknownOption(JsonSchemaDocument)
+
+const JsonSchemaDirectType = S.Struct({ type: S.String })
+const decodeJsonSchemaDirectType = S.decodeUnknownOption(JsonSchemaDirectType)
+
+const JsonSchemaAnyOf = S.Struct({
+  anyOf: S.Array(
+    S.Struct({
+      type: S.optionalKey(S.String),
+      enum: S.optionalKey(S.Unknown),
+    }),
+  ),
+})
+const decodeJsonSchemaAnyOf = S.decodeUnknownOption(JsonSchemaAnyOf)
+
+/**
+ * The JSON Schema `type`s a property may carry, best effort. The emitter
+ * renders `S.Number` as an `anyOf` whose EXTRA branches are literal string
+ * encodings — `{type: 'string', enum: ['NaN']}`, `'Infinity'`, `'-Infinity'`.
+ * Counting those branch types would let `'string'` corroborate every numeric
+ * field, deriving a mistyped wire `live` when it can never fire (the exact
+ * "draft shown as live ⇒ silently dead broker" failure), so a branch carrying
+ * an `enum` key is an encoding artifact and its `type` does not count. An
+ * empty result means "could not tell" — the caller trusts the wire's
+ * declaration rather than failing a wire the tooling cannot see into.
+ */
+const jsonSchemaTypesOf = (property: unknown): ReadonlyArray<string> =>
+  Option.match(decodeJsonSchemaDirectType(property), {
+    onSome: direct => [direct.type],
+    onNone: () =>
+      Option.match(decodeJsonSchemaAnyOf(property), {
+        onSome: union =>
+          Array.getSomes(
+            union.anyOf.map(branch =>
+              branch.enum === undefined
+                ? Option.fromNullishOr(branch.type)
+                : Option.none(),
+            ),
+          ),
+        onNone: () => [],
+      }),
+  })
+
+/** Which JSON Schema `type`s corroborate each declared wire value type. */
+const JSON_TYPES_BY_VALUE_TYPE: Record<WireValueType, ReadonlyArray<string>> = {
+  string: ['string'],
+  enum: ['string'],
+  number: ['number', 'integer'],
+  boolean: ['boolean'],
+  // `json` encodes anything, so no JSON Schema type can contradict it.
+  json: [],
+}
+
+/**
+ * Verifies a payload field against the manifest event's `jsonSchema`.
+ *
+ * `jsonSchema` is OPTIONAL in manifests — the emitter omits it when a payload
+ * schema cannot be rendered. When it is absent (or carries no property map),
+ * there is nothing to verify against, so the wire's DECLARED `fieldType` is
+ * trusted rather than the wire being condemned to draft: an unverifiable
+ * declaration on the SOURCE side is the manifest's gap, not the wire's. A
+ * missing manifest or event, by contrast, means the referenced thing may not
+ * exist at all — that is draft, handled by the caller.
+ */
+const fieldChecksOut = (
+  event: ManifestEvent,
+  field: string,
+  declared: Option.Option<WireValueType>,
+): boolean =>
+  Option.match(decodeJsonSchemaDocument(event.payload.jsonSchema), {
+    onNone: () => true,
+    onSome: document => {
+      const properties = document.schema.properties
+      if (properties === undefined) {
+        return true
+      }
+      if (!Object.hasOwn(properties, field)) {
+        return false
+      }
+      return Option.match(declared, {
+        onNone: () => true,
+        onSome: valueType => {
+          const jsonTypes = jsonSchemaTypesOf(properties[field])
+          const corroborating = JSON_TYPES_BY_VALUE_TYPE[valueType]
+          if (jsonTypes.length === 0 || corroborating.length === 0) {
+            return true
+          }
+          return Array.some(corroborating, jsonType =>
+            Array.contains(jsonTypes, jsonType),
+          )
+        },
+      })
+    },
+  })
+
+const manifestFor = (
+  manifests: ReadonlyArray<ManifestTag>,
+  tag: string,
+): Option.Option<ManifestTag> =>
+  Array.findFirst(manifests, manifest => manifest.tag === tag)
+
+const eventFor = (
+  manifest: ManifestTag,
+  name: string,
+): Option.Option<ManifestEvent> =>
+  Array.findFirst(manifest.events, event => event.name === name)
+
+const attributeFor = (
+  manifest: ManifestTag,
+  name: string,
+): Option.Option<ManifestAttribute> =>
+  Array.findFirst(manifest.attributes, attribute => attribute.name === name)
+
+/**
+ * Whether the transform reconciles the declared type pairing:
+ *
+ * - `direct` and `condition` copy the field straight across, so
+ *   `fieldType === inputType`.
+ * - `lookup` re-maps the value entirely: valid into a `string` input
+ *   regardless of the source type, or into an `enum` input iff every row
+ *   value AND the fallback are members of the target attribute's declared
+ *   values (an undeclared value set cannot be verified ⇒ not reconciled).
+ */
+const transformReconciles = (
+  wire: Wire,
+  target: ManifestAttribute,
+): boolean => {
+  switch (wire.transform._tag) {
+    case 'direct':
+    case 'condition':
+      return wire.fieldType === wire.inputType
+    case 'lookup': {
+      if (wire.inputType === 'string') {
+        return true
+      }
+      if (wire.inputType !== 'enum') {
+        return false
+      }
+      const declaredValues = target.values
+      if (declaredValues === undefined) {
+        return false
+      }
+      const outputs = [
+        ...Object.values(wire.transform.rows),
+        wire.transform.fallback,
+      ]
+      return Array.every(outputs, value =>
+        Array.contains(declaredValues, value),
+      )
+    }
+  }
+}
+
+const routeMountsBothEnds = (table: RouteTable, wire: Wire): boolean =>
+  Array.some(
+    table.routes,
+    route =>
+      Array.some(route.mounts, mount => mount.tag === wire.from) &&
+      Array.some(route.mounts, mount => mount.tag === wire.to),
+  )
+
+/**
+ * Derives a wire's state fresh from the manifests and the route table —
+ * see `WireState` for what each state means and why none of this is stored.
+ *
+ * Draft on ANY unverifiable reference, including a wire whose declared
+ * `inputType` disagrees with the target attribute's manifest type: a stale
+ * declaration is indistinguishable from a wrong one, and the whole point of
+ * draft is "this record cannot be trusted to fire correctly".
+ */
+export const deriveWireState = (
+  wire: Wire,
+  context: {
+    readonly manifests: ReadonlyArray<ManifestTag>
+    readonly table: RouteTable
+  },
+): WireState => {
+  const verified = Option.match(manifestFor(context.manifests, wire.from), {
+    onNone: () => false,
+    onSome: fromManifest =>
+      Option.match(eventFor(fromManifest, wire.event), {
+        onNone: () => false,
+        onSome: event => {
+          if (!fieldChecksOut(event, wire.field, Option.some(wire.fieldType))) {
+            return false
+          }
+          // A condition's gate field is a payload reference too — existence
+          // only, because the wire declares no type for it.
+          if (
+            wire.transform._tag === 'condition' &&
+            !fieldChecksOut(event, wire.transform.field, Option.none())
+          ) {
+            return false
+          }
+          return Option.match(manifestFor(context.manifests, wire.to), {
+            onNone: () => false,
+            onSome: toManifest =>
+              Option.match(attributeFor(toManifest, wire.input), {
+                onNone: () => false,
+                onSome: target =>
+                  target.type === wire.inputType &&
+                  transformReconciles(wire, target),
+              }),
+          })
+        },
+      }),
+  })
+
+  if (!verified) {
+    return 'draft'
+  }
+  return routeMountsBothEnds(context.table, wire) ? 'live' : 'never-fires'
+}