Extract Hermodr from Odin

Hermodr is the Eve browser lowering. It was an organ of Odin: Node inside a Rust
repository, sharing a common module directory with Odin's coordinator, and until
recently running its own provider-session ingress and accepting publications
into a private store.

The ingress was removed first, deliberately. An extraction that carried it would
have moved a second acceptance authority into a repository of its own and called
that progress. What moved here is a bridge: it resolves providers through Odin's
catalog, reads those providers directly, and relays operator intent to
provider-advertised command routes.

Contents: the daemon, the provider subscription source and its lifecycle tests,
the state stream registry, the browser catalog tests, the four lifecycle
scripts, and the persona avatar.

Three dependencies on Odin were resolved rather than carried. The swarm document
catalog now comes from CultLib's cultcache-ts alongside defineDocumentType.
Idunn's health contract is declared locally in idunn-health.cjs, over the generic
transport that also moved to CultLib, with sourceRuntimeId "hermodr" rather than
Odin's. parseArgs is seventeen lines in args.cjs, because Hermodr used one of
that utility module's six functions and carrying the other five would have been
carrying a library nobody here reads.

MIT, matching CultLib, Odin, Idunn, Eve and Erycina, so the deployment chain is
one a creator may lawfully run end to end.

Verified: 17 tests pass, every module loads with CultLib resolving from the new
location, and no import references Odin. Not verified: behaviour against a live
provider over RUDP, which needs a running Verse.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

.gitignore

@@ -0,0 +1,4 @@
+node_modules/
+*.log
+.DS_Store
+scratch/

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GameCult
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,74 @@
+# Hermodr
+
+Hermodr is the Eve browser lowering. It resolves providers through Odin's
+catalog, reads those providers for their state, renders their surfaces to
+browsers, and relays operator intent back as typed CultMesh command documents.
+
+It owns the browser edge. It does not own truth.
+
+## Authority
+
+- **Providers** own their state and serve it. Hermodr reads; it never accepts.
+- **Odin** owns discovery: what exists, what schema speaks it, where to reach
+  it. Odin is not in the data path, and nothing here reads state *from* Odin.
+- **Hermodr** owns session, transport, lowering, and the relay of intent.
+  Everything it holds about provider state is a projection carrying a sequence
+  number. Its staleness marks are display facts, not withdrawal decisions.
+
+A lowering runtime cannot make something true by rendering it.
+
+## The round trip
+
+Intent leaves by `POST /hermodr/commands/eve`, which resolves a `cultmesh://`
+target from the request or the provider catalog, wraps the body as
+`gamecult.eve.command.v1`, stamps `publishedBy: "hermodr-browser-lowering"`, and
+publishes to the provider's own advertised route. The provider decides whether
+to act. Eve's client refuses any response that is not a correlated
+`gamecult.eve.command_receipt.v1` in state `reconciled`.
+
+Consequence returns as newly published provider state, by the same subscription
+as every other change. That is the whole point of the split: intent and
+consequence travel the same road in opposite directions, and neither passes
+through a store Hermodr owns.
+
+## Running it
+
+```bash
+npm start -- --host 127.0.0.1 --port 8798
+```
+
+Needs a reachable Odin catalog and `CULTLIB_ROOT` pointing at a CultLib
+checkout. Provider read cadence is `--provider-poll-interval-ms`, default 2000.
+
+```bash
+npm test     # unit tests, no live Verse required
+npm run check
+```
+
+## Known shape
+
+Provider state is read by polling, wrapped in lifecycle semantics that emit
+snapshot, update, and withdrawn events with sequence numbers. Polling is a first
+cut: CultMesh ships `cultMeshPollingDocumentWatcher` for exactly this shape, and
+a push subscription belongs here eventually. It does not change the authority,
+which is why the swap was made before the move.
+
+One invariant is easy to get wrong and quiet when you do: **a failed read is not
+a withdrawal.** A provider restart or a dropped packet must not render as the
+provider retracting state it still holds. Read errors are reported and the
+previous value stands; only genuine absence withdraws. Both paths are tested.
+
+## History
+
+Hermodr was an organ of Odin, and until recently it ran its own provider-session
+ingress and accepted publications into a private store. A surface reached a
+browser only if its provider bound to Hermodr specifically, so a provider had to
+publish twice: once where the Verse expected it, and once into Hermodr so an
+operator could watch their own command land.
+
+That ingress is gone. The extraction happened after it was removed, so what
+moved here was a bridge rather than a second acceptance authority wearing one's
+name.
+
+`GameCult/Odin` holds the coordinator and the Rust organs. `GameCult/CultLib`
+holds the swarm document catalog and the CultNet transports this depends on.

package.json

@@ -0,0 +1,13 @@
+{
+  "name": "@gamecult/hermodr",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Eve browser lowering: resolves providers through Odin, reads their state, renders surfaces, and relays operator intent as typed CultMesh command documents.",
+  "type": "commonjs",
+  "scripts": {
+    "start": "node src/hermodr-daemon.cjs",
+    "test": "node --test test/*.test.cjs",
+    "check": "node --check src/hermodr-daemon.cjs && node --check src/hermodr-provider-subscription.cjs && node --check src/hermodr-state-stream.cjs && node --check src/idunn-health.cjs && node --check src/args.cjs"
+  },
+  "license": "MIT"
+}

scripts/health-hermodr.ps1

@@ -0,0 +1,14 @@
+param(
+  [string] $BaseUrl = $(if ($env:HERMODR_BASE_URL) { $env:HERMODR_BASE_URL } else { "http://127.0.0.1:8798" })
+)
+
+$ErrorActionPreference = "Stop"
+
+$healthUrl = $BaseUrl.TrimEnd("/") + "/health"
+$response = Invoke-RestMethod -Uri $healthUrl -Method Get -TimeoutSec 3
+
+if ($response.authority -ne "lowering-only") {
+  throw "Hermodr responded, but did not report lowering-only authority."
+}
+
+Write-Host "Hermodr browser lowering responds at $BaseUrl; authority=$($response.authority). This is not daemon health or Verse discovery authority."

scripts/restart-hermodr.ps1

@@ -0,0 +1,23 @@
+param(
+  [string] $HostAddress = $(if ($env:HERMODR_BIND_HOST) { $env:HERMODR_BIND_HOST } else { "127.0.0.1" }),
+  [int] $Port = $(if ($env:HERMODR_PORT) { [int]$env:HERMODR_PORT } else { 8798 }),
+  [string] $OdinCultMeshUri = $(if ($env:HERMODR_ODIN_CULTMESH_URI) { $env:HERMODR_ODIN_CULTMESH_URI } elseif ($env:ODIN_CULTMESH_URI) { $env:ODIN_CULTMESH_URI } else { "cultmesh://odin/rendezvous/provider-catalog" }),
+  [string] $IdunnRudpHealth = $(if ($env:HERMODR_IDUNN_RUDP_HEALTH) { $env:HERMODR_IDUNN_RUDP_HEALTH } else { $env:IDUNN_RUDP_HEALTH }),
+  [string] $IdunnDaemon = "hermodr",
+  [string] $IdunnHealthContract = "hermodr.cultnet-rudp-browser-lowering-health"
+)
+
+$ErrorActionPreference = "Stop"
+
+if ($env:IDUNN_ACTUATOR -ne "1" -or $env:IDUNN_COMMAND_AUTHORITY -ne "idunn-daemon") {
+  throw "restart-hermodr.ps1 is an Idunn actuator body. Redeploy by poking Idunn; direct service restart is not an owned path."
+}
+
+$stop = Join-Path $PSScriptRoot "stop-hermodr.ps1"
+$start = Join-Path $PSScriptRoot "start-hermodr.ps1"
+
+if (Test-Path -LiteralPath $stop) {
+  & $stop
+}
+
+& $start -HostAddress $HostAddress -Port $Port -OdinCultMeshUri $OdinCultMeshUri -IdunnRudpHealth $IdunnRudpHealth -IdunnDaemon $IdunnDaemon -IdunnHealthContract $IdunnHealthContract -NoWindow

scripts/start-hermodr.ps1

@@ -0,0 +1,57 @@
+param(
+  [string] $HostAddress = $(if ($env:HERMODR_BIND_HOST) { $env:HERMODR_BIND_HOST } else { "127.0.0.1" }),
+  [int] $Port = $(if ($env:HERMODR_PORT) { [int]$env:HERMODR_PORT } else { 8798 }),
+  [string] $OdinCultMeshUri = $(if ($env:HERMODR_ODIN_CULTMESH_URI) { $env:HERMODR_ODIN_CULTMESH_URI } elseif ($env:ODIN_CULTMESH_URI) { $env:ODIN_CULTMESH_URI } else { "cultmesh://odin/rendezvous/provider-catalog" }),
+  [string] $IdunnRudpHealth = $(if ($env:HERMODR_IDUNN_RUDP_HEALTH) { $env:HERMODR_IDUNN_RUDP_HEALTH } else { $env:IDUNN_RUDP_HEALTH }),
+  [string] $IdunnDaemon = "hermodr",
+  [string] $IdunnHealthContract = "hermodr.cultnet-rudp-browser-lowering-health",
+  [string] $StateDir = $(Join-Path $PSScriptRoot "..\scratch\Hermodr"),
+  [switch] $NoWindow
+)
+
+$ErrorActionPreference = "Stop"
+
+foreach ($name in @(
+  "HERMODR_ODIN_HTTP_BASE",
+  "HERMODR_ODIN_WS_BASE",
+  "HERMODR_ODIN_STATE_PATH",
+  "HERMODR_SLEIPNIR_COMMAND_RUDP",
+  "HERMODR_SLEIPNIR_COMMAND_ENDPOINT",
+  "HERMODR_MUNINN_RUDP",
+  "HERMODR_AETHERIA_COMMAND_RUDP",
+  "HERMODR_ODIN_CULTMESH_STORE",
+  "ODIN_CULTMESH_STORE"
+)) {
+  if (-not [string]::IsNullOrWhiteSpace([Environment]::GetEnvironmentVariable($name))) {
+    throw "$name was removed. Hermodr lowers Odin/CultMesh state for browsers and may only publish typed CultMesh command documents."
+  }
+}
+if (-not [string]::IsNullOrWhiteSpace($env:HERMODR_COMMAND_STORE)) {
+  throw "HERMODR_COMMAND_STORE was removed. Hermodr publishes typed commands through provider-advertised CultMesh routes and records visible witnesses in Odin's CultMesh cache."
+}
+
+$node = "node"
+$Hermodr = Join-Path $PSScriptRoot "..\src\hermodr-daemon.cjs"
+$arguments = @(
+  $Hermodr,
+  "--host", $HostAddress,
+  "--port", $Port,
+  "--odin-cultmesh-uri", $OdinCultMeshUri
+)
+if (-not [string]::IsNullOrWhiteSpace($IdunnRudpHealth)) {
+  $arguments += @(
+    "--idunn-rudp-health", $IdunnRudpHealth,
+    "--idunn-daemon", $IdunnDaemon,
+    "--idunn-health-contract", $IdunnHealthContract
+  )
+}
+
+if ($NoWindow) {
+  New-Item -ItemType Directory -Force -Path $StateDir | Out-Null
+  $proc = Start-Process -FilePath $node -ArgumentList $arguments -WindowStyle Hidden -PassThru
+  $proc.Id | Set-Content -Encoding ASCII -LiteralPath (Join-Path $StateDir "hermodr.pid")
+  Write-Host "Started Hermodr browser lowering at http://${HostAddress}:${Port}/"
+  return
+}
+
+& $node @arguments

scripts/stop-hermodr.ps1

@@ -0,0 +1,22 @@
+param(
+  [string] $StateDir = (Join-Path (Split-Path -Parent $PSScriptRoot) "scratch\Hermodr")
+)
+
+$ErrorActionPreference = "Stop"
+
+$pidPath = Join-Path $StateDir "hermodr.pid"
+if (-not (Test-Path $pidPath)) {
+  Write-Host "No Hermodr PID file found at $pidPath."
+  exit 0
+}
+
+$HermodrPid = (Get-Content -Raw $pidPath).Trim()
+if ($HermodrPid -match "^\d+$") {
+  $process = Get-Process -Id ([int] $HermodrPid) -ErrorAction SilentlyContinue
+  if ($process) {
+    Stop-Process -Id $process.Id
+    Write-Host "Stopped Hermodr PID $HermodrPid."
+  }
+}
+
+Remove-Item -LiteralPath $pidPath -Force

src/args.cjs

@@ -0,0 +1,31 @@
+"use strict";
+
+// Command-line parsing, kept deliberately dumb.
+//
+// Keys are stored exactly as typed, so --provider-poll-interval-ms and
+// --providerPollIntervalMs are different keys. Option readers accept both, and
+// rejectRemovedOptions in the daemon rejects both, because a removed option that
+// is silently ignored under one spelling is worse than no rejection at all.
+//
+// This came from Odin's src/odin/utils.cjs, of which Hermodr used this one
+// function out of six. Carrying the other five would have been carrying a
+// library nobody reads.
+
+function parseArgs(argv) {
+  const parsed = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (!arg.startsWith("--")) continue;
+    const key = arg.slice(2);
+    const next = argv[index + 1];
+    if (!next || next.startsWith("--")) {
+      parsed[key] = true;
+    } else {
+      parsed[key] = next;
+      index += 1;
+    }
+  }
+  return parsed;
+}
+
+module.exports = { parseArgs };

src/hermodr-provider-subscription.cjs

@@ -0,0 +1,154 @@
+"use strict";
+
+// Provider state subscription for the browser lowering.
+//
+// Hermodr previously ran its own provider-session ingress and accepted
+// publications into a private store, which made it a required ingress rather
+// than a bridge: a surface reached a browser only if its provider bound to
+// Hermodr specifically. Providers own their state. Odin publishes where to find
+// it. This source resolves a provider through the catalog and reads that
+// provider directly, exactly as the command path already routes intent.
+//
+// It presents the same narrow port the previous store did -
+// forProvider(id) -> { latest, watch, watchLifecycle } - so
+// HermodrStateStreamRegistry, its sequence numbers, and its stale/reconnected
+// transitions are untouched.
+//
+// readDocument is injected. That keeps the polling and lifecycle semantics
+// testable without a live Verse, and keeps CultMesh transport out of this file.
+
+const DEFAULT_POLL_INTERVAL_MS = 2_000;
+
+class ProviderSubscriptionSource {
+  constructor(readDocument, options = {}) {
+    if (typeof readDocument !== "function") {
+      throw new Error("Provider subscription source requires a readDocument(providerId, schemaId, recordKey) function.");
+    }
+    this.readDocument = readDocument;
+    this.pollIntervalMs = Number.isFinite(options.pollIntervalMs) && options.pollIntervalMs > 0
+      ? options.pollIntervalMs
+      : DEFAULT_POLL_INTERVAL_MS;
+    this.setInterval = options.setInterval || setInterval;
+    this.clearInterval = options.clearInterval || clearInterval;
+    this.onError = options.onError || (() => {});
+    this.entries = new Map();
+    this.sequence = 0;
+  }
+
+  forProvider(providerId) {
+    return {
+      latest: (schemaId, recordKey) => this.latest(providerId, schemaId, recordKey),
+      watch: (schemaId, recordKey, callback) => this.watch(providerId, schemaId, recordKey, callback),
+      watchLifecycle: (schemaId, recordKey, callback) => this.watchLifecycle(providerId, schemaId, recordKey, callback),
+    };
+  }
+
+  async latest(providerId, schemaId, recordKey) {
+    const value = await this.readDocument(providerId, schemaId, recordKey);
+    if (value === undefined || value === null) {
+      throw new Error(`Provider ${providerId} published no ${schemaId}:${recordKey}.`);
+    }
+    return value;
+  }
+
+  watch(providerId, schemaId, recordKey, callback) {
+    return this.watchLifecycle(providerId, schemaId, recordKey, (event) => {
+      if (event.kind !== "withdrawn") callback(event.value);
+    });
+  }
+
+  watchLifecycle(providerId, schemaId, recordKey, callback) {
+    const key = keyOf(providerId, schemaId, recordKey);
+    let entry = this.entries.get(key);
+    if (!entry) {
+      entry = {
+        providerId,
+        schemaId,
+        recordKey,
+        listeners: new Set(),
+        value: undefined,
+        present: false,
+        timer: null,
+        polling: false,
+      };
+      this.entries.set(key, entry);
+      entry.timer = this.setInterval(() => { this.poll(key); }, this.pollIntervalMs);
+      if (typeof entry.timer?.unref === "function") entry.timer.unref();
+    }
+
+    entry.listeners.add(callback);
+    if (entry.present) {
+      callback({ kind: "snapshot", sequence: ++this.sequence, value: entry.value });
+    }
+    // First listener on a cold entry still needs a value without waiting a full
+    // interval. Subsequent listeners piggyback on the shared poll.
+    this.poll(key);
+
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      entry.listeners.delete(callback);
+      if (entry.listeners.size === 0) {
+        this.clearInterval(entry.timer);
+        this.entries.delete(key);
+      }
+    };
+  }
+
+  async poll(key) {
+    const entry = this.entries.get(key);
+    if (!entry || entry.polling) return;
+    entry.polling = true;
+    try {
+      let value;
+      try {
+        value = await this.readDocument(entry.providerId, entry.schemaId, entry.recordKey);
+      } catch (error) {
+        // A read failure is not a withdrawal. The provider may be restarting,
+        // and claiming withdrawal would let a transport hiccup look like the
+        // provider retracting state it still holds.
+        this.onError(error, { providerId: entry.providerId, schemaId: entry.schemaId, recordKey: entry.recordKey });
+        return;
+      }
+
+      if (!this.entries.has(key)) return;
+
+      const missing = value === undefined || value === null;
+      if (missing) {
+        if (entry.present) {
+          entry.present = false;
+          entry.value = undefined;
+          this.emit(entry, { kind: "withdrawn", sequence: ++this.sequence, reason: "withdrawn" });
+        }
+        return;
+      }
+
+      if (entry.present && equivalent(entry.value, value)) return;
+
+      const kind = entry.present ? "update" : "snapshot";
+      entry.present = true;
+      entry.value = value;
+      this.emit(entry, { kind, sequence: ++this.sequence, value });
+    } finally {
+      entry.polling = false;
+    }
+  }
+
+  emit(entry, event) {
+    for (const listener of entry.listeners) listener(event);
+  }
+}
+
+function keyOf(providerId, schemaId, recordKey) {
+  if (!String(providerId || "").trim() || !String(schemaId || "").trim() || !String(recordKey || "").trim()) {
+    throw new Error("Provider subscription requires providerId, schemaId, and recordKey.");
+  }
+  return `${providerId}\u001f${schemaId}\u001f${recordKey}`;
+}
+
+function equivalent(left, right) {
+  return JSON.stringify(left) === JSON.stringify(right);
+}
+
+module.exports = { ProviderSubscriptionSource, DEFAULT_POLL_INTERVAL_MS };

src/hermodr-state-stream.cjs

@@ -0,0 +1,32 @@
+"use strict";
+
+class HermodrStateStreamRegistry {
+  constructor(source) { this.source = source; this.entries = new Map(); }
+  acquire(selection, listener) {
+    const key = `${selection.schemaId}\u001f${selection.recordKey}`;
+    let entry = this.entries.get(key);
+    if (!entry) {
+      entry = { listeners: new Set([listener]), sequence: 0, stale: false, unsubscribe: null };
+      entry.unsubscribe = this.source.forProvider(selection.providerId).watchLifecycle(selection.schemaId, selection.recordKey, event => {
+        const type = event.kind === "withdrawn" ? "stale" : entry.stale ? "reconnected" : event.kind;
+        entry.stale = type === "stale";
+        const lowered = { type, sequence: ++entry.sequence, source: selection,
+          ...(event.value === undefined ? {} : { value: event.value }),
+          ...(event.reason ? { reason: event.reason } : {}) };
+        for (const subscriber of entry.listeners) subscriber(lowered);
+      });
+      this.entries.set(key, entry);
+    } else {
+      entry.listeners.add(listener);
+    }
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      entry.listeners.delete(listener);
+      if (entry.listeners.size === 0) { entry.unsubscribe(); this.entries.delete(key); }
+    };
+  }
+}
+
+module.exports = { HermodrStateStreamRegistry };

src/idunn-health.cjs

@@ -0,0 +1,65 @@
+"use strict";
+
+// Idunn health publication, as Odin consumes it.
+//
+// The transport used to live here: 300-odd lines of socket handling, RUDP
+// handshaking, Ed25519 signing, and packet receipt, of which almost nothing was
+// about Idunn. That is generic CultNet client work and now lives in CultLib as
+// cultnet-ts's signed-daemon-health module.
+//
+// What remains is what Odin actually needs to know: Idunn's wire contract, and
+// the shape of the calls its consumers already make. The constants are defined
+// by Idunn in docs/signed-daemon-health-authority.md. They are declared here,
+// not decided here; if they change, that document changes first.
+
+const path = require("path");
+const { createRequire } = require("module");
+
+const cultLibRoot = process.env.CULTLIB_ROOT
+  ? path.resolve(process.env.CULTLIB_ROOT)
+  : path.resolve(__dirname, "..", "..", "CultLib");
+
+const requireCultNet = createRequire(path.resolve(cultLibRoot, "packages", "cultnet-ts", "package.json"));
+
+const {
+  CULTNET_RUDP_PROTOCOL_ID,
+  createSignedDaemonHealthPublisher,
+  publishSignedDaemonHealth,
+  signedDaemonHealthPayload,
+  signedDaemonHealthSigningMessage,
+} = requireCultNet("./dist/index.js");
+
+// Idunn's contract. Owner: GameCult/Idunn, docs/signed-daemon-health-authority.md.
+const IDUNN_HEALTH_CONTRACT = Object.freeze({
+  connectionId: 0x1d0d0001,
+  signedSchemaId: "idunn.signed_daemon_health.v1",
+  unsignedSchemaId: "idunn.daemon_health",
+  messageIdPrefix: "odin-health",
+});
+
+function createIdunnRudpHealthPublisher(options) {
+  if (!options) return null;
+  return createSignedDaemonHealthPublisher({
+    sourceRuntimeId: "hermodr",
+    ...options,
+    contract: IDUNN_HEALTH_CONTRACT,
+  });
+}
+
+const publishIdunnRudpHealth = publishSignedDaemonHealth;
+const signedHealthPayload = signedDaemonHealthPayload;
+
+// The signing purpose is Idunn's signed schema id, so a statement signed for
+// Idunn cannot verify as another service's health.
+function signingMessage(payload) {
+  return signedDaemonHealthSigningMessage(IDUNN_HEALTH_CONTRACT.signedSchemaId, payload);
+}
+
+module.exports = {
+  CULTNET_RUDP_PROTOCOL_ID,
+  IDUNN_HEALTH_CONTRACT,
+  createIdunnRudpHealthPublisher,
+  publishIdunnRudpHealth,
+  signedHealthPayload,
+  signingMessage,
+};

test/hermodr-catalog.test.cjs

@@ -0,0 +1,70 @@
+"use strict";
+
+const assert = require("node:assert/strict");
+const test = require("node:test");
+
+const {
+  createBrowserCatalog,
+  findProviderCdnRoute,
+  hermodrRudpPeerOptions,
+  normalizeProviderAdvertisement,
+  normalizeSurfaceState,
+  surfaceRecordKeys,
+} = require("../src/hermodr-daemon.cjs");
+
+test("Hermodr outbound RUDP peers bind beyond loopback", () => {
+  const options = hermodrRudpPeerOptions();
+  assert.equal(options.bindHost, "0.0.0.0");
+  assert.equal(options.connectTimeoutMs, 2_000);
+});
+
+const provider = normalizeProviderAdvertisement({
+  providerId: "fixture.game",
+  title: "Fixture game",
+  surfaces: [
+    { surfaceId: "fixture.menu", surfaceKind: "menu", recordRef: "cultmesh://fixture/surfaces/menu" },
+    { surfaceId: "fixture.world", surfaceKind: "interactive-world", recordRef: "cultmesh://fixture/surfaces/world" },
+  ],
+  routes: [{
+    id: "fixture-cdn",
+    uri: "rudp://127.0.0.1:3000",
+    tags: ["cultmesh-cdn", "asset_blob"],
+  }],
+});
+
+test("Hermodr preserves every advertised surface and its semantic kind", () => {
+  const catalog = createBrowserCatalog([provider], { odinCultMeshUri: "cultmesh://odin/providers" });
+  assert.deepEqual(catalog.surfaces.map(surface => surface.surfaceId), ["fixture.menu", "fixture.world"]);
+  assert.equal(catalog.surfaces[1].surfaceKind, "interactive-world");
+  assert.equal(catalog.providers[0].surfaces[1].recordRef, "cultmesh://fixture/surfaces/world");
+});
+
+test("surface reads prefer the provider-advertised record reference", () => {
+  const catalog = createBrowserCatalog([provider]);
+  assert.equal(surfaceRecordKeys(catalog, "fixture.game", "fixture.world")[0], "cultmesh://fixture/surfaces/world");
+});
+
+test("surface-state normalization lowers MessagePack array records", () => {
+  const state = normalizeSurfaceState([
+    "gjallar.overview",
+    "Gjallar",
+    7,
+    "2026-08-25T00:00:00Z",
+    [
+      "gjallar.overview.surface",
+      ["root", "dashboard", { title: "Gjallar" }, [], [], [], { mode: "weighted-bisect" }, {}],
+      [],
+    ],
+  ], "gjallar.overview");
+
+  assert.equal(state.surface.id, "gjallar.overview.surface");
+  assert.equal(state.surface.root.kind, "dashboard");
+  assert.equal(state.surface.root.layout.mode, "weighted-bisect");
+});
+
+test("CDN routing follows the asset URI provider instead of a product name", () => {
+  const catalog = createBrowserCatalog([provider]);
+  const route = findProviderCdnRoute(catalog, "cultmesh://fixture.game/assets/player");
+  assert.equal(route.providerId, "fixture.game");
+  assert.equal(route.endpoint, "rudp://127.0.0.1:3000");
+});

test/hermodr-provider-subscription.test.cjs

@@ -0,0 +1,188 @@
+"use strict";
+
+const test = require("node:test");
+const assert = require("node:assert/strict");
+
+const { ProviderSubscriptionSource } = require("../src/hermodr-provider-subscription.cjs");
+
+function harness(reads) {
+  const state = { value: reads.shift(), calls: 0, cleared: 0 };
+  let tick = null;
+  const source = new ProviderSubscriptionSource(
+    async () => {
+      state.calls += 1;
+      if (state.value instanceof Error) throw state.value;
+      return state.value;
+    },
+    {
+      setInterval: (fn) => { tick = fn; return { unref() {} }; },
+      clearInterval: () => { state.cleared += 1; tick = null; },
+      onError: () => {},
+    },
+  );
+  return {
+    source,
+    state,
+    set: (value) => { state.value = value; },
+    poll: async () => { if (tick) tick(); await flush(); },
+    hasTimer: () => tick !== null,
+  };
+}
+
+async function flush() {
+  for (let i = 0; i < 4; i += 1) await new Promise((resolve) => setImmediate(resolve));
+}
+
+function collect(source, providerId = "erycina", schemaId = "gamecult.eve.surface_state.v1", recordKey = "erycina") {
+  const events = [];
+  const release = source.forProvider(providerId).watchLifecycle(schemaId, recordKey, (event) => events.push(event));
+  return { events, release };
+}
+
+test("first watch emits a snapshot of the provider's document", async () => {
+  const h = harness([{ title: "Erycina" }]);
+  const { events } = collect(h.source);
+  await flush();
+
+  assert.equal(events.length, 1);
+  assert.equal(events[0].kind, "snapshot");
+  assert.deepEqual(events[0].value, { title: "Erycina" });
+});
+
+test("an unchanged document emits nothing further", async () => {
+  const h = harness([{ title: "Erycina" }]);
+  const { events } = collect(h.source);
+  await flush();
+  await h.poll();
+  await h.poll();
+
+  assert.equal(events.length, 1);
+});
+
+test("a changed document emits an update", async () => {
+  const h = harness([{ version: 1 }]);
+  const { events } = collect(h.source);
+  await flush();
+  h.set({ version: 2 });
+  await h.poll();
+
+  assert.equal(events.length, 2);
+  assert.equal(events[1].kind, "update");
+  assert.deepEqual(events[1].value, { version: 2 });
+  assert.ok(events[1].sequence > events[0].sequence);
+});
+
+test("a document that disappears is withdrawn", async () => {
+  const h = harness([{ version: 1 }]);
+  const { events } = collect(h.source);
+  await flush();
+  h.set(null);
+  await h.poll();
+
+  assert.equal(events.at(-1).kind, "withdrawn");
+  assert.equal(events.at(-1).reason, "withdrawn");
+});
+
+test("a document that returns after withdrawal emits a fresh snapshot", async () => {
+  const h = harness([{ version: 1 }]);
+  const { events } = collect(h.source);
+  await flush();
+  h.set(null);
+  await h.poll();
+  h.set({ version: 3 });
+  await h.poll();
+
+  assert.equal(events.at(-1).kind, "snapshot");
+  assert.deepEqual(events.at(-1).value, { version: 3 });
+});
+
+test("a read failure is not a withdrawal", async () => {
+  // A provider restart or a dropped packet must not look like the provider
+  // retracting state it still holds. This is the invariant that stops a
+  // transport hiccup from being rendered as authoritative absence.
+  const h = harness([{ version: 1 }]);
+  const { events } = collect(h.source);
+  await flush();
+  const before = events.length;
+
+  h.set(new Error("rudp timeout"));
+  await h.poll();
+  await h.poll();
+
+  assert.equal(events.length, before);
+  assert.equal(events.at(-1).kind, "snapshot");
+});
+
+test("state survives the failure and updates once reads recover", async () => {
+  const h = harness([{ version: 1 }]);
+  const { events } = collect(h.source);
+  await flush();
+  h.set(new Error("rudp timeout"));
+  await h.poll();
+  h.set({ version: 9 });
+  await h.poll();
+
+  assert.equal(events.at(-1).kind, "update");
+  assert.deepEqual(events.at(-1).value, { version: 9 });
+});
+
+test("releasing the last listener stops polling", async () => {
+  const h = harness([{ version: 1 }]);
+  const { release } = collect(h.source);
+  await flush();
+  assert.ok(h.hasTimer());
+
+  release();
+
+  assert.equal(h.state.cleared, 1);
+  assert.equal(h.hasTimer(), false);
+});
+
+test("a second listener shares one poll and receives the current snapshot", async () => {
+  const h = harness([{ version: 1 }]);
+  const first = collect(h.source);
+  await flush();
+  const callsAfterFirst = h.state.calls;
+
+  const second = collect(h.source);
+  await flush();
+
+  assert.equal(second.events[0].kind, "snapshot");
+  assert.deepEqual(second.events[0].value, { version: 1 });
+  // The shared entry polls once per interval regardless of listener count.
+  await h.poll();
+  assert.ok(h.state.calls <= callsAfterFirst + 2);
+
+  first.release();
+  assert.equal(h.state.cleared, 0, "the entry survives while one listener remains");
+  second.release();
+  assert.equal(h.state.cleared, 1);
+});
+
+test("watch skips withdrawal events and yields values only", async () => {
+  const h = harness([{ version: 1 }]);
+  const values = [];
+  h.source.forProvider("erycina").watch("s", "k", (value) => values.push(value));
+  await flush();
+  h.set(null);
+  await h.poll();
+  h.set({ version: 2 });
+  await h.poll();
+
+  assert.deepEqual(values, [{ version: 1 }, { version: 2 }]);
+});
+
+test("latest refuses to invent a document the provider does not publish", async () => {
+  const h = harness([null]);
+  await assert.rejects(
+    () => h.source.forProvider("erycina").latest("gamecult.eve.surface_state.v1", "erycina"),
+    /published no/,
+  );
+});
+
+test("a subscription requires provider, schema, and record key", () => {
+  const h = harness([{}]);
+  assert.throws(() => h.source.forProvider("").watchLifecycle("s", "k", () => {}), /requires providerId/);
+  assert.throws(() => h.source.forProvider("p").watchLifecycle("", "k", () => {}), /requires providerId/);
+  assert.throws(() => h.source.forProvider("p").watchLifecycle("s", "", () => {}), /requires providerId/);
+});