|
| 1 | +# Moss Integration |
| 2 | + |
| 3 | +**Status:** v0.1.0 pilot, in progress. The tool scaffold and dev config are implemented (#163). The Moss group context (#164) and NDOs as assets (#165) follow. Supersedes the "Moss Integration Contract" in [lobby-architecture.md](lobby-architecture.md) §9 where they differ. |
| 4 | + |
| 5 | +Moss is the Weave host (lightningrodlabs/moss). In the v0.1.0 pilot Nondominium runs as a **tool** inside Moss, started with the `weave` CLI in dev mode. The standalone build (Lobby DNA, Group DNA, invite codes) keeps compiling and running unchanged; the pilot ships Moss only. |
| 6 | + |
| 7 | +## Decisions |
| 8 | + |
| 9 | +- The pilot runs `@theweave/cli` in dev mode with a shared dev config and our own bootstrap and relay. Not the Moss app, not a curation list. |
| 10 | +- Inside Moss the Moss group is the federation layer. There is one Nondominium group per Moss group: the tool instance's `group` cell. |
| 11 | +- Each NDO is a clone cell of the `ndo` role. Profiles come from Moss, roles from `myAccountabilitiesPerGroup()`, NDOs are exposed as Moss assets. |
| 12 | +- v0.1.0 ships no work context. |
| 13 | + |
| 14 | +## Running the tool in dev mode |
| 15 | + |
| 16 | +Moss is built on Holochain 0.7.1 only in its `0.16` release candidates. The pilot uses `@theweave/cli` `0.16.0-rc.5`, which downloads a patched Holochain `0.7.1-mdns.8` that cannot see stock Holochain peers. |
| 17 | + |
| 18 | +```bash |
| 19 | +bun run build:happ # inside nix develop, produces workdir/nondominium.happ |
| 20 | +bun run moss:install # installs weave/ (Electron and the weave CLI), once |
| 21 | +bun run tool-dev # Vite on :8888 plus two Moss windows, Alice and Bob |
| 22 | +bun run tool-dev-1 # the same with Alice only |
| 23 | +``` |
| 24 | + |
| 25 | +`weave/` is a separate package outside the root workspaces so that CI and the standalone build never install Electron. `weave/weave.dev.config.ts` defines one group, `Nondominium Pilot`, created by agent 1 and joined by agent 2, with the tool served from `localhost:8888` and the `.happ` from `workdir/`. |
| 26 | + |
| 27 | +Click the group in the Moss sidebar, then the Nondominium tool. |
| 28 | + |
| 29 | +**Two machines.** Every `weave` call must pass the same `--bootstrap-url` and `--relay-url` of a server both machines reach (`kitsune2-bootstrap-srv` serves the relay on `/relay`), and the same CLI version. The group `networkSeed` in the shared config is what puts both agents in the same group. |
| 30 | + |
| 31 | +### Gotchas |
| 32 | + |
| 33 | +- `weave` loads the config through `ts-node` inside Electron. It needs TypeScript 5.x (TypeScript 7 has no JS API and the CLI crashes), `tslib` (not declared by the CLI) and a tsconfig with `"module": "commonjs"`. `weave/package.json` and `weave/tsconfig.json` carry all three. |
| 34 | +- A tool served from localhost must call `initializeHotReload()` before `WeaveClient.connect()`, or `connect()` waits forever. `ui/src/lib/moss/connect.ts` does it when `detectHost` sees the dev-mode iframe. |
| 35 | +- The group icon is limited to about 200 KB. `ui/static/icon.png` is a 128 px version of the logo. |
| 36 | +- `weave` opens an Electron window per agent. On a shared desktop, a nested X server keeps them contained: `Xephyr :99 -screen 1500x950 &` then `DISPLAY=:99 bun run tool-dev`. |
| 37 | + |
| 38 | +## What the Moss manifest does to our roles |
| 39 | + |
| 40 | +Verified in the #162 spike (see [issue #162](https://github.com/Sensorica/nondominium/issues/162)). Moss installs `workdir/happ.yaml` unchanged, deferred roles included, but it installs `group` and `ndo` as **provisioned** cells next to `lobby`, `nondominium` and `hrea`. So every tool instance already has its own `group` cell, which is the instance's group DHT and the one Nondominium group of that Moss group, and an unused `ndo` cell. NDO clones come on top. Clone limits of 64 and 512 were not refused. |
| 41 | + |
| 42 | +## The UI seam |
| 43 | + |
| 44 | +``` |
| 45 | +hc-connect.ts connectHolochainClient() |
| 46 | + detectCurrentHost() moss/host.ts standalone, or Moss (with or without hot reload) |
| 47 | + connectMoss() moss/connect.ts WeaveClient.connect + applet client |
| 48 | + standalone modes launcher, manifest, env (unchanged) |
| 49 | +``` |
| 50 | + |
| 51 | +- `moss/host.ts` decides from the page itself: the `applet://` protocol or an injected `__WEAVE_API__` is a packaged tool; a dev-build iframe carrying Moss's iframe-kind hash is a tool in dev mode; anything else is standalone. The standalone path is not touched when the host is not Moss. |
| 52 | +- `moss/connect.ts` runs hot reload when needed, connects the `WeaveClient` with our `AppletServices`, and returns the applet client Moss hands the tool, the group hash and the applet hash. Inside Moss the client signs through Moss, so none of the standalone signing-credential code runs. |
| 53 | +- `moss/applet-services.ts` is the `AppletServices` object. In #163 it declares no creatables and no assets; #165 fills `search` and `getAssetInfo`. |
| 54 | +- The connection result carries `moss` so later slices reach the `WeaveClient` through the client service (`holochainClient.moss`). |
| 55 | + |
| 56 | +Moss mode is a connection mode (`HolochainConnectionMode` gains `'moss'`). The cross-group view is not implemented: a cross-group render throws. |
| 57 | + |
| 58 | +## Open items |
| 59 | + |
| 60 | +- `weaveClient.createCloneCell(req, true)` fails whenever `req.modifiers.properties` is set, which NDO clones need. See the #162 result and #164. |
| 61 | +- `AppletServices` in `@theweave/api` `0.7.0-rc.3` has `getAssetInfo`, `search` and `creatables`. Opening an asset is not a method on it: Moss renders the tool with an `asset` view (`renderInfo.view.type === 'asset'`), and the tool calls `weaveClient.openAsset` to open other assets. |
0 commit comments