@bespokeagentics/microdots-host 0.1.2 → 0.2.0

package/src/wire.ts

@@ -6,6 +6,7 @@ import type {
   ManifestTag,
 } from '@bespokeagentics/microdots-element'
 
+import { TopologyRegistryEntry } from './registry.ts'
 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.
@@ -126,11 +127,21 @@ export type PlacementCondition = typeof PlacementCondition.Type
 export const PlacementSpan = S.Literals([12, 8, 6, 4, 3])
 export type PlacementSpan = typeof PlacementSpan.Type
 
+/**
+ * The sentinel `slotId` of a placement pinned to a CSS selector in host-owned
+ * DOM instead of a declared slot. An anchor placement carries `selector`; the
+ * refinement below makes a half-anchor (either half without the other)
+ * unrepresentable, so a hand-edited file fails decode loudly and a mutator's
+ * `redecode()` refuses it as `undecodable` — never a silent half-record.
+ */
+export const ANCHOR_SLOT_ID = '@anchor'
+
 /**
  * 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 —
+ * phase design's table (work item 2), and again by the Pages write-mode plan
+ * (anchors: `'@anchor'` + `selector`). Every new field is `S.optionalKey`,
+ * because the 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`.
  *
@@ -145,11 +156,14 @@ export type PlacementSpan = typeof PlacementSpan.Type
  *                 three.
  * - `span`      — grid columns (grid slots only).
  * - `order`     — stacking order within the slot.
+ * - `selector`  — the CSS selector an anchor placement pins to. Present
+ *                 exactly when `slotId === ANCHOR_SLOT_ID`.
  *
- * 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).
+ * Deliberately NOT here, with their reasons: `resolved`/`resolvedAt` (check 5
+ * needs a crawl that does not exist — an anchor's resolution is reported
+ * UNVERIFIABLE, never stored as a guess) 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),
@@ -160,7 +174,17 @@ export const TopologyPlacement = S.Struct({
   envs: S.optionalKey(S.Array(WireEnv)),
   span: S.optionalKey(PlacementSpan),
   order: S.optionalKey(S.Number),
-})
+  selector: S.optionalKey(S.String),
+}).pipe(
+  S.check(
+    S.makeFilter(
+      placement =>
+        (placement.slotId === ANCHOR_SLOT_ID) === ('selector' in placement) ||
+        `an anchor placement carries both slotId "${ANCHOR_SLOT_ID}" and a selector — never one half`,
+      { expected: 'selector present exactly when slotId is "@anchor"' },
+    ),
+  ),
+)
 export type TopologyPlacement = typeof TopologyPlacement.Type
 
 export const TopologyRoute = S.Struct({
@@ -244,9 +268,27 @@ export const TopologyHost = S.Struct({
   id: S.String,
   label: S.String,
   ownedInputs: S.Array(S.Struct({ name: S.String, type: S.String })),
+  /**
+   * Who owns this host's layout DOM. Absent means `authored` — hand-written
+   * markup wins and `slotDom.ts` only backfills missing containers. Only an
+   * explicitly `generated` host renders its slot manifest as its page
+   * structure (`renderLayout.ts`) and accepts layout writes from Pages. The
+   * marker is HOST-level, not manifest-level, because the gate must be
+   * readable when NO manifest exists: `generateLayout` targets exactly that
+   * state, and `removeLayout` returns to it (plan ruling D4,
+   * `wiki/plans/active/microdots-platform-pages-generated-layout.md`).
+   */
+  layout: S.optionalKey(S.Literals(['authored', 'generated'])),
 })
 export type TopologyHost = typeof TopologyHost.Type
 
+/** The layout-ownership seam: absent means `authored`. Every gate — the
+ *  proof host's renderer, the Pages service's layout mutators — reads the
+ *  mode through here, never `topology.host.layout` directly. */
+export const layoutModeOf = (topology: {
+  readonly host: TopologyHost
+}): 'authored' | 'generated' => topology.host.layout ?? 'authored'
+
 /**
  * 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
@@ -261,6 +303,16 @@ export type TopologyHost = typeof TopologyHost.Type
  * - `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.
+ *
+ * 2026-09-03 adds a third, on the same terms:
+ *
+ * - `registry` — where to FETCH the bundle for a tag (`./registry.ts`).
+ *   Absent means the host mounts from its compiled registry alone, exactly as
+ *   before. Present, it wins per tag, which is what lets a placement for a dot
+ *   the host was never built with actually mount: until this key existed, a
+ *   fetched placement naming an unregistered tag reached `findEntry`, got
+ *   `undefined`, and threw — so placing a MicroDot on a DEPLOYED host meant a
+ *   human editing `registry.ts` and shipping a host build.
  */
 export const HostTopology = S.Struct({
   host: TopologyHost,
@@ -268,6 +320,7 @@ export const HostTopology = S.Struct({
   overview: S.optionalKey(TopologyOverview),
   slotManifest: S.optionalKey(HostSlotManifest),
   rules: S.optionalKey(S.Array(RouteRule)),
+  registry: S.optionalKey(S.Array(TopologyRegistryEntry)),
   wires: S.Array(Wire),
   watch: S.Array(S.Struct({ event: S.String })),
 })

package/src/wireEngine.test.ts

@@ -614,7 +614,7 @@ describe('attachWireEngine', () => {
    * click sent paths from host A into panes rendering host B. All four wires
    * derive `live`, so the Wiring screen showed nothing wrong.
    */
-  test('two dots emitting the same event name drive only the wire whose `from` matches', () => {
+  test('two MicroDots emitting the same event name drive only the wire whose `from` matches', () => {
     const table = mount('wiring-table')
     const canvas = mount('pages-canvas')
     const inspector = mount('pages-inspector')