@bespokeagentics/microdots-host 0.1.2 → 0.2.0

package/src/registry.test.ts

@@ -0,0 +1,289 @@
+import { Schema as S } from 'effect'
+import { describe, expect, test } from 'vitest'
+
+import { registry as embeddingRegistry } from '../../../apps/embedding-demo/src/registry.ts'
+import { registry as pitchDeckRegistry } from '../../../apps/pitch-deck-website/host/src/registry.ts'
+import { registry as platformRegistry } from '../../../apps/platform/src/registry.ts'
+import {
+  type MicroDotRegistry,
+  TopologyRegistryEntry,
+  bundleAlreadyDefined,
+  findEntry,
+  isAllowedBundle,
+  refusedRegistryRows,
+  resolveRegistry,
+} from './registry.ts'
+import { HostTopology } from './wire.ts'
+
+const compiled: MicroDotRegistry = [
+  {
+    tag: 'readout-view',
+    bundle: '/microdots/readout.js',
+    localPort: 3101,
+    deployedApiUrl: 'https://readout.example',
+    attributes: {},
+  },
+  {
+    tag: 'intake-form',
+    bundle: '/microdots/intake.js',
+    localPort: 3103,
+    attributes: {},
+  },
+]
+
+describe('resolveRegistry', () => {
+  test('a topology with no registry leaves the compiled one exactly as it was', () => {
+    // Every topology written before this key existed. The compiled array is
+    // the floor and must stay byte-identical, or shipping this would change
+    // what every existing host mounts.
+    expect(resolveRegistry(compiled, undefined)).toBe(compiled)
+    expect(resolveRegistry(compiled, [])).toBe(compiled)
+  })
+
+  test('a fetched entry for an UNKNOWN tag becomes mountable — the whole gap', () => {
+    // Until this existed, a fetched placement naming a tag the build did not
+    // carry reached `findEntry`, got `undefined`, and the mount threw. Placing
+    // a MicroDot on a deployed host meant editing registry.ts and rebuilding.
+    const resolved = resolveRegistry(compiled, [
+      {
+        tag: 'dossier-detail',
+        bundle: 'https://cdn.microdot.cloud/dossier/1.2.0/dossier.js',
+        localPort: 3116,
+        deployedApiUrl: 'https://dossier.example',
+      },
+    ], ['https://cdn.microdot.cloud'])
+
+    expect(findEntry(compiled, 'dossier-detail')).toBeUndefined()
+    expect(findEntry(resolved, 'dossier-detail')).toEqual({
+      tag: 'dossier-detail',
+      bundle: 'https://cdn.microdot.cloud/dossier/1.2.0/dossier.js',
+      localPort: 3116,
+      deployedApiUrl: 'https://dossier.example',
+      attributes: {},
+    })
+    // The compiled entries survive alongside it.
+    expect(findEntry(resolved, 'readout-view')?.localPort).toBe(3101)
+  })
+
+  test('a fetched entry REPLACES a compiled one whole, never field by field', () => {
+    // Replacing wholesale is what stops a stale compiled `deployedApiUrl`
+    // surviving underneath a fresh bundle — a mixed row nobody could reason
+    // about, and one that would send RPCs to the previous deployment.
+    // (Whether a re-point takes effect in a LIVE session is a separate
+    // question with a different answer — see `bundleAlreadyDefined` below.)
+    const resolved = resolveRegistry(compiled, [
+      {
+        tag: 'readout-view',
+        bundle: 'https://cdn.microdot.cloud/readout/2.0.0/readout.js',
+        localPort: 3101,
+      },
+    ], ['https://cdn.microdot.cloud'])
+
+    expect(findEntry(resolved, 'readout-view')).toEqual({
+      tag: 'readout-view',
+      bundle: 'https://cdn.microdot.cloud/readout/2.0.0/readout.js',
+      localPort: 3101,
+      attributes: {},
+    })
+    expect(findEntry(resolved, 'readout-view')?.deployedApiUrl).toBeUndefined()
+  })
+
+  test('an absent deployedApiUrl stays ABSENT, not undefined', () => {
+    // `exactOptionalPropertyTypes`, and `apiUrlFor` fails closed on a
+    // non-local page by checking for `undefined` — a key present with an
+    // undefined value would serialise back into a topology as `null`.
+    const resolved = resolveRegistry([], [
+      { tag: 'workbench-board', bundle: '/microdots/workbench.js', localPort: 3106 },
+    ])
+    expect(Object.hasOwn(resolved[0] ?? {}, 'deployedApiUrl')).toBe(false)
+  })
+
+  test('the last fetched entry for a tag wins, so a document cannot half-apply', () => {
+    const resolved = resolveRegistry([], [
+      { tag: 'dupe', bundle: '/first.js', localPort: 1 },
+      { tag: 'dupe', bundle: '/second.js', localPort: 2 },
+    ])
+    expect(resolved).toHaveLength(1)
+    expect(findEntry(resolved, 'dupe')?.bundle).toBe('/second.js')
+  })
+})
+
+describe('the bundle-origin allowlist', () => {
+  const CDN = 'https://cdn.microdot.cloud'
+
+  test('a relative bundle is same-origin and always allowed', () => {
+    expect(isAllowedBundle('/microdots/readout.js', [])).toBe(true)
+    // Protocol-relative is NOT same-origin — `//evil.example/x.js` inherits the
+    // scheme and loads from another host, which is the case a naive
+    // startsWith('/') check waves straight through.
+    expect(isAllowedBundle('//evil.example/x.js', [])).toBe(false)
+  })
+
+  test('a cross-origin bundle needs its origin named', () => {
+    expect(isAllowedBundle(`${CDN}/readout/abc/readout.js`, [])).toBe(false)
+    expect(isAllowedBundle(`${CDN}/readout/abc/readout.js`, [CDN])).toBe(true)
+    // Exact origin, not a prefix: a lookalike host must not pass.
+    expect(
+      isAllowedBundle('https://cdn.microdot.cloud.evil.example/x.js', [CDN]),
+    ).toBe(false)
+  })
+
+  test('an unparseable specifier is refused, not waved through', () => {
+    expect(isAllowedBundle('not a url', [])).toBe(false)
+    expect(isAllowedBundle('javascript:alert(1)', [])).toBe(false)
+  })
+
+  test('resolveRegistry DROPS a disallowed row and reports it', () => {
+    // Silently dropping it would present later as "not registered", naming
+    // the wrong cause — the row exists and was refused.
+    const fetched = [
+      { tag: 'evil', bundle: 'https://evil.example/x.js', localPort: 1 },
+      { tag: 'fine', bundle: '/microdots/fine.js', localPort: 2 },
+    ]
+    const resolved = resolveRegistry(compiled, fetched, [])
+
+    expect(findEntry(resolved, 'evil')).toBeUndefined()
+    expect(findEntry(resolved, 'fine')?.bundle).toBe('/microdots/fine.js')
+    expect(refusedRegistryRows(fetched, []).map(row => row.tag)).toEqual(['evil'])
+  })
+
+  test('naming the origin admits the row', () => {
+    const fetched = [
+      { tag: 'dossier-detail', bundle: `${CDN}/dossier/abc/dossier.js`, localPort: 3116 },
+    ]
+    expect(refusedRegistryRows(fetched, [CDN])).toEqual([])
+    expect(findEntry(resolveRegistry(compiled, fetched, [CDN]), 'dossier-detail')?.bundle)
+      .toBe(`${CDN}/dossier/abc/dossier.js`)
+  })
+
+  test('a refused row never displaces the compiled entry it shadows', () => {
+    // The dangerous case: an attacker re-points an EXISTING tag. The compiled
+    // row must survive untouched rather than being replaced or dropped.
+    const resolved = resolveRegistry(
+      compiled,
+      [{ tag: 'readout-view', bundle: 'https://evil.example/x.js', localPort: 3101 }],
+      [],
+    )
+    expect(findEntry(resolved, 'readout-view')?.bundle).toBe('/microdots/readout.js')
+  })
+})
+
+describe('bundleAlreadyDefined', () => {
+  test('names a tag whose re-point this session cannot honour', () => {
+    // `loader.ts` short-circuits on `customElements.get(tag)` and a custom
+    // element cannot be un-defined, so a polling page keeps running the bundle
+    // it already loaded. Saying so beats implying the swap took effect.
+    const resolved = resolveRegistry(compiled, [
+      { tag: 'readout-view', bundle: '/v2/readout.js', localPort: 3101 },
+    ])
+    const loaded = new Map([['readout-view', '/microdots/readout.js']])
+
+    expect(bundleAlreadyDefined(resolved, loaded)).toEqual(['readout-view'])
+    // Unchanged bundle, and a tag never loaded, are both silent.
+    expect(
+      bundleAlreadyDefined(resolved, new Map([['readout-view', '/v2/readout.js']])),
+    ).toEqual([])
+    expect(bundleAlreadyDefined(resolved, new Map())).toEqual([])
+  })
+})
+
+describe('the premise this key rests on', () => {
+  test('every compiled registry entry still has EMPTY attributes', () => {
+    // THE LOAD-BEARING FACT, pinned so it cannot rot silently.
+    //
+    // The programme ruled that `HostTopology` carries no registry because
+    // "registries hold computed values (`JSON.stringify(...)` attribute
+    // payloads) and stay TypeScript". Phase 5 moved attribute data onto
+    // `placement.values` and emptied every entry, which is what made the
+    // registry records-only and therefore safe to send as data.
+    //
+    // If someone puts a computed attribute back into a registry, this fails —
+    // and the right response is to move it to `placement.values`, not to
+    // loosen this test.
+    for (const [name, entries] of [
+      ['pitch-deck', pitchDeckRegistry],
+      ['platform', platformRegistry],
+      ['embedding-demo', embeddingRegistry],
+    ] as const) {
+      for (const entry of entries) {
+        expect(
+          Object.keys(entry.attributes),
+          `${name}: <${entry.tag}> carries attributes`,
+        ).toEqual([])
+      }
+    }
+  })
+
+  test('every compiled registry entry decodes as a topology registry entry', () => {
+    // The wire shape and the runtime shape are separate types; this is what
+    // keeps them from drifting apart.
+    const decode = S.decodeUnknownSync(TopologyRegistryEntry)
+    for (const entries of [
+      pitchDeckRegistry,
+      platformRegistry,
+      embeddingRegistry,
+    ]) {
+      for (const entry of entries) {
+        expect(() => decode(entry)).not.toThrow()
+      }
+    }
+  })
+})
+
+describe('HostTopology', () => {
+  const base = {
+    host: { id: 'h', label: 'H', ownedInputs: [] },
+    routes: [
+      { path: '/a', label: 'A', title: 'A', sectionIds: ['s'], mounts: [] },
+    ],
+    wires: [],
+    watch: [],
+  }
+
+  test('decodes with no registry key — every topology written before today', () => {
+    const decoded = S.decodeUnknownSync(HostTopology)(base)
+    expect(decoded.registry).toBeUndefined()
+  })
+
+  test('decodes a carried registry and hands it to resolveRegistry', () => {
+    const decoded = S.decodeUnknownSync(HostTopology)({
+      ...base,
+      registry: [
+        { tag: 'late-arrival', bundle: '/late.js', localPort: 3199 },
+      ],
+    })
+    expect(findEntry(resolveRegistry([], decoded.registry), 'late-arrival')).toMatchObject(
+      { bundle: '/late.js' },
+    )
+  })
+
+  test('refuses an EMPTY bundle as loudly as a missing one', () => {
+    // The quiet case, found by audit. A missing key was already refused; `''`
+    // decoded cleanly and then `import('')` resolves against the page and
+    // imports the page — a blank mount with a clean console.
+    expect(() =>
+      S.decodeUnknownSync(HostTopology)({
+        ...base,
+        registry: [{ tag: 'broken', bundle: '', localPort: 3199 }],
+      }),
+    ).toThrow()
+    expect(() =>
+      S.decodeUnknownSync(HostTopology)({
+        ...base,
+        registry: [{ tag: '', bundle: '/x.js', localPort: 3199 }],
+      }),
+    ).toThrow()
+  })
+
+  test('refuses a registry entry missing its bundle', () => {
+    // A row with no bundle is a row that cannot mount; failing the decode is
+    // the loud form, and `acquireTopology` renders it as a visible error
+    // rather than a blank page.
+    expect(() =>
+      S.decodeUnknownSync(HostTopology)({
+        ...base,
+        registry: [{ tag: 'broken', localPort: 3199 }],
+      }),
+    ).toThrow()
+  })
+})

package/src/registry.ts

@@ -1,3 +1,5 @@
+import { Schema as S } from 'effect'
+
 /**
  * What a host knows about one registered ELEMENT.
  *
@@ -29,6 +31,162 @@ export type MicroDotEntry = {
 /** A host's whole registry: one entry per element it may mount. */
 export type MicroDotRegistry = ReadonlyArray<MicroDotEntry>
 
+/**
+ * The same entry, as it travels IN A TOPOLOGY DOCUMENT.
+ *
+ * Why this exists. A host acquires its topology at runtime and polls it
+ * (`topologySource.ts`, `entry.ts`'s `pollTopology`), so it can already mount
+ * a placement whose route, section and slot its build never knew about. The
+ * one thing it could not learn at runtime was where to FETCH the bundle: that
+ * lived only in the compiled `registry` array, so the moment a fetched
+ * placement named an unregistered tag, `findEntry` returned `undefined` and
+ * the mount threw. Placing a MicroDot on a deployed host therefore meant
+ * editing `registry.ts` by hand and shipping a host build — the last
+ * build-time half of `gap-placement-is-source-code-not-data`.
+ *
+ * Why it is allowed to be data NOW. The programme ruled that `HostTopology`
+ * carries no registry because "registries hold computed values
+ * (`JSON.stringify(...)` attribute payloads) and stay TypeScript". That
+ * premise expired: Phase 5 moved attribute data onto `placement.values`, and
+ * every one of the 48 entries across all three hosts now reads
+ * `attributes: {}` — pinned by a test, so this reasoning cannot rot silently.
+ * What is left is a record of four scalars.
+ *
+ * Why it is a SEPARATE type from `MicroDotEntry`. On the wire `attributes` may
+ * be absent; at runtime it is always present, because every consumer spreads
+ * it. `resolveRegistry` is the one conversion, so no existing call site has to
+ * learn about `undefined`.
+ */
+export const TopologyRegistryEntry = S.Struct({
+  tag: S.NonEmptyString,
+  /**
+   * Where to fetch the bundle. NON-EMPTY, because `''` decoded cleanly and
+   * then produced a silent mount failure — `import('')` resolves against the
+   * page and imports the page, which is this repo's signature blank-with-a-
+   * clean-console. A missing key is refused loudly; so is an empty one.
+   *
+   * DELIBERATELY UNCONSTRAINED BEYOND THAT, and it is a real trust boundary:
+   * this string reaches `import(/* @vite-ignore *\/ bundleUrl)` in
+   * `loader.ts`, so whoever may write a host's topology may execute code in
+   * every page polling it. That was already true of `WIRING_WRITE_KEY` for
+   * placements; carrying the registry widens it from "may rearrange the page"
+   * to "may run JS on it", and `microdots/pages` now holds that key too.
+   * Accepted for now — no shell ships a CSP either — and recorded on
+   * `gap-placement-is-source-code-not-data` rather than left implicit.
+   */
+  bundle: S.NonEmptyString,
+  localPort: S.Number,
+  deployedApiUrl: S.optionalKey(S.String),
+  attributes: S.optionalKey(S.Record(S.String, S.String)),
+})
+export type TopologyRegistryEntry = typeof TopologyRegistryEntry.Type
+
+/**
+ * The registry a host actually mounts from: what it was built with, plus
+ * whatever its topology carried.
+ *
+ * FETCHED WINS, deliberately and per tag. The compiled array is the floor —
+ * it keeps a host working when its topology carries no registry at all, which
+ * is every topology written before this shipped — and a fetched entry for the
+ * same tag replaces it whole. Merging FIELDS instead would let a stale
+ * compiled `deployedApiUrl` survive underneath a fresh bundle, which is the
+ * mixed state nobody could reason about.
+ *
+ * WHAT THIS DOES AND DOES NOT BUY. A tag the host has never mounted is loaded
+ * from the fetched row, which is the whole point. **Re-pointing a tag that is
+ * ALREADY defined needs a reload**: `loader.ts` short-circuits on
+ * `customElements.get(tag)` and a custom element cannot be un-defined, so a
+ * live page keeps running the bundle it already has. `deployedApiUrl` is the
+ * same — `api-url` is deliberately not an observed attribute. Callers that
+ * poll should say so out loud rather than imply the swap took effect; see
+ * `bundleAlreadyDefined` below.
+ */
+/**
+ * Whether a FETCHED row's bundle may be loaded by this host.
+ *
+ * THE ALLOWLIST BELONGS TO THE HOST, NOT THE TOPOLOGY. A `bundle` string
+ * reaches `import()` in `loader.ts`, so whoever writes a host's topology could
+ * otherwise run arbitrary JavaScript in every page polling it — and an
+ * allowlist carried IN the topology would be edited by that same writer, which
+ * bounds nothing. The host states where it is willing to load code from, the
+ * way it states its own topology URL: as an attribute it reads at boot
+ * (`configuration-arrives-as-attributes`).
+ *
+ * FAIL CLOSED. An empty allowlist means same-origin only, which is what every
+ * host ships today (all 48 compiled entries are `/microdots/<name>.js`), so a
+ * host that says nothing is not weakened by this key existing. A cross-origin
+ * bundle — the CDN — is loaded only once someone names that origin.
+ *
+ * A relative specifier is same-origin by construction. Anything else must
+ * parse AND match an allowed origin exactly; a parse failure is a refusal, not
+ * a pass, because an unparseable specifier is not a same-origin path either.
+ */
+export const isAllowedBundle = (
+  bundle: string,
+  allowedOrigins: ReadonlyArray<string>,
+): boolean => {
+  if (bundle.startsWith('/') && !bundle.startsWith('//')) return true
+  try {
+    return allowedOrigins.includes(new URL(bundle).origin)
+  } catch {
+    return false
+  }
+}
+
+/** Fetched rows this host refuses to load code from, for reporting. Silently
+ *  dropping them would present as "not registered", naming the wrong cause. */
+export const refusedRegistryRows = (
+  fetched: ReadonlyArray<TopologyRegistryEntry> | undefined,
+  allowedOrigins: ReadonlyArray<string>,
+): ReadonlyArray<TopologyRegistryEntry> =>
+  (fetched ?? []).filter(entry => !isAllowedBundle(entry.bundle, allowedOrigins))
+
+/**
+ * Tags whose resolved bundle differs from the one already defined on this
+ * page — a re-point that this session will NOT honour, because the element is
+ * defined and cannot be redefined.
+ *
+ * Reported rather than fixed: silently serving the old bundle while the
+ * topology says otherwise is the disagreement that costs an afternoon.
+ */
+export const bundleAlreadyDefined = (
+  resolved: MicroDotRegistry,
+  loadedBundles: ReadonlyMap<string, string>,
+): ReadonlyArray<string> =>
+  resolved
+    .filter(entry => {
+      const already = loadedBundles.get(entry.tag)
+      return already !== undefined && already !== entry.bundle
+    })
+    .map(entry => entry.tag)
+
+export const resolveRegistry = (
+  compiled: MicroDotRegistry,
+  fetched: ReadonlyArray<TopologyRegistryEntry> | undefined,
+  /** Origins this host will load code from. Empty = same-origin only. */
+  allowedOrigins: ReadonlyArray<string> = [],
+): MicroDotRegistry => {
+  const admitted = (fetched ?? []).filter(entry =>
+    isAllowedBundle(entry.bundle, allowedOrigins),
+  )
+  if (admitted.length === 0) return compiled
+  const byTag = new Map<string, MicroDotEntry>(
+    compiled.map(entry => [entry.tag, entry]),
+  )
+  for (const entry of admitted) {
+    byTag.set(entry.tag, {
+      tag: entry.tag,
+      bundle: entry.bundle,
+      localPort: entry.localPort,
+      ...(entry.deployedApiUrl === undefined
+        ? {}
+        : { deployedApiUrl: entry.deployedApiUrl }),
+      attributes: entry.attributes ?? {},
+    })
+  }
+  return [...byTag.values()]
+}
+
 const LOCAL_HOSTNAMES = ['localhost', '127.0.0.1']
 
 /**

package/src/registryFromManifest.test.ts

@@ -0,0 +1,126 @@
+import type { MicroDotManifest } from '@bespokeagentics/microdots-element'
+import { describe, expect, test } from 'vitest'
+
+import { isAllowedBundle } from './registry.ts'
+import {
+  DEFAULT_CDN_BASE_URL,
+  missingRegistryRows,
+  registryEntryFromManifest,
+} from './registryFromManifest.ts'
+
+const manifest = (over: Partial<MicroDotManifest> = {}): MicroDotManifest => ({
+  name: 'dossier',
+  build: 'c7269628',
+  bundle: {
+    file: 'dossier.js',
+    hashedFile: 'dossier.c7269628.js',
+    bytes: 100,
+    gzipBytes: 40,
+  },
+  service: { localPort: 3116, deployedApiUrl: 'https://dossier.example' },
+  tags: [{ tag: 'dossier-detail', attributes: [], events: [] }],
+  ...over,
+})
+
+describe('registryEntryFromManifest', () => {
+  test('composes the IMMUTABLE build-id URL, not the moving semver one', () => {
+    // `cdnPublish` writes two keys for one set of bytes: `{dot}/{version}/…`
+    // for humans and `{dot}/{buildId}/…` as the machine alias. `manifest.build`
+    // is the content hash of exactly the bundle this manifest describes, so a
+    // row built from it can never drift onto different bytes the way a moving
+    // alias can.
+    expect(registryEntryFromManifest({ manifest: manifest(), tag: 'dossier-detail' })).toEqual({
+      tag: 'dossier-detail',
+      bundle: `${DEFAULT_CDN_BASE_URL}/dossier/c7269628/dossier.js`,
+      localPort: 3116,
+      deployedApiUrl: 'https://dossier.example',
+    })
+  })
+
+  test('the filename does not repeat the hash', () => {
+    // The hash is already in the path. Getting this wrong puts it in every
+    // embed snippet twice, and it is invisible until somebody copies one.
+    const entry = registryEntryFromManifest({
+      manifest: manifest(),
+      tag: 'dossier-detail',
+    })
+    expect(entry.bundle).not.toContain('dossier.c7269628.js')
+    expect(entry.bundle.endsWith('/dossier.js')).toBe(true)
+  })
+
+  test('a composed row satisfies the host allowlist once the CDN is named', () => {
+    // The two halves have to agree or the join is useless: a row this composes
+    // must be one a host will actually load.
+    const entry = registryEntryFromManifest({
+      manifest: manifest(),
+      tag: 'dossier-detail',
+    })
+    expect(isAllowedBundle(entry.bundle, [])).toBe(false)
+    expect(isAllowedBundle(entry.bundle, [DEFAULT_CDN_BASE_URL])).toBe(true)
+  })
+
+  test('an absent deployedApiUrl stays ABSENT', () => {
+    const entry = registryEntryFromManifest({
+      manifest: manifest({ service: { localPort: 3116 } }),
+      tag: 'dossier-detail',
+    })
+    expect(Object.hasOwn(entry, 'deployedApiUrl')).toBe(false)
+  })
+
+  test('a trailing slash on the base never doubles up', () => {
+    expect(
+      registryEntryFromManifest({
+        manifest: manifest(),
+        tag: 'dossier-detail',
+        cdnBaseUrl: 'https://cdn.example/',
+      }).bundle,
+    ).toBe('https://cdn.example/dossier/c7269628/dossier.js')
+  })
+})
+
+describe('missingRegistryRows', () => {
+  const byTag = new Map([['dossier-detail', manifest()]])
+
+  test('composes only for tags the topology has no row for', () => {
+    const result = missingRegistryRows({
+      placedTags: ['dossier-detail'],
+      existing: [{ tag: 'dossier-detail', bundle: '/pinned.js', localPort: 3116 }],
+      manifestsByTag: byTag,
+    })
+    // An existing row is never overwritten — it may be pinned deliberately,
+    // and re-pointing a live host's bundle as a side effect of an unrelated
+    // placement is the worst kind of surprise.
+    expect(result.rows).toEqual([])
+    expect(result.unknown).toEqual([])
+  })
+
+  test('composes for a tag with no row', () => {
+    const result = missingRegistryRows({
+      placedTags: ['dossier-detail'],
+      existing: undefined,
+      manifestsByTag: byTag,
+    })
+    expect(result.rows.map(row => row.tag)).toEqual(['dossier-detail'])
+  })
+
+  test('a tag the catalog cannot describe is REPORTED, never skipped', () => {
+    // A placement whose bundle nothing can name will not mount. Dropping it
+    // silently is how that becomes a blank slot with a clean console.
+    const result = missingRegistryRows({
+      placedTags: ['dossier-detail', 'ghost-tag'],
+      existing: undefined,
+      manifestsByTag: byTag,
+    })
+    expect(result.rows.map(row => row.tag)).toEqual(['dossier-detail'])
+    expect(result.unknown).toEqual(['ghost-tag'])
+  })
+
+  test('a tag placed twice composes one row', () => {
+    const result = missingRegistryRows({
+      placedTags: ['dossier-detail', 'dossier-detail'],
+      existing: undefined,
+      manifestsByTag: byTag,
+    })
+    expect(result.rows).toHaveLength(1)
+  })
+})

package/src/registryFromManifest.ts

@@ -0,0 +1,92 @@
+import type { MicroDotManifest } from '@bespokeagentics/microdots-element'
+
+import type { TopologyRegistryEntry } from './registry.ts'
+
+/**
+ * The documented CDN root. Publishing writes here
+ * (`microdots/deploy/service/cdnPublish.ts`), and nothing else in the repo
+ * reads it — which is exactly the join this module closes.
+ */
+export const DEFAULT_CDN_BASE_URL = 'https://cdn.microdot.cloud'
+
+/**
+ * Compose a topology registry row from a catalog manifest.
+ *
+ * THE JOIN THAT WAS MISSING. Everything a host needs to load a dot has been
+ * stored per version in `microdots/catalog` all along — the tag, the bundle
+ * filename, the local port, the deployed API origin — and the bytes have been
+ * published to the CDN under a derivable key. Nothing composed the two, so
+ * placing a dot on a deployed host still meant a human writing the row by
+ * hand. This is that composition, and it is deliberately pure: no fetch, no
+ * catalog client, so both services and any test can call it.
+ *
+ * THE BUILD ID, NOT THE VERSION. `cdnPublish` writes two keys for one set of
+ * bytes — `{dot}/{version}/{file}` for humans and `{dot}/{buildId}/{file}` as
+ * the immutable machine alias. This composes the machine alias, because
+ * `manifest.build` is the 8-hex content hash of exactly the bundle this
+ * manifest describes: a row built from it can never drift onto different bytes
+ * the way a moving semver alias can. The filename does NOT repeat the hash —
+ * the hash is already in the path.
+ *
+ * WHAT THIS DOES NOT KNOW. Whether those bytes were ever published. That lives
+ * in the deploy service's `cdn_bundle_versions` ledger, which the catalog
+ * cannot see. A row for an unpublished build produces a 404 at mount — loud,
+ * in the console, naming the URL — rather than a silent nothing, which is the
+ * honest failure for a fact this side genuinely does not hold.
+ */
+export const registryEntryFromManifest = (input: {
+  readonly manifest: MicroDotManifest
+  readonly tag: string
+  /** Defaults to the documented CDN root. */
+  readonly cdnBaseUrl?: string
+}): TopologyRegistryEntry => {
+  const base = input.cdnBaseUrl ?? DEFAULT_CDN_BASE_URL
+  const deployed = input.manifest.service.deployedApiUrl
+  return {
+    tag: input.tag,
+    bundle: `${base.replace(/\/+$/, '')}/${input.manifest.name}/${input.manifest.build}/${input.manifest.bundle.file}`,
+    localPort: input.manifest.service.localPort,
+    // ABSENT, not undefined — `apiUrlFor` fails closed on `undefined` for a
+    // non-local page, and a key present-but-undefined serialises as `null`.
+    ...(deployed === undefined || deployed === '' ? {} : { deployedApiUrl: deployed }),
+  }
+}
+
+/**
+ * The rows a topology is MISSING for the tags it places.
+ *
+ * A writer calls this after mutating placements: any tag now placed that the
+ * topology carries no registry row for, and that the catalog can describe,
+ * gets a row composed for it. Tags the catalog does not know are returned as
+ * `unknown` rather than skipped, because a placement whose bundle nothing can
+ * name will not mount and the writer must be able to say so.
+ */
+export const missingRegistryRows = (input: {
+  readonly placedTags: ReadonlyArray<string>
+  readonly existing: ReadonlyArray<TopologyRegistryEntry> | undefined
+  readonly manifestsByTag: ReadonlyMap<string, MicroDotManifest>
+  readonly cdnBaseUrl?: string
+}): {
+  readonly rows: ReadonlyArray<TopologyRegistryEntry>
+  readonly unknown: ReadonlyArray<string>
+} => {
+  const known = new Set((input.existing ?? []).map(entry => entry.tag))
+  const rows: Array<TopologyRegistryEntry> = []
+  const unknown: Array<string> = []
+  for (const tag of new Set(input.placedTags)) {
+    if (known.has(tag)) continue
+    const manifest = input.manifestsByTag.get(tag)
+    if (manifest === undefined) {
+      unknown.push(tag)
+      continue
+    }
+    rows.push(
+      registryEntryFromManifest({
+        manifest,
+        tag,
+        ...(input.cdnBaseUrl === undefined ? {} : { cdnBaseUrl: input.cdnBaseUrl }),
+      }),
+    )
+  }
+  return { rows, unknown }
+}