@bespokeagentics/microdots-host 0.1.0 → 0.1.2

package/src/compositionSpec.ts

@@ -0,0 +1,802 @@
+import { Array, Option, Schema as S } from 'effect'
+
+import {
+  AvailableMicroDotSlug,
+  type CatalogLockV1,
+  CatalogLockV1 as CatalogLockV1Schema,
+  type MigrationResult,
+  ResolvedMicroDotSpecV2 as ResolvedMicroDotSpecV2Schema,
+  decodeAuthoringDiagnosticSync,
+  migrated,
+  migrationNeedsInput,
+} from '@bespokeagentics/microdots-authoring'
+import type { ManifestTag } from '@bespokeagentics/microdots-element'
+
+import { HostTopology, deriveWireState, topologyRouteTable } from './wire.ts'
+
+/**
+ * The composition IR a spec-filler emits and the compiler consumes.
+ *
+ * `topology` is the already-shipping host record. `generate` names new
+ * MicroDots the compiler should scaffold; tags that appear in the topology
+ * but not here must already exist in the surface catalog. The model never
+ * writes source files — see
+ * `wiki/plans/active/microdots-specialist-spec-filler.md`.
+ */
+export const GenerateDotSpecV1 = S.Struct({
+  slug: AvailableMicroDotSlug,
+  tag: S.NonEmptyString.check(S.isPattern(/^[a-z][a-z0-9]*(?:-[a-z0-9]+)+$/)),
+  port: S.Int.check(S.isGreaterThan(0)),
+})
+export type GenerateDotSpecV1 = typeof GenerateDotSpecV1.Type
+
+/** @deprecated v1 compatibility name; new authoring uses ResolvedMicroDotSpecV2. */
+export const GenerateDotSpec = GenerateDotSpecV1
+/** @deprecated v1 compatibility name; new authoring uses ResolvedMicroDotSpecV2. */
+export type GenerateDotSpec = GenerateDotSpecV1
+
+export const CompositionSpecV1 = S.Struct({
+  schemaVersion: S.Literal(1),
+  brief: S.optionalKey(S.String),
+  generate: S.Array(GenerateDotSpecV1),
+  topology: HostTopology,
+})
+export type CompositionSpecV1 = typeof CompositionSpecV1.Type
+
+/** Legacy read/caller contract; new Workbench traffic uses explicit v2. */
+export const CompositionSpec = CompositionSpecV1
+/** Legacy read/caller contract; new Workbench traffic uses explicit v2. */
+export type CompositionSpec = CompositionSpecV1
+
+const CompositionSpecV2Base = S.Struct({
+  schemaVersion: S.Literal(2),
+  brief: S.optionalKey(S.String),
+  generate: S.Array(ResolvedMicroDotSpecV2Schema),
+  topology: HostTopology,
+  catalogLock: CatalogLockV1Schema,
+})
+
+const sameDigestRecord = (
+  left: Readonly<Record<string, string>>,
+  right: Readonly<Record<string, string>>,
+): boolean => {
+  const leftKeys = Object.keys(left)
+  return (
+    leftKeys.length === Object.keys(right).length &&
+    leftKeys.every(key => left[key] === right[key])
+  )
+}
+
+export const catalogLocksEqual = (
+  left: CatalogLockV1,
+  right: CatalogLockV1,
+): boolean =>
+  left.schemaVersion === right.schemaVersion &&
+  left.snapshotSha256 === right.snapshotSha256 &&
+  left.compilerVersion === right.compilerVersion &&
+  sameDigestRecord(left.shapeDigests, right.shapeDigests) &&
+  sameDigestRecord(left.capabilityDigests, right.capabilityDigests) &&
+  left.backendCatalogDigest === right.backendCatalogDigest &&
+  left.targetMatrixDigest === right.targetMatrixDigest &&
+  left.allocationBaselineDigest === right.allocationBaselineDigest
+
+export const CompositionSpecV2 = CompositionSpecV2Base.check(
+  S.makeFilter(
+    spec =>
+      spec.generate.every(generated =>
+        catalogLocksEqual(generated.catalogLock, spec.catalogLock),
+      ),
+    { expected: 'every generated MicroDot uses the composition catalog lock' },
+  ),
+)
+export type CompositionSpecV2 = typeof CompositionSpecV2.Type
+
+export const CompositionSpecVersioned = S.Union([
+  CompositionSpecV1,
+  CompositionSpecV2,
+])
+export type CompositionSpecVersioned = typeof CompositionSpecVersioned.Type
+
+export type CompositionIssue = {
+  readonly path: string
+  readonly message: string
+}
+
+const issue = (path: string, message: string): CompositionIssue => ({
+  path,
+  message,
+})
+
+const tagOf = (surface: ManifestTag): string => surface.tag
+
+const knownTags = (
+  spec: CompositionSpec,
+  surfaces: ReadonlyArray<ManifestTag>,
+): ReadonlySet<string> => {
+  const tags = new Set<string>(surfaces.map(tagOf))
+  for (const generated of spec.generate) {
+    tags.add(generated.tag)
+  }
+  return tags
+}
+
+const duplicatePaths = (
+  values: ReadonlyArray<string>,
+  pathOf: (index: number) => string,
+  label: string,
+): ReadonlyArray<CompositionIssue> => {
+  const seen = new Map<string, number>()
+  const issues: Array<CompositionIssue> = []
+  for (const [index, value] of values.entries()) {
+    const previous = seen.get(value)
+    if (previous === undefined) {
+      seen.set(value, index)
+      continue
+    }
+    issues.push(
+      issue(
+        pathOf(index),
+        `${label} "${value}" duplicates generate[${previous.toString()}]`,
+      ),
+    )
+  }
+  return issues
+}
+
+const placedTags = (spec: CompositionSpec): ReadonlySet<string> => {
+  const tags = new Set<string>()
+  for (const route of spec.topology.routes) {
+    for (const mount of route.mounts) {
+      tags.add(mount.tag)
+    }
+  }
+  for (const rule of spec.topology.rules ?? []) {
+    for (const placement of rule.placements) {
+      tags.add(placement.tag)
+    }
+  }
+  return tags
+}
+
+const slotIds = (spec: CompositionSpec): ReadonlySet<string> | undefined => {
+  const manifest = spec.topology.slotManifest
+  if (manifest === undefined) {
+    return undefined
+  }
+  return new Set(manifest.slots.map(slot => slot.id))
+}
+
+const checkMounts = (
+  spec: CompositionSpec,
+  tags: ReadonlySet<string>,
+): ReadonlyArray<CompositionIssue> => {
+  const slots = slotIds(spec)
+  const issues: Array<CompositionIssue> = []
+  for (const [routeIndex, route] of spec.topology.routes.entries()) {
+    for (const [mountIndex, mount] of route.mounts.entries()) {
+      const path = `topology.routes[${routeIndex.toString()}].mounts[${mountIndex.toString()}]`
+      if (!tags.has(mount.tag)) {
+        issues.push(
+          issue(
+            `${path}.tag`,
+            `tag "${mount.tag}" is neither a catalogued surface nor in generate[]`,
+          ),
+        )
+      }
+      if (slots !== undefined && !slots.has(mount.slotId)) {
+        issues.push(
+          issue(
+            `${path}.slotId`,
+            `slot "${mount.slotId}" is not in topology.slotManifest`,
+          ),
+        )
+      }
+    }
+  }
+  return issues
+}
+
+const checkWires = (
+  spec: CompositionSpec,
+  surfaces: ReadonlyArray<ManifestTag>,
+  tags: ReadonlySet<string>,
+): ReadonlyArray<CompositionIssue> => {
+  const generatedTags = new Set(spec.generate.map(generated => generated.tag))
+  const table = topologyRouteTable(spec.topology)
+  const issues: Array<CompositionIssue> = []
+  for (const [index, wire] of spec.topology.wires.entries()) {
+    const path = `topology.wires[${index.toString()}]`
+    if (!tags.has(wire.from)) {
+      issues.push(
+        issue(
+          `${path}.from`,
+          `tag "${wire.from}" is neither a catalogued surface nor in generate[]`,
+        ),
+      )
+    }
+    if (!tags.has(wire.to)) {
+      issues.push(
+        issue(
+          `${path}.to`,
+          `tag "${wire.to}" is neither a catalogued surface nor in generate[]`,
+        ),
+      )
+    }
+    if (generatedTags.has(wire.from) || generatedTags.has(wire.to)) {
+      continue
+    }
+    if (!tags.has(wire.from) || !tags.has(wire.to)) {
+      continue
+    }
+    const state = deriveWireState(wire, { manifests: surfaces, table })
+    if (state === 'draft') {
+      issues.push(
+        issue(
+          path,
+          `wire "${wire.id}" derives draft — a tag, event, field, input or type pairing is missing from the surface catalog`,
+        ),
+      )
+    }
+  }
+  return issues
+}
+
+/**
+ * Fail-closed composition lint. Schema-decode is the first gate; this is
+ * the second: identities, slot membership, and `deriveWireState !== 'draft'`
+ * for wires whose both ends are catalogued surfaces. Wires that touch a
+ * `generate[]` tag skip the manifest check — the scaffold surface is not
+ * the domain surface yet.
+ */
+export const validateComposition = (
+  spec: CompositionSpec,
+  surfaces: ReadonlyArray<ManifestTag>,
+): ReadonlyArray<CompositionIssue> => {
+  const tags = knownTags(spec, surfaces)
+  return [
+    ...duplicatePaths(
+      spec.generate.map(generated => generated.slug),
+      index => `generate[${index.toString()}].slug`,
+      'slug',
+    ),
+    ...duplicatePaths(
+      spec.generate.map(generated => generated.tag),
+      index => `generate[${index.toString()}].tag`,
+      'tag',
+    ),
+    ...duplicatePaths(
+      spec.generate.map(generated => String(generated.port)),
+      index => `generate[${index.toString()}].port`,
+      'port',
+    ),
+    ...checkMounts(spec, tags),
+    ...checkWires(spec, surfaces, tags),
+    ...Array.getSomes(
+      spec.generate.map((generated, index) =>
+        placedTags(spec).has(generated.tag)
+          ? Option.none()
+          : Option.some(
+              issue(
+                `generate[${index.toString()}].tag`,
+                `generated tag "${generated.tag}" is never placed in the topology`,
+              ),
+            ),
+      ),
+    ),
+  ]
+}
+
+/**
+ * The current existing-surface lane writes v2, but it never generates a new
+ * MicroDot. Keep that boundary explicit so a resolved application spec cannot
+ * accidentally fall through to the legacy scaffold compiler.
+ *
+ * Once `generate[]` is known empty, the topology validation is exactly the v1
+ * compatibility rule: every mounted/wired tag must already exist in the
+ * emitted surface catalog. The temporary v1 value is not encoded or persisted;
+ * it is the retained read-side validator during the Phase 6 migration.
+ */
+export const validateExistingSurfaceComposition = (
+  spec: CompositionSpecV2,
+  surfaces: ReadonlyArray<ManifestTag>,
+): ReadonlyArray<CompositionIssue> => {
+  if (spec.generate.length > 0) {
+    return [
+      issue(
+        'generate',
+        'existing-surface composition requires generate[] to be empty; use the application-authoring compiler for new MicroDots',
+      ),
+    ]
+  }
+
+  const compatibilitySpec: CompositionSpecV1 = {
+    schemaVersion: 1,
+    generate: [],
+    topology: spec.topology,
+    ...(spec.brief === undefined ? {} : { brief: spec.brief }),
+  }
+  return validateComposition(compatibilitySpec, surfaces)
+}
+
+export const encodeTopologyJson = (topology: HostTopology): string =>
+  `${JSON.stringify(S.encodeSync(HostTopology)(topology), null, 2)}\n`
+
+/* ============================================================
+   Surface-derived JSON Schema — the smaller prompt.
+   Illegal tags/events/attrs/transforms are unrepresentable here; the
+   Effect schema is still the decoder. Built by hand because the
+   constrained enums are a function of the live ManifestTag catalog,
+   not of HostTopology's free strings.
+   ============================================================ */
+
+export type JsonSchema = {
+  readonly $schema?: string
+  readonly $comment?: string
+  readonly $defs?: Readonly<Record<string, JsonSchema>>
+  readonly type?:
+    'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean'
+  readonly enum?: ReadonlyArray<string | number>
+  readonly const?: string | number | boolean
+  readonly properties?: Readonly<Record<string, JsonSchema>>
+  readonly required?: ReadonlyArray<string>
+  readonly additionalProperties?: boolean | JsonSchema
+  readonly items?: JsonSchema
+  readonly minItems?: number
+  readonly minLength?: number
+  readonly minimum?: number
+  readonly maximum?: number
+  readonly pattern?: string
+  readonly if?: JsonSchema
+  readonly then?: JsonSchema
+  readonly allOf?: ReadonlyArray<JsonSchema>
+  readonly oneOf?: ReadonlyArray<JsonSchema>
+  readonly anyOf?: ReadonlyArray<JsonSchema>
+}
+
+const objectSchema = (
+  properties: Readonly<Record<string, JsonSchema>>,
+  required: ReadonlyArray<string>,
+): JsonSchema => ({
+  type: 'object',
+  additionalProperties: false,
+  properties,
+  required,
+})
+
+const stringEnum = (values: ReadonlyArray<string>): JsonSchema => ({
+  type: 'string',
+  enum: values,
+})
+
+const TAG_PATTERN = '^[a-z][a-z0-9]*(?:-[a-z0-9]+)+$'
+
+const tagNameSchema = (
+  known: ReadonlyArray<string>,
+  allowNewTags: boolean,
+): JsonSchema => {
+  if (known.length === 0) {
+    return { type: 'string', pattern: TAG_PATTERN }
+  }
+  if (!allowNewTags) {
+    return stringEnum(known)
+  }
+  return {
+    anyOf: [stringEnum(known), { type: 'string', pattern: TAG_PATTERN }],
+  }
+}
+
+const wireIfThen = (
+  surfaces: ReadonlyArray<ManifestTag>,
+): ReadonlyArray<JsonSchema> =>
+  surfaces.flatMap(surface => {
+    const clauses: Array<JsonSchema> = []
+    const events = surface.events.map(event => event.name)
+    clauses.push({
+      if: {
+        properties: { from: { const: surface.tag } },
+        required: ['from'],
+      },
+      then: {
+        properties: { event: stringEnum(events) },
+      },
+    })
+    const inputs = surface.attributes.map(attribute => attribute.name)
+    clauses.push({
+      if: {
+        properties: { to: { const: surface.tag } },
+        required: ['to'],
+      },
+      then: {
+        properties: { input: stringEnum(inputs) },
+      },
+    })
+    return clauses
+  })
+
+const VALUE_TYPES: ReadonlyArray<string> = [
+  'string',
+  'number',
+  'boolean',
+  'json',
+  'enum',
+]
+
+const ENV_ENUM: JsonSchema = stringEnum(['dev', 'preview', 'prod'])
+
+const transformSchema: JsonSchema = {
+  oneOf: [
+    objectSchema({ _tag: { const: 'direct' } }, ['_tag']),
+    objectSchema(
+      {
+        _tag: { const: 'lookup' },
+        rows: {
+          type: 'object',
+          additionalProperties: { type: 'string' },
+        },
+        fallback: { type: 'string' },
+      },
+      ['_tag', 'rows', 'fallback'],
+    ),
+    objectSchema(
+      {
+        _tag: { const: 'condition' },
+        field: { type: 'string' },
+        op: { const: 'is' },
+        value: { type: 'string' },
+      },
+      ['_tag', 'field', 'op', 'value'],
+    ),
+  ],
+}
+
+const wireSchema = (
+  surfaces: ReadonlyArray<ManifestTag>,
+  allowNewTags: boolean,
+): JsonSchema => {
+  const known = surfaces.map(tagOf)
+  const base = objectSchema(
+    {
+      id: { type: 'string', minLength: 1 },
+      from: tagNameSchema(known, allowNewTags),
+      event: { type: 'string', minLength: 1 },
+      field: { type: 'string', minLength: 1 },
+      fieldType: stringEnum(VALUE_TYPES),
+      to: tagNameSchema(known, allowNewTags),
+      input: { type: 'string', minLength: 1 },
+      inputType: stringEnum(VALUE_TYPES),
+      transform: transformSchema,
+      envs: { type: 'array', items: ENV_ENUM, minItems: 1 },
+      plain: { type: 'string' },
+    },
+    [
+      'id',
+      'from',
+      'event',
+      'field',
+      'fieldType',
+      'to',
+      'input',
+      'inputType',
+      'transform',
+      'envs',
+      'plain',
+    ],
+  )
+  const clauses = wireIfThen(surfaces)
+  if (clauses.length === 0) {
+    return base
+  }
+  return { allOf: [base, ...clauses] }
+}
+
+const placementSchema = (
+  surfaces: ReadonlyArray<ManifestTag>,
+  allowNewTags: boolean,
+): JsonSchema =>
+  objectSchema(
+    {
+      id: { type: 'string' },
+      tag: tagNameSchema(surfaces.map(tagOf), allowNewTags),
+      slotId: { type: 'string', minLength: 1 },
+      values: {
+        type: 'object',
+        additionalProperties: { type: 'string' },
+      },
+      condition: objectSchema(
+        {
+          who: { type: 'string' },
+          device: { type: 'string' },
+          locale: { type: 'string' },
+        },
+        [],
+      ),
+      envs: { type: 'array', items: ENV_ENUM },
+      span: { enum: [12, 8, 6, 4, 3] },
+      order: { type: 'number' },
+    },
+    ['tag', 'slotId'],
+  )
+
+const routeSchema = (
+  surfaces: ReadonlyArray<ManifestTag>,
+  allowNewTags: boolean,
+): JsonSchema =>
+  objectSchema(
+    {
+      path: { type: 'string', minLength: 1 },
+      label: { type: 'string', minLength: 1 },
+      title: { type: 'string', minLength: 1 },
+      sectionIds: { type: 'array', items: { type: 'string' } },
+      mounts: {
+        type: 'array',
+        items: placementSchema(surfaces, allowNewTags),
+      },
+    },
+    ['path', 'label', 'title', 'sectionIds', 'mounts'],
+  )
+
+const slotSpecSchema = objectSchema(
+  {
+    id: { type: 'string', minLength: 1 },
+    kind: stringEnum(['bar', 'band', 'rail', 'grid']),
+    row: { type: 'number' },
+    width: { type: 'string' },
+    capacity: { type: 'number' },
+  },
+  ['id', 'kind', 'row'],
+)
+
+const topologySchema = (
+  surfaces: ReadonlyArray<ManifestTag>,
+  allowNewTags: boolean,
+): JsonSchema =>
+  objectSchema(
+    {
+      host: objectSchema(
+        {
+          id: { type: 'string', minLength: 1 },
+          label: { type: 'string', minLength: 1 },
+          ownedInputs: {
+            type: 'array',
+            items: objectSchema(
+              { name: { type: 'string' }, type: { type: 'string' } },
+              ['name', 'type'],
+            ),
+          },
+        },
+        ['id', 'label', 'ownedInputs'],
+      ),
+      routes: {
+        type: 'array',
+        minItems: 1,
+        items: routeSchema(surfaces, allowNewTags),
+      },
+      overview: objectSchema(
+        {
+          path: { type: 'string' },
+          label: { type: 'string' },
+          title: { type: 'string' },
+          leadingSectionIds: { type: 'array', items: { type: 'string' } },
+        },
+        ['path', 'label', 'title'],
+      ),
+      slotManifest: objectSchema(
+        {
+          theme: objectSchema(
+            { name: { type: 'string' }, version: { type: 'string' } },
+            ['name', 'version'],
+          ),
+          slots: { type: 'array', items: slotSpecSchema },
+        },
+        ['theme', 'slots'],
+      ),
+      rules: {
+        type: 'array',
+        items: {
+          oneOf: [
+            objectSchema(
+              {
+                id: { type: 'string' },
+                label: { type: 'string' },
+                kind: { const: 'pattern' },
+                pattern: { type: 'string' },
+                placements: {
+                  type: 'array',
+                  items: placementSchema(surfaces, allowNewTags),
+                },
+              },
+              ['id', 'label', 'kind', 'pattern', 'placements'],
+            ),
+            objectSchema(
+              {
+                id: { type: 'string' },
+                label: { type: 'string' },
+                kind: { const: 'group' },
+                paths: { type: 'array', items: { type: 'string' } },
+                placements: {
+                  type: 'array',
+                  items: placementSchema(surfaces, allowNewTags),
+                },
+              },
+              ['id', 'label', 'kind', 'paths', 'placements'],
+            ),
+            objectSchema(
+              {
+                id: { type: 'string' },
+                label: { type: 'string' },
+                kind: { const: 'dynamic' },
+                template: { type: 'string' },
+                placements: {
+                  type: 'array',
+                  items: placementSchema(surfaces, allowNewTags),
+                },
+              },
+              ['id', 'label', 'kind', 'template', 'placements'],
+            ),
+          ],
+        },
+      },
+      wires: { type: 'array', items: wireSchema(surfaces, allowNewTags) },
+      watch: {
+        type: 'array',
+        items: objectSchema({ event: { type: 'string' } }, ['event']),
+      },
+    },
+    ['host', 'routes', 'wires', 'watch'],
+  )
+
+/**
+ * JSON Schema (draft 2020-12) for constrained decoding of a CompositionSpec.
+ * Event and attribute names are closed over the supplied surfaces, so a
+ * model cannot emit `from: "readout-view", event: "bid-placed"`.
+ */
+export type CompositionJsonSchemaOptions = {
+  /** When false, topology tags are a closed enum of the catalog. Default true. */
+  readonly allowNewTags?: boolean
+}
+
+export const compositionJsonSchema = (
+  surfaces: ReadonlyArray<ManifestTag>,
+  options: CompositionJsonSchemaOptions = {},
+): JsonSchema => {
+  const allowNewTags = options.allowNewTags ?? true
+  return {
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    $comment:
+      'Legal tags, events, attributes and transforms are derived from the ManifestTag catalog. Do not invent names.',
+    ...objectSchema(
+      {
+        schemaVersion: { const: 1 },
+        brief: { type: 'string' },
+        generate: {
+          type: 'array',
+          items: objectSchema(
+            {
+              slug: {
+                type: 'string',
+                pattern: '^[a-z][a-z0-9-]*$',
+              },
+              tag: { type: 'string', pattern: TAG_PATTERN },
+              port: { type: 'integer', minimum: 1, maximum: 65535 },
+            },
+            ['slug', 'tag', 'port'],
+          ),
+        },
+        topology: topologySchema(surfaces, allowNewTags),
+      },
+      ['schemaVersion', 'generate', 'topology'],
+    ),
+  }
+}
+
+/** Test/helper: event names the schema admits when `from` is this tag. */
+export const schemaEventsFor = (
+  schema: JsonSchema,
+  fromTag: string,
+): ReadonlyArray<string> => {
+  const topology = schema.properties?.['topology']
+  const wires = topology?.properties?.['wires']
+  const items = wires?.items
+  const clauses = items?.allOf ?? (items === undefined ? [] : [items])
+  for (const clause of clauses) {
+    if (clause.if?.properties?.['from']?.const === fromTag) {
+      const enumerated = clause.then?.properties?.['event']?.enum
+      if (enumerated === undefined) {
+        return []
+      }
+      return Array.getSomes(
+        enumerated.map(value =>
+          typeof value === 'string' ? Option.some(value) : Option.none(),
+        ),
+      )
+    }
+  }
+  return []
+}
+
+/** Test/helper: attribute names the schema admits when `to` is this tag. */
+export const schemaInputsFor = (
+  schema: JsonSchema,
+  toTag: string,
+): ReadonlyArray<string> => {
+  const topology = schema.properties?.['topology']
+  const wires = topology?.properties?.['wires']
+  const items = wires?.items
+  const clauses = items?.allOf ?? (items === undefined ? [] : [items])
+  for (const clause of clauses) {
+    if (clause.if?.properties?.['to']?.const === toTag) {
+      const enumerated = clause.then?.properties?.['input']?.enum
+      if (enumerated === undefined) {
+        return []
+      }
+      return Array.getSomes(
+        enumerated.map(value =>
+          typeof value === 'string' ? Option.some(value) : Option.none(),
+        ),
+      )
+    }
+  }
+  return []
+}
+
+/** Legacy v1 decoder, preserved through the Phase 6 saved-spec migration. */
+export const decodeCompositionSpec = S.decodeUnknownEffect(CompositionSpecV1)
+/** Legacy v1 decoder, preserved through the Phase 6 saved-spec migration. */
+export const decodeCompositionSpecSync = S.decodeUnknownSync(CompositionSpecV1)
+
+export const decodeCompositionSpecVersioned = S.decodeUnknownEffect(
+  CompositionSpecVersioned,
+)
+export const decodeCompositionSpecVersionedSync = S.decodeUnknownSync(
+  CompositionSpecVersioned,
+)
+
+export const encodeCompositionSpecV2Sync = S.encodeSync(CompositionSpecV2)
+
+/**
+ * The only lossless v1 migration available before catalogs exist is a
+ * topology-only composition. Legacy generate rows lack domain, shape,
+ * capability, target and provenance semantics, so Phase 0 reports the closed
+ * input boundary instead of guessing them.
+ */
+export const migrateCompositionSpecV1 = (
+  spec: CompositionSpecV1,
+  catalogLock: CatalogLockV1,
+): MigrationResult<CompositionSpecV2> => {
+  if (spec.generate.length === 0) {
+    const value: CompositionSpecV2 = {
+      schemaVersion: 2,
+      generate: [],
+      topology: spec.topology,
+      catalogLock,
+      ...(spec.brief === undefined ? {} : { brief: spec.brief }),
+    }
+    return migrated(value)
+  }
+
+  return migrationNeedsInput(
+    decodeAuthoringDiagnosticSync({
+      schemaVersion: 1,
+      code: 'migration-input-required',
+      phase: 'migrate',
+      path: ['generate'],
+      entityIds: spec.generate.map(generated => generated.slug),
+      severity: 'error',
+      retryable: true,
+      references: [
+        'wiki/plans/active/microdots-authoring-catalog-programme.md',
+      ],
+      destinationMutated: false,
+      nextLane: 'application-correction',
+      parameters: {
+        required: [
+          'fronts',
+          'domain',
+          'capabilities',
+          'target-profile',
+          'provenance',
+        ],
+      },
+    }),
+  )
+}