@bespokeagentics/microdots-host 0.1.0 → 0.1.2

package/src/compositionSpec.v2.test.ts

@@ -0,0 +1,216 @@
+import { describe, expect, test } from 'vitest'
+
+import {
+  type ResolvedMicroDotSpecV2,
+  decodeCatalogLockSync,
+  decodeResolvedMicroDotSpecSync,
+} from '@bespokeagentics/microdots-authoring'
+
+import {
+  type CompositionSpecV1,
+  type CompositionSpecV2,
+  decodeCompositionSpecSync,
+  decodeCompositionSpecVersionedSync,
+  encodeCompositionSpecV2Sync,
+  migrateCompositionSpecV1,
+  validateExistingSurfaceComposition,
+} from './compositionSpec.ts'
+import type { HostTopology } from './wire.ts'
+
+const topology: HostTopology = {
+  host: { id: 'host', label: 'Host', ownedInputs: [] },
+  routes: [
+    {
+      path: '/',
+      label: 'Home',
+      title: 'Home',
+      sectionIds: ['main'],
+      mounts: [],
+    },
+  ],
+  wires: [],
+  watch: [],
+}
+
+const lock = decodeCatalogLockSync({
+  schemaVersion: 1,
+  snapshotSha256: 'a'.repeat(64),
+  compilerVersion: '0.1.0',
+  shapeDigests: { 'shape:view@1': 'e'.repeat(64) },
+  capabilityDigests: {},
+  backendCatalogDigest: 'b'.repeat(64),
+  targetMatrixDigest: 'c'.repeat(64),
+  allocationBaselineDigest: 'd'.repeat(64),
+})
+
+const resolved = (catalogLock = lock): ResolvedMicroDotSpecV2 =>
+  decodeResolvedMicroDotSpecSync({
+    schemaVersion: 2,
+    slug: 'quote-board',
+    domain: {
+      schemaVersion: 1,
+      entity: {
+        name: 'Quote',
+        pluralName: 'Quotes',
+        identityField: 'symbol',
+      },
+      fields: [
+        {
+          id: 'symbol',
+          key: 'symbol',
+          label: 'Symbol',
+          kind: 'text',
+          required: true,
+          constraints: {},
+        },
+      ],
+      operations: [],
+    },
+    surfaces: [
+      {
+        shape: 'shape:view@1',
+        subject: 'quote',
+        parameters: {},
+        tag: 'quote-board-view',
+      },
+    ],
+    backend: {
+      tag: 'quote-board-backend',
+      layout: {
+        rootId: 'records',
+        nodes: [
+          {
+            id: 'records',
+            primitive: 'records-table@1',
+            parameters: {},
+          },
+        ],
+      },
+    },
+    capabilityClosure: [],
+    target: {
+      id: 'cloudflare-worker@1',
+      provider: 'cloudflare',
+      runtime: 'worker',
+      support: 'supported',
+      proof: 'preflight',
+      requiredArtifacts: ['service/worker.ts'],
+      requiredBindings: [],
+      requiredSecrets: [],
+      acknowledgedConsequences: [],
+    },
+    identity: {
+      packageName: '@microdots/quote-board',
+      bundleName: 'quote-board.js',
+      port: 3116,
+      frontTags: ['quote-board-view'],
+      backendTag: 'quote-board-backend',
+    },
+    catalogLock,
+    provenance: {
+      selectedBy: 'human',
+      client: 'workbench',
+    },
+  })
+
+const v1 = (
+  generate: CompositionSpecV1['generate'] = [],
+): CompositionSpecV1 => ({
+  schemaVersion: 1,
+  generate,
+  topology,
+})
+
+describe('CompositionSpec v1/v2 boundary', () => {
+  test('preserves the existing v1 decoder', () => {
+    expect(decodeCompositionSpecSync(v1())).toEqual(v1())
+  })
+
+  test('migrates topology-only v1 exactly under an explicit catalog lock', () => {
+    const result = migrateCompositionSpecV1(v1(), lock)
+    expect(result._tag).toBe('migrated')
+    if (result._tag !== 'migrated') {
+      throw new Error('expected topology-only migration to succeed')
+    }
+    expect(result.value).toEqual({
+      schemaVersion: 2,
+      generate: [],
+      topology,
+      catalogLock: lock,
+    })
+    expect(decodeCompositionSpecVersionedSync(result.value)).toEqual(
+      result.value,
+    )
+  })
+
+  test('does not invent missing v1 generation semantics', () => {
+    const result = migrateCompositionSpecV1(
+      v1([{ slug: 'quote', tag: 'quote-view', port: 3990 }]),
+      lock,
+    )
+    expect(result._tag).toBe('needs-input')
+    if (result._tag !== 'needs-input') {
+      throw new Error('expected migration input to be required')
+    }
+    expect(result.diagnostic.code).toBe('migration-input-required')
+    expect(result.diagnostic.destinationMutated).toBe(false)
+  })
+
+  test('decodes and encodes v2 without cutting over the v1 API', () => {
+    const generated: ReadonlyArray<ResolvedMicroDotSpecV2> = [resolved()]
+    const spec: CompositionSpecV2 = {
+      schemaVersion: 2,
+      generate: generated,
+      topology,
+      catalogLock: lock,
+    }
+    expect(decodeCompositionSpecVersionedSync(spec)).toEqual(spec)
+    expect(encodeCompositionSpecV2Sync(spec)).toEqual(spec)
+  })
+
+  test('accepts only topology-only v2 in the existing-surface lane', () => {
+    expect(
+      validateExistingSurfaceComposition(
+        {
+          schemaVersion: 2,
+          generate: [],
+          topology,
+          catalogLock: lock,
+        },
+        [],
+      ),
+    ).toEqual([])
+
+    expect(
+      validateExistingSurfaceComposition(
+        {
+          schemaVersion: 2,
+          generate: [resolved()],
+          topology,
+          catalogLock: lock,
+        },
+        [],
+      ),
+    ).toContainEqual({
+      path: 'generate',
+      message:
+        'existing-surface composition requires generate[] to be empty; use the application-authoring compiler for new MicroDots',
+    })
+  })
+
+  test('rejects generated specs locked to a different catalog snapshot', () => {
+    const otherLock = decodeCatalogLockSync({
+      ...lock,
+      snapshotSha256: 'f'.repeat(64),
+    })
+
+    expect(() =>
+      decodeCompositionSpecVersionedSync({
+        schemaVersion: 2,
+        generate: [resolved()],
+        topology,
+        catalogLock: otherLock,
+      }),
+    ).toThrow()
+  })
+})

package/src/fillComposition.test.ts

@@ -0,0 +1,240 @@
+import { describe, expect, test } from 'vitest'
+
+import type {
+  ManifestAttribute,
+  ManifestEvent,
+  ManifestTag,
+} from '@bespokeagentics/microdots-element'
+
+import type { CompositionSpec } from './compositionSpec.ts'
+import { schemaEventsFor } from './compositionSpec.ts'
+import {
+  FillCompositionError,
+  compositionPrompt,
+  fillComposition,
+  liveFillPrompt,
+} from './fillComposition.ts'
+import type { HostTopology, Wire } from './wire.ts'
+
+const attribute = (name: string): ManifestAttribute => ({
+  name,
+  type: 'string',
+  required: false,
+  live: true,
+  ownership: 'dot',
+})
+
+const manifestEvent = (name: string, field: string): ManifestEvent => ({
+  name,
+  payload: {
+    ref: `@microdots/test/contract#${name}`,
+    jsonSchema: {
+      dialect: 'draft-2020-12',
+      schema: { type: 'object', properties: { [field]: { type: 'string' } } },
+      definitions: {},
+    },
+  },
+})
+
+const SURFACES: ReadonlyArray<ManifestTag> = [
+  {
+    tag: 'readout-view',
+    attributes: [attribute('symbol')],
+    events: [manifestEvent('quote-changed', 'symbol')],
+  },
+  {
+    tag: 'fleet-health',
+    attributes: [attribute('region')],
+    events: [],
+  },
+]
+
+const wire: Wire = {
+  id: 'w1',
+  from: 'readout-view',
+  event: 'quote-changed',
+  field: 'symbol',
+  fieldType: 'string',
+  to: 'fleet-health',
+  input: 'region',
+  inputType: 'string',
+  transform: {
+    _tag: 'lookup',
+    rows: { FOLD: 'us-east' },
+    fallback: 'us-east',
+  },
+  envs: ['dev'],
+  plain: 'When the quote changes, set the region.',
+}
+
+const topology: HostTopology = {
+  host: { id: 'demo-host', label: 'Demo', ownedInputs: [] },
+  routes: [
+    {
+      path: '/price',
+      label: 'Price',
+      title: 'Price',
+      sectionIds: ['section-price'],
+      mounts: [{ tag: 'readout-view', slotId: 'price-slot' }],
+    },
+    {
+      path: '/fleet',
+      label: 'Fleet',
+      title: 'Fleet',
+      sectionIds: ['section-fleet'],
+      mounts: [{ tag: 'fleet-health', slotId: 'fleet-slot' }],
+    },
+  ],
+  slotManifest: {
+    theme: { name: '@bespokeagentics/microdots-theme', version: '0.1.0' },
+    slots: [
+      { id: 'price-slot', kind: 'band', row: 1, capacity: 1 },
+      { id: 'fleet-slot', kind: 'band', row: 1, capacity: 1 },
+    ],
+  },
+  wires: [wire],
+  watch: [],
+}
+
+const gold: CompositionSpec = {
+  schemaVersion: 1,
+  brief: 'Wire the ticker into the fleet region.',
+  generate: [],
+  topology,
+}
+
+describe('compositionPrompt', () => {
+  test('is the brief plus the schema instruction — not the wiki', () => {
+    const prompt = compositionPrompt('compose price and fleet')
+    expect(prompt).toContain('Brief: compose price and fleet')
+    expect(prompt).toContain('JSON Schema')
+    expect(prompt).toContain('generate must be []')
+    expect(prompt).not.toContain('AGENTS.md')
+  })
+
+  test('offers the coordinated current theme version in the live JSON shape', () => {
+    expect(liveFillPrompt('compose price and fleet', SURFACES)).toContain(
+      '"version":"0.1.1"',
+    )
+  })
+})
+
+describe('fillComposition', () => {
+  test('decodes and validates a stub that honours the schema', () => {
+    const spec = fillComposition({
+      brief: gold.brief ?? '',
+      surfaces: SURFACES,
+      complete: (prompt, schema) => {
+        expect(prompt).toContain('Wire the ticker')
+        expect(schemaEventsFor(schema, 'readout-view')).toEqual([
+          'quote-changed',
+        ])
+        expect(schemaEventsFor(schema, 'readout-view')).not.toContain(
+          'bid-placed',
+        )
+        return JSON.stringify(gold)
+      },
+    })
+    expect(spec).toEqual(gold)
+  })
+
+  test('rejects non-JSON', () => {
+    expect(() =>
+      fillComposition({
+        brief: 'x',
+        surfaces: SURFACES,
+        complete: () => 'not json',
+      }),
+    ).toThrow(FillCompositionError)
+    try {
+      fillComposition({
+        brief: 'x',
+        surfaces: SURFACES,
+        complete: () => 'not json',
+      })
+    } catch (error) {
+      expect(error).toBeInstanceOf(FillCompositionError)
+      if (error instanceof FillCompositionError) {
+        expect(error.failure._tag).toBe('invalid-json')
+      }
+    }
+  })
+
+  test('rejects a value the Effect schema will not decode', () => {
+    try {
+      fillComposition({
+        brief: 'x',
+        surfaces: SURFACES,
+        complete: () => JSON.stringify({ schemaVersion: 2 }),
+      })
+      expect.unreachable('decode should fail')
+    } catch (error) {
+      expect(error).toBeInstanceOf(FillCompositionError)
+      if (error instanceof FillCompositionError) {
+        expect(error.failure._tag).toBe('decode-failed')
+      }
+    }
+  })
+
+  test('rejects a draft wire even when JSON Schema was bypassed', () => {
+    const bogus: CompositionSpec = {
+      ...gold,
+      topology: {
+        ...topology,
+        wires: [{ ...wire, event: 'bid-placed' }],
+      },
+    }
+    try {
+      fillComposition({
+        brief: 'x',
+        surfaces: SURFACES,
+        complete: () => JSON.stringify(bogus),
+      })
+      expect.unreachable('validate should 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]?.path).toBe('topology.wires[0]')
+        }
+      }
+    }
+  })
+
+  test('refuses an invented mount tag even when JSON Schema was bypassed', () => {
+    const bogus: CompositionSpec = {
+      ...gold,
+      topology: {
+        ...topology,
+        routes: [
+          ...topology.routes,
+          {
+            path: '/weather',
+            label: 'Weather',
+            title: 'Weather',
+            sectionIds: ['section-weather'],
+            mounts: [{ tag: 'weather-5day-forecast', slotId: 'price-slot' }],
+          },
+        ],
+      },
+    }
+    try {
+      fillComposition({
+        brief: 'rainy weather',
+        surfaces: SURFACES,
+        complete: () => JSON.stringify(bogus),
+      })
+      expect.unreachable('invented tags must fail')
+    } catch (error) {
+      expect(error).toBeInstanceOf(FillCompositionError)
+      if (
+        error instanceof FillCompositionError &&
+        error.failure._tag === 'invalid'
+      ) {
+        expect(error.message).toContain('weather-5day-forecast')
+        expect(error.message).not.toContain('topology.routes')
+      }
+    }
+  })
+})

package/src/fillComposition.ts

@@ -0,0 +1,159 @@
+import type { ManifestTag } from '@bespokeagentics/microdots-element'
+
+import {
+  type CompositionIssue,
+  type CompositionSpec,
+  type JsonSchema,
+  compositionJsonSchema,
+  decodeCompositionSpecSync,
+  validateComposition,
+} from './compositionSpec.ts'
+
+/**
+ * The entire generate-time prompt. Legal names live in the JSON Schema
+ * (`compositionJsonSchema`); this text is the brief plus that instruction.
+ * See `wiki/plans/active/microdots-specialist-spec-filler.md`.
+ */
+export const compositionPrompt = (brief: string): string =>
+  [
+    'Emit a CompositionSpec JSON object and nothing else.',
+    'Legal tags, events, attributes and transforms are in the JSON Schema.',
+    'Do not invent names. Use only catalogued tags. generate must be [].',
+    `Brief: ${brief}`,
+  ].join('\n')
+
+/** Compact catalog for a live model that cannot take a JSON Schema grammar. */
+export const compositionVocabulary = (
+  surfaces: ReadonlyArray<ManifestTag>,
+): string =>
+  surfaces
+    .map(surface => {
+      const events =
+        surface.events.map(event => event.name).join(', ') || '(none)'
+      const attributes =
+        surface.attributes.map(attribute => attribute.name).join(', ') ||
+        '(none)'
+      return `- ${surface.tag}: events [${events}]; attributes [${attributes}]`
+    })
+    .join('\n')
+
+export const liveFillPrompt = (
+  brief: string,
+  surfaces: ReadonlyArray<ManifestTag>,
+): string =>
+  [
+    compositionPrompt(brief),
+    '',
+    'Catalogued tags (use only these; do not invent tags, events or attributes):',
+    compositionVocabulary(surfaces),
+    '',
+    'generate must be []. Every mount and wire tag must be a catalogued tag.',
+    'JSON shape:',
+    '{"schemaVersion":1,"brief":"...","generate":[],"topology":{"host":{"id":"composed","label":"Composed","ownedInputs":[]},"routes":[{"path":"/readout","label":"Readout","title":"Readout","sectionIds":["section-readout"],"mounts":[{"tag":"readout-view","slotId":"readout-slot"}]}],"slotManifest":{"theme":{"name":"@bespokeagentics/microdots-theme","version":"0.1.1"},"slots":[{"id":"readout-slot","kind":"band","row":1,"capacity":1}]},"wires":[{"id":"w1","from":"readout-view","event":"quote-changed","field":"symbol","fieldType":"string","to":"roster-backend","input":"refresh-token","inputType":"string","transform":{"_tag":"direct"},"envs":["dev","preview","prod"],"plain":"When the quote changes, refresh the roster backend."}],"watch":[]}}',
+    'transform is {"_tag":"direct"} or {"_tag":"lookup","rows":{...},"fallback":"..."} or {"_tag":"condition","field":"...","op":"is","value":"..."}.',
+    'envs is ["dev","preview","prod"]. Slot kind is band. fieldType and inputType are string, number, boolean, json, or enum.',
+  ].join('\n')
+
+/** Strip fences and surrounding prose so a small model can narrate. */
+export const extractCompositionJson = (answer: string): string => {
+  const trimmed = answer
+    .trim()
+    .replace(/^```(?:json)?\s*/u, '')
+    .replace(/\s*```$/u, '')
+  const start = trimmed.indexOf('{')
+  const end = trimmed.lastIndexOf('}')
+  return start !== -1 && end > start ? trimmed.slice(start, end + 1) : trimmed
+}
+
+/**
+ * Test seam for a constrained decoder. Production will pass a model call
+ * that honours `schema`; tests pass a stub. The adapter never writes files.
+ */
+export type CompleteCompositionJson = (
+  prompt: string,
+  schema: JsonSchema,
+) => string
+
+export type FillCompositionFailure =
+  | { readonly _tag: 'invalid-json'; readonly detail: string }
+  | { readonly _tag: 'decode-failed'; readonly detail: string }
+  | {
+      readonly _tag: 'invalid'
+      readonly issues: ReadonlyArray<CompositionIssue>
+    }
+
+export class FillCompositionError extends Error {
+  readonly name = 'FillCompositionError'
+  /**
+   * Declared and assigned, NOT a `constructor(readonly failure: …)` parameter
+   * property. A parameter property is TS syntax that needs code GENERATED for
+   * it, and node's type stripping is strip-only — so the moment this module
+   * joined a vite config's import chain it killed `bun run build` with
+   * `ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX` while every other gate stayed green.
+   * Third instance of the same hazard class; see
+   * `wiki/patterns-and-traps/a-workspace-package-import-kills-a-vite-config.md`.
+   */
+  readonly failure: FillCompositionFailure
+
+  constructor(failure: FillCompositionFailure) {
+    super(fillFailureMessage(failure))
+    this.failure = failure
+  }
+}
+
+const fillFailureMessage = (failure: FillCompositionFailure): string => {
+  switch (failure._tag) {
+    case 'invalid-json':
+    case 'decode-failed':
+      return failure.detail
+    case 'invalid':
+      return failure.issues.map(issue => issue.message).join(' ')
+  }
+}
+
+const detailOf = (cause: unknown, fallback: string): string =>
+  cause instanceof Error ? cause.message : fallback
+
+export type FillCompositionOptions = {
+  readonly brief: string
+  readonly surfaces: ReadonlyArray<ManifestTag>
+  readonly complete: CompleteCompositionJson
+  /** Closed over the catalog when false (the Workbench picker). Default false. */
+  readonly allowNewTags?: boolean
+}
+
+/**
+ * Constrained-decode a CompositionSpec. Fail closed: malformed JSON, a
+ * value the Effect schema rejects, or a draft wire never reach the compiler.
+ */
+export const fillComposition = (
+  options: FillCompositionOptions,
+): CompositionSpec => {
+  const schema = compositionJsonSchema(options.surfaces, {
+    allowNewTags: options.allowNewTags ?? false,
+  })
+  const raw = options.complete(compositionPrompt(options.brief), schema)
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch (cause) {
+    throw new FillCompositionError({
+      _tag: 'invalid-json',
+      detail: detailOf(cause, 'JSON.parse failed'),
+    })
+  }
+  let spec: CompositionSpec
+  try {
+    spec = decodeCompositionSpecSync(parsed)
+  } catch (cause) {
+    throw new FillCompositionError({
+      _tag: 'decode-failed',
+      detail: detailOf(cause, 'CompositionSpec decode failed'),
+    })
+  }
+  const issues = validateComposition(spec, options.surfaces)
+  if (issues.length > 0) {
+    throw new FillCompositionError({ _tag: 'invalid', issues })
+  }
+  return spec
+}