Odin/docs/hermodr-extraction-plan.md

Hermodr Extraction Plan

Objective

Hermodr is the Eve-to-browser lowering bridge. It should resolve providers through Odin's directory, subscribe to those providers for their state, render their surfaces to browsers, carry operator intent back to the provider that owns the consequence, and — new — emit a surface as static bytes for audiences that are not Verse participants.

It currently runs its own provider ingress and its own state store instead. This plan deletes that, moves the daemon into its own repository, and adds static lowering as a second output mode.

What Odin is

Odin is a rendezvous organ. It tells you what state is available, what schemas speak it, and where to reach it. It does not tell you what the state is, and it is not in the data path.

A provider owns its state and serves it. Odin owns the directory. A consumer resolves through the directory and then talks to the provider.

Hermodr's command path already works this way. findProviderCommandRoute looks a route up in the catalog and then publishes the command to the provider's own advertised endpoint. Erycina's surface says the same thing from the other side: discoveryOwner: "Odin", while canonicalSurfaceUri points at cultmesh://asgard.starfire.erycina/eve/operator/surface — Odin tells you where, you go ask Erycina.

Current mechanism

Hermodr lives in Odin as Node inside a Rust repository: src/hermodr-daemon.cjs (1,462 lines), src/hermodr-state-stream.cjs (32), test/hermodr-*.test.cjs (191), four PowerShell lifecycle scripts, and a persona avatar. Eve holds the browser-side consumer at web/hermodr-provider-catalog.mjs.

The intent path is already correct

POST /hermodr/commands/eve is generic across providers. It resolves a cultmesh:// target from the body or from the provider catalog, wraps intent as gamecult.eve.command.v1, stamps publishedBy: "hermodr-browser-lowering", publishes to the provider's advertised route, and returns a receipt. Eve's client passes commandSink: publishCommandIntent into the renderer and refuses any response that is not a correlated gamecult.eve.command_receipt.v1 in state reconciled.

This path is kept unchanged. It is also the reference for what the state path should look like.

The state path is the defect

main() constructs an OdinLivePublicationSource — an in-process Map with a read side (latest, watch, watchLifecycle) and a write side (accept, withdraw). It opens its own provider-session ingress, bound to its own address with its own session token, and feeds accepted documents into that private store. HermodrStateStreamRegistry watches the store and pushes lifecycle events to browsers.

So providers publish their state directly into Hermodr, and Hermodr decides what it holds. A surface reaches a browser only if its provider binds to Hermodr, which makes a required ingress out of something named a bridge.

The class is called OdinLivePublicationSource and lives in src/odin/. Odin does not use it. Neither the coordinator nor any Odin test references it, and the same is true of provider-session-ingress.cjs. This is Hermodr's own state machinery wearing Odin's name and filed under Odin's shared modules, which is why it reads as though Odin sanctioned it.

The loop does not close

The command path was added after the fact, on discovering the original bridge was entirely non-interactive. It was added well, but to one leg only, and the rest still assumes a viewer.

Intent leaves correctly, to the provider that owns the consequence. The consequence returns as newly published provider state — and that reaches the browser only through Hermodr's private ingress. A provider must therefore publish twice: once wherever the Verse expects it, and once into Hermodr, so the operator can see their own action land.

The core issue is not a missing write path. Intent goes out the right door and consequence comes back through the wrong one. Deleting the ingress is what closes the loop: once state arrives by subscription to the provider, a command's effect returns by the same route as every other change.

The client already carries the seed of the static case. publishCommandIntent checks liveHermodr and, when absent, logs the intent instead of posting it.

Invariants

• A provider owns its state and serves it. Nothing else holds it as truth.
• Odin owns the directory: what exists, what schema, where. Never the data path.
• Hermodr owns the browser edge: session, transport, lowering, relay of intent. It holds projections with sequence numbers, never truth.
• A lowering runtime cannot make something true by rendering it.
• Static output carries no back-channel and must not pretend otherwise.

Authority map

Owner. Each provider owns its own state, its surface document, and its command routes. Odin owns provider discovery, schema awareness, and route advertisement.

Inputs to Hermodr. Odin's catalog, to resolve providers and routes. Provider subscriptions, for state. Browser requests.

Outputs. Lowered surfaces; live state streams; typed gamecult.eve.command.v1 documents published to provider routes; receipts; static artifacts.

Derived, not owner. Everything Hermodr holds about provider state is a projection carrying a sequence number. Its staleness marks are display facts, not withdrawal decisions.

Forbidden writers. Hermodr may not accept or withdraw a publication. It may not bind a provider session. It may not author a command as itself. Odin may not become a state relay; if a consumer can read state from Odin, the directory has become the data path.

Shared paths. State resolution and command routing must use the same catalog lookup. Live and static lowering must render from the same surface graph through the same composition primitive; if they diverge visually, the static path is wrong, not the graph.

Intended change

1. Delete the ingress and the private store. Hermodr resolves a provider through the catalog, exactly as the command path already does, and subscribes to that provider for state.
2. HermodrStateStreamRegistry survives untouched. It consumes only source.forProvider(id).watchLifecycle(schemaId, recordKey, cb), which is already a narrow port. Replace what sits behind that port with a provider subscription client and every stream, sequence number, and browser keeps working.
3. Extract the daemon to GameCult/Hermodr.
4. Add static lowering as a library with a CLI entry point.

Cut line

Deleted outright:

• the OdinLivePublicationSource construction and every write into it
• createProviderSessionIngress, and the --provider-session-bind and --provider-session-token options

Leaves Odin with Hermodr, because Odin never used it:

• src/odin/live-publication-source.cjs and src/odin/provider-session-ingress.cjs, both referenced only by hermodr-daemon.cjs and test/hermodr-live-publication.test.cjs. They are misfiled Hermodr code, not shared Odin modules. If the subscription client fully replaces them, they are deleted rather than moved.
• src/odin/utils.cjs (68 lines), also Hermodr-only. Copy the handful of helpers actually used; do not extract a utility library.

Moved out of Odin, for its own reasons:

• src/odin/idunn-rudp.cjs (324 lines) follows Idunn to GameCult/Idunn as a published health-client contract. Genuinely shared — the coordinator and a health test use it too — so both consume it from its owner rather than each carrying a copy.

Resolved, not copied:

• src/odin/documents.cjs (536 lines) is the only true shared dependency, used by the coordinator, Hermodr, and two discovery tests. It survives as a decode contract and must become a published package. Forking it creates two definitions of one wire format, which is the failure this plan exists to remove.

Subtraction budget

Hermodr loses its ingress and its state store. Odin loses the Node daemon, four lifecycle scripts, three misfiled Hermodr modules, and idunn-rudp.cjs. One shared document package appears. Net: a duplicate acceptance authority deleted, src/odin/ reduced from fourteen modules to ten, one package added, one repository added.

The static lowering library is the only genuinely new surface. It earns its keep by making public storefronts hostable without a mesh, a runtime, or a daemon — the difference between a founding creator being able to self-host and not.

Build budget

Node only; no Rust targets change. Odin's crates are untouched. The new repository is one package with a test target, and static lowering adds a CLI entry to that same package rather than a second package.

Phases

Phase 1 — Idunn RUDP client. Done, as a split. The transport moved to CultLib as cultnet-ts's signed-daemon-health; Idunn now documents its connection id and schema names; Odin keeps a 65-line adapter that declares that contract. The whole-file move originally specified was not carried out, for the reasons below.

Phase 2 — Delete the ingress, in place. Done. ProviderSubscriptionSource replaces the private store behind the existing port, the ingress and its options are gone, and src/odin/ is down to twelve modules. Verified by unit tests; behaviour against a live provider over RUDP remains an operator step.

Phase 3 — Publish the document contract. Done. The 45 definitions are cultcache-ts's defineSwarmDocuments, verified byte-identical to what documents.cjs produced. Odin keeps a 26-line adapter under the name its consumers already call. utils.cjs left with Hermodr, which used one of its six functions.

Phase 4 — Extract. Done. GameCult/Hermodr, MIT, sixteen files. The three dependencies on Odin were resolved rather than carried: the catalog comes from CultLib, Idunn's health contract is declared locally over the CultLib transport with sourceRuntimeId hermodr, and parseArgs is seventeen lines of args.cjs. src/odin/ is down from fourteen modules to eleven, and Odin's CommonJS surface from sixteen files to twelve.

Phase 5 — Static lowering. Done, in GameCult/Hermodr. A library and CLI rendering a surface graph to standalone HTML through the same renderEveSurface the browser uses, under jsdom, with command controls disabled and labelled because a static page has no back-channel. Runnable without the daemon.

All five phases are complete. This document stays here as the record of what left Odin and why; the work now happens in Hermodr.

Verification

Positive:

• A provider that publishes only to its own advertised address reaches a browser through Hermodr. This fails today and is the point of the work.
• Live state streams keep their sequence numbers, and stale and reconnected transitions still fire across a provider restart.
• A browser command still reaches its provider and returns a correlated receipt.
• Static output of a surface renders equivalently to the live lowering of the same graph.

Negative, and these are the ones that prove the authority moved:

• Hermodr cannot be made to accept a provider publication. The code path is gone, not merely unused.
• Starting Hermodr with the removed ingress options fails loudly rather than silently ignoring them.
• With Odin stopped, Hermodr cannot resolve providers it has not already resolved, but existing provider subscriptions keep delivering. If stopping Odin stops live state, Odin is in the data path and this plan failed.
• Nothing reads state from Odin. A consumer able to do so proves the directory became a relay.
• Two Hermodr instances against the same provider show the same state.
• Static output contains no command controls that appear operable. A dead button in a static page is a lie about a back-channel that does not exist.

Why Phase 1 was split rather than moved

Reading idunn-rudp.cjs before moving it changed the answer. Of its 324 lines, 13 mention Idunn, and most of those are error message strings. The genuinely Idunn-owned content is two constants: the connection ID 0x1d0d0001 and the schema name idunn.signed_daemon_health.v1. Everything else — Ed25519 signing, RUDP session management, packet receipt, endpoint parsing, msgpack framing — is generic CultNet client plumbing.

Moving the file to Idunn would put 311 lines of transport code into a Rust repository with no Node packaging, and would give Odin a cross-repo filesystem dependency on a sibling checkout. The file already resolves CultLib by walking __dirname/../../../CultLib, which works only while Odin sits beside CultLib; Erycina had the identical bug and it broke the moment that repository moved. Repeating it deliberately, in the plan whose purpose is removing misplaced ownership, would be a poor trade.

It also buys nothing yet. The duplication it prevents does not exist until Hermodr leaves in Phase 4, because both consumers still live in this repository.

Three options, in the order I would rank them:

1. Generic to CultLib, constants to Idunn. The transport belongs beside cultnet-ts, which Odin already resolves into and Hermodr will too. Idunn owns the connection ID and the schema name. This is the real fix, and it removes the sibling-path bug rather than relocating it.
2. Defer to Phase 4. Correct and free. Move it when the duplication actually threatens, and decide the shape then.
3. Move it whole to Idunn. As originally written. Cheapest to type, and it puts transport code where it does not belong while adding a fragile path.

Option 1 was chosen and carried out. idunn-rudp.cjs fell from 324 lines to 65: Idunn's three constants and the call shapes Odin's consumers already use. packages/cultnet-ts/src/signed-daemon-health.ts holds the transport, taking the contract as a parameter. Idunn's docs/signed-daemon-health-authority.md gained the wire-contract table it was missing — the connection id had existed only in this consumer's code.

Both the moved module and the adapter dropped the sibling-path assumption on the way, honouring CULTLIB_ROOT instead of walking up three directories from wherever the file happens to sit.

Phase 3's remaining decision is unchanged: documents.cjs is now the only genuinely shared dependency left between Odin and a future Hermodr.

Open questions for the operator

1. documents.cjs ownership. Published from Odin, or promoted into CultLib beside the other typed contracts? It is a wire format several services share, which argues for CultLib, but Odin authors it.
2. Ephemeral view state. Expanded panels, unsent field contents, optimistic pending states. Client-side today by omission rather than decision.
3. Static lowering and identity. A live surface knows who is viewing; a static artifact does not. Either static surfaces are public-only, or the lowering takes an audience parameter and emits per-audience artifacts. Public-only is smaller and covers the storefront.