@bespokeagentics/microdots-host 0.1.0 → 0.1.2

package/evals/topology-regressions.p5.v1.json

@@ -0,0 +1,105 @@
+{
+  "schemaVersion": 1,
+  "id": "microdots.topology-regressions.p5",
+  "corpusVersion": "p5.1",
+  "toolVersion": "compose-from-selection@1",
+  "surfaces": [
+    {
+      "tag": "readout-view",
+      "attributes": [
+        { "name": "symbol", "ownership": "dot" },
+        { "name": "api-url", "ownership": "environment" }
+      ],
+      "events": [
+        {
+          "name": "quote-changed",
+          "fields": { "symbol": "string" }
+        }
+      ]
+    },
+    {
+      "tag": "roster-backend",
+      "attributes": [{ "name": "refresh-token", "ownership": "dot" }],
+      "events": []
+    }
+  ],
+  "cases": [
+    {
+      "schemaVersion": 1,
+      "id": "topology.together",
+      "title": "Place both catalogued surfaces on one route",
+      "input": {
+        "hostId": "lead-capture",
+        "hostLabel": "Lead capture",
+        "tags": ["readout-view", "roster-backend"],
+        "layout": "together",
+        "slotKind": "band",
+        "wires": []
+      },
+      "expected": {
+        "hostId": "lead-capture",
+        "hostLabel": "Lead capture",
+        "generateCount": 0,
+        "routePaths": ["/"],
+        "mountedTags": ["readout-view", "roster-backend"],
+        "slotKinds": ["band", "band"],
+        "wirePlain": []
+      }
+    },
+    {
+      "schemaVersion": 1,
+      "id": "topology.per-tag",
+      "title": "Place one catalogued surface on each route",
+      "input": {
+        "hostId": "demo",
+        "hostLabel": "Demo",
+        "tags": ["readout-view", "roster-backend"],
+        "layout": "per-tag",
+        "slotKind": "rail",
+        "wires": []
+      },
+      "expected": {
+        "hostId": "demo",
+        "hostLabel": "Demo",
+        "generateCount": 0,
+        "routePaths": ["/readout-view", "/roster-backend"],
+        "mountedTags": ["readout-view", "roster-backend"],
+        "slotKinds": ["rail", "rail"],
+        "wirePlain": []
+      }
+    },
+    {
+      "schemaVersion": 1,
+      "id": "topology.direct-wire",
+      "title": "Materialize one catalogued direct wire",
+      "input": {
+        "brief": "Wire the readout quote into the roster refresh token.",
+        "hostId": "demo",
+        "hostLabel": "Demo",
+        "tags": ["readout-view", "roster-backend"],
+        "layout": "together",
+        "slotKind": "band",
+        "wires": [
+          {
+            "from": "readout-view",
+            "event": "quote-changed",
+            "field": "symbol",
+            "to": "roster-backend",
+            "input": "refresh-token"
+          }
+        ]
+      },
+      "expected": {
+        "hostId": "demo",
+        "hostLabel": "Demo",
+        "generateCount": 0,
+        "routePaths": ["/"],
+        "mountedTags": ["readout-view", "roster-backend"],
+        "slotKinds": ["band", "band"],
+        "wirePlain": [
+          "When quote-changed on readout-view, set refresh-token on roster-backend."
+        ]
+      }
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bespokeagentics/microdots-host",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "MicroDots host shell — registry, loader, slot manifest and placement checks for mounting MicroDot custom elements. Raw TypeScript source; consume with Bun or Vite.",
   "type": "module",
   "license": "Apache-2.0",
@@ -10,14 +10,16 @@
     "directory": "packages/microdots-host"
   },
   "publishConfig": {
-    "access": "public"
+    "access": "restricted"
   },
   "main": "./src/index.ts",
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./composition": "./src/compositionSpec.ts"
   },
   "dependencies": {
-    "@bespokeagentics/microdots-element": "0.1.0"
+    "@bespokeagentics/microdots-authoring": "0.1.1",
+    "@bespokeagentics/microdots-element": "0.1.1"
   },
   "peerDependencies": {
     "effect": "4.0.0-rc.108"

package/src/composeFromSelection.test.ts

@@ -0,0 +1,277 @@
+import { describe, expect, test } from 'vitest'
+
+import { decodeCatalogLockSync } from '@bespokeagentics/microdots-authoring'
+import type {
+  ManifestAttribute,
+  ManifestEvent,
+  ManifestTag,
+} from '@bespokeagentics/microdots-element'
+
+import {
+  composeExistingSurfacesFromSelection,
+  composeFromSelection,
+  eventFieldsOf,
+  wireableAttributesOf,
+} from './composeFromSelection.ts'
+import { FillCompositionError } from './fillComposition.ts'
+
+const attribute = (
+  name: string,
+  ownership: ManifestAttribute['ownership'] = 'dot',
+): ManifestAttribute => ({
+  name,
+  type: 'string',
+  required: false,
+  live: true,
+  ownership,
+})
+
+const manifestEvent = (
+  name: string,
+  properties: Readonly<Record<string, unknown>>,
+): ManifestEvent => ({
+  name,
+  payload: {
+    ref: `@microdots/test/contract#${name}`,
+    jsonSchema: {
+      dialect: 'draft-2020-12',
+      schema: { type: 'object', properties },
+      definitions: {},
+    },
+  },
+})
+
+const PRICE: ManifestTag = {
+  tag: 'readout-view',
+  attributes: [attribute('symbol'), attribute('api-url', 'environment')],
+  events: [manifestEvent('quote-changed', { symbol: { type: 'string' } })],
+}
+
+const FLEET: ManifestTag = {
+  tag: 'fleet-health',
+  attributes: [attribute('region')],
+  events: [],
+}
+
+const SURFACES: ReadonlyArray<ManifestTag> = [PRICE, FLEET]
+
+const CATALOG_LOCK = decodeCatalogLockSync({
+  schemaVersion: 1,
+  snapshotSha256: 'a'.repeat(64),
+  compilerVersion: '1.2.1-p6',
+  shapeDigests: {},
+  capabilityDigests: {},
+  backendCatalogDigest: 'b'.repeat(64),
+  targetMatrixDigest: 'c'.repeat(64),
+  allocationBaselineDigest: 'd'.repeat(64),
+})
+
+describe('eventFieldsOf', () => {
+  test('reads nested draft-2020-12 properties', () => {
+    const event = PRICE.events[0]
+    expect(event).toBeDefined()
+    if (event === undefined) {
+      return
+    }
+    expect(eventFieldsOf(event)).toEqual([{ name: 'symbol', type: 'string' }])
+  })
+})
+
+describe('wireableAttributesOf', () => {
+  test('drops environment-owned attributes', () => {
+    expect(wireableAttributesOf(PRICE).map(item => item.name)).toEqual([
+      'symbol',
+    ])
+  })
+})
+
+describe('composeFromSelection', () => {
+  test('emits catalog-locked v2 for new existing-surface traffic', () => {
+    const spec = composeExistingSurfacesFromSelection(
+      {
+        hostId: 'lead-capture',
+        hostLabel: 'Lead capture',
+        tags: ['readout-view', 'fleet-health'],
+        layout: 'together',
+        slotKind: 'band',
+        wires: [],
+      },
+      SURFACES,
+      CATALOG_LOCK,
+    )
+
+    expect(spec.schemaVersion).toBe(2)
+    expect(spec.generate).toEqual([])
+    expect(spec.catalogLock).toEqual(CATALOG_LOCK)
+  })
+
+  test('places every selected tag on one route when layout is together', () => {
+    const spec = composeFromSelection(
+      {
+        hostId: 'lead-capture',
+        hostLabel: 'Lead capture',
+        tags: ['readout-view', 'fleet-health'],
+        layout: 'together',
+        slotKind: 'band',
+        wires: [],
+      },
+      SURFACES,
+    )
+    expect(spec.generate).toEqual([])
+    expect(spec.topology.host).toEqual({
+      id: 'lead-capture',
+      label: 'Lead capture',
+      ownedInputs: [],
+    })
+    expect(spec.topology.routes).toHaveLength(1)
+    expect(spec.topology.routes[0]?.path).toBe('/')
+    expect(spec.topology.routes[0]?.mounts.map(mount => mount.tag)).toEqual([
+      'readout-view',
+      'fleet-health',
+    ])
+    expect(spec.topology.slotManifest?.theme).toEqual({
+      name: '@bespokeagentics/microdots-theme',
+      version: '0.1.1',
+    })
+  })
+
+  test('one route per tag when layout is per-tag', () => {
+    const spec = composeFromSelection(
+      {
+        hostId: 'demo',
+        hostLabel: 'Demo',
+        tags: ['readout-view', 'fleet-health'],
+        layout: 'per-tag',
+        slotKind: 'rail',
+        wires: [],
+      },
+      SURFACES,
+    )
+    expect(spec.topology.routes.map(route => route.path)).toEqual([
+      '/readout-view',
+      '/fleet-health',
+    ])
+    expect(spec.topology.slotManifest?.slots.map(slot => slot.kind)).toEqual([
+      'rail',
+      'rail',
+    ])
+  })
+
+  test('fills a catalogued wire and never invents generate[]', () => {
+    const spec = composeFromSelection(
+      {
+        brief: 'Wire the ticker into the fleet region.',
+        hostId: 'demo',
+        hostLabel: 'Demo',
+        tags: ['readout-view', 'fleet-health'],
+        layout: 'together',
+        slotKind: 'band',
+        wires: [
+          {
+            from: 'readout-view',
+            event: 'quote-changed',
+            field: 'symbol',
+            to: 'fleet-health',
+            input: 'region',
+          },
+        ],
+      },
+      SURFACES,
+    )
+    expect(spec.generate).toEqual([])
+    expect(spec.brief).toBe('Wire the ticker into the fleet region.')
+    expect(spec.topology.wires).toEqual([
+      {
+        id: 'w1',
+        from: 'readout-view',
+        event: 'quote-changed',
+        field: 'symbol',
+        fieldType: 'string',
+        to: 'fleet-health',
+        input: 'region',
+        inputType: 'string',
+        transform: { _tag: 'direct' },
+        envs: ['dev', 'preview', 'prod'],
+        plain:
+          'When quote-changed on readout-view, set region on fleet-health.',
+      },
+    ])
+  })
+
+  test('refuses a tag that is not in the catalog', () => {
+    try {
+      composeFromSelection(
+        {
+          hostId: 'demo',
+          hostLabel: 'Demo',
+          tags: ['weather-5day-forecast'],
+          layout: 'together',
+          slotKind: 'band',
+          wires: [],
+        },
+        SURFACES,
+      )
+      expect.unreachable('unknown tags must fail')
+    } catch (error) {
+      expect(error).toBeInstanceOf(FillCompositionError)
+      if (error instanceof FillCompositionError) {
+        expect(error.failure._tag).toBe('invalid')
+        if (error.failure._tag === 'invalid') {
+          expect(error.failure.issues[0]?.message).toContain(
+            'weather-5day-forecast',
+          )
+          expect(error.failure.issues[0]?.message).toContain('catalog')
+        }
+      }
+    }
+  })
+
+  test('refuses an empty selection', () => {
+    expect(() =>
+      composeFromSelection(
+        {
+          hostId: 'demo',
+          hostLabel: 'Demo',
+          tags: [],
+          layout: 'together',
+          slotKind: 'band',
+          wires: [],
+        },
+        SURFACES,
+      ),
+    ).toThrow(FillCompositionError)
+  })
+
+  test('refuses a wire to an environment-owned attribute', () => {
+    try {
+      composeFromSelection(
+        {
+          hostId: 'demo',
+          hostLabel: 'Demo',
+          tags: ['readout-view', 'fleet-health'],
+          layout: 'together',
+          slotKind: 'band',
+          wires: [
+            {
+              from: 'readout-view',
+              event: 'quote-changed',
+              field: 'symbol',
+              to: 'readout-view',
+              input: 'api-url',
+            },
+          ],
+        },
+        SURFACES,
+      )
+      expect.unreachable('environment inputs must fail')
+    } catch (error) {
+      expect(error).toBeInstanceOf(FillCompositionError)
+      if (
+        error instanceof FillCompositionError &&
+        error.failure._tag === 'invalid'
+      ) {
+        expect(error.failure.issues[0]?.message).toContain('api-url')
+      }
+    }
+  })
+})