# Worked Example 01 — Bringing Up a Galaxy An installation from an empty machine to a fleet that can take an order, in the order the things actually have to happen. It follows [[Low Passage]] as the specification stands; where the two disagree, the specification wins and this document is the one that is wrong. **Nothing here has been run end to end.** M0 has not been built, so every command below is specified rather than demonstrated. The last section records what has been settled along the way and names what the machine is most likely to disagree with first; this document is meant to be corrected as that happens. ## Why it takes three acts The installation has to exist before anything else does, for two reasons that are prerequisites rather than preferences. **A node cannot enrol without a certificate, and certificates come from the CA** — so the Galaxy has to exist before the first machine joins it. **The store has to hold the bootstrap equipment before a flagship can fit it** — and since a person's only way into a fleet is a channel, and a channel is equipment, that order is what lets somebody reach the fleet at all. ```mermaid flowchart LR A["Empty machine"] --> B["galaxy init<br/>CA · record · store · library"] B --> C["node join<br/>key · certificate · identity"] C --> D["flagship init<br/>fleet · task force · ship · crew"] D --> E["First light<br/>a person reaches the fleet"] ``` ## Before you start The machine here is Windows 10 with OTP 29 (ERTS 17.1.1), `rebar3` 3.28.0 at `C:\Users\<you>\bin`, and Elixir 1.20.5 compiled against the same OTP. `inets` httpd serves on it and is the server the bridge standardizes on; Cowboy does not, on this OTP, and stays a later check. None of the three acts needs a web server — the bridge does. The operator has to decide one thing before the first command: **where the record lives**, because a record has to be pointed at something. **A name is optional.** A Galaxy may be labelled at any time and by anything with the authority to relabel, like every other named thing — and the label carries no authority, which is consistent with a Galaxy that holds no standing orders. ## The first act — `lowpassage galaxy init` Creates the installation and nothing else. No fleet, no ship, no mind. **It asks for** the location of the record. A label is optional here and can be given later. **It writes:** - `galaxy/ca/` — the CA's key and certificate. Everything that joins later is signed by this and nothing else. - `galaxy/store/` — the bootstrap set: the equipment for the bridge channel, which is the one channel that costs nothing beyond the interface. - `galaxy/library/` — the definition library, seeded with `starter` and `workshop`. - `galaxy/skills/` — the written procedures for the operations that recur: ingest, enroll, survey, muster. Nothing in the fleet can be done before there is a written way to do it, which is why these ship with the installation rather than being written when first needed. - `galaxy/minds/` — an empty mind-pool inventory. - `galaxy/consorts/` — an empty consort list. - a single-use join token. **How you know it worked:** the CA exists, a token was minted, and there is still nothing to look at. That is the correct outcome — this act creates the conditions for work rather than any work. ## The second act — `lowpassage node join` Brings this machine into the installation. **It asks for** the join token. **It writes:** - `nodes/<hostname>/` — a keypair and a certificate signed by the CA, with a subject matching the hostname. The hostname, never the address: a lease change must not invalidate a certificate. - the distribution configuration — cookie, seeds, EPMD port, TLS. Distribution comes up and connects to nothing, because there is nothing yet. - the identity: the roles this node may host. At first init, *may host the flagship* and *may host the bridge*. **How you know it worked:** `net_kernel` is up, the certificate verifies against the CA, the node reports itself, and the bridge answers — because on a galaxy of one node there is nowhere else for it to run. Nothing has a peer. **Why the bridge is part of this act rather than one of its own.** It is an OTP application, so it runs on a node that declares it may host it. With one node that is this machine; with several it is whichever node holds the declaration. Moving it is therefore starting it there and stopping it here — not a migration, with no record to replay and no address to change. What moves is the declaration, it lives in the Galaxy's record, and that is what gives the interface an address that outlives the move. ## The third act — `lowpassage flagship init` Creates a fleet. **It asks for** the flagship's name, and the minds for the first posts — one to think with at once, and one held for the first station that does work. **It writes:** - the fleet's identity, and one task force — empty of ships, existing anyway, because a commodore is the lowest commission that may muster one. - the flagship: prefix fixed at `flagship`, so the commodore is at `flagship:flag:commodore` whatever the ship is called. The name given here is a label. - the minimum command crew: the Commodore at `flagship:flag:commodore`, also holding the flagship's Captain commission; **Communications** at `flagship:flag:comms`; and the bosun and quartermaster as uncommissioned support stations at `flagship:bosun` and `flagship:quartermaster`. The **flag log** is the task force's record and begins here. - the mind bindings: the **command** mind bound to the Commodore's station, and the **work** mind allocated with capacity two and left unbound — binding is made at muster, and there is not yet a station doing work to bind it to. Both are mind host endpoints on this machine, LM Studio here, though any OpenAI-compatible host would serve. - the budget. **How you know it worked:** `flagship:flag:commodore` resolves, the watch bill is empty, and the log has begun — recording its own creation before anything else, so every later entry is attributable. ## First light The bridge comes up and a person can reach the fleet. At one node it shares the machine with everything else, and that is a reasonable first configuration rather than a compromise — most installations will start there. It becomes worth moving once a second node can run it, because a bridge that lives on the only node it watches cannot report that node's failure. What the person sees is a fleet with one ship, a watch bill with nothing on it, health readings with nothing to compute, and a field to type into. That field goes to Communications, and from there it is an ordinary message to an address — the Commodore's. Which is the point of the whole sequence: the first thing the galaxy can do is take an order. ## What is running, from the bottom up At the end of the third act the galaxy is one node deep and one ship wide. Nothing that should be there is missing and nothing above it exists. | Layer | What is there | |---|---| | **Node** | one: this machine, an ERTS, distribution up and connecting to nothing, certificate signed by the Galaxy's CA | | **Galaxy** | the CA, the record, the store with its bootstrap set, the definition library, the skills, a mind inventory of two, an empty consort list, and the bridge | | **Fleet** | one | | **Task force** | one, holding no ships of its own beyond the flagship, and no campaign | | **Ship** | one: the flagship, prefix `flagship`, labelled whatever the operator named it | | **Stations** | four crewed, and the ship's own machinery | | **Parts** | a crew for each station, and the parts each crew supervises | | **Equipment** | two fitted items, both listed below | ```mermaid flowchart TB F["Fleet"] --> TF["Task force"] --> S["flagship"] S --> C["flagship:flag:commodore"] S --> CM["flagship:flag:comms"] S --> B["flagship:bosun"] S --> Q["flagship:quartermaster"] ``` That is the whole of the Complement at this moment: four crewed stations under one ship, under one task force, under one fleet. The node underneath it, and the Galaxy's own holdings, are not drawn because nothing in the Complement depends on which machine is beneath — that is the point of a ship's segment being its own. ### The ship, and what is inside it The flagship is a supervision tree before it is anything else: `registry`, `ship_log`, `watch_bill`, `router`, `work_tree`, `mind_pool`, `analyst` and `health`, in that order of dependency, plus dynamic supervisors sitting empty. Those are the ship's machinery rather than stations — they decide nothing and touch nothing outside. Below them sit the stations, arranged two ways: - **Department `flag`** — the flag deck, holding the **Commodore** at `flagship:flag:commodore` and **Communications** at `flagship:flag:comms`. Communications is the **flag staff** at bootstrap, which is the flag deck minus the commodore and the log. - **At ship level** — the **bosun** at `flagship:bosun` and the **quartermaster** at `flagship:quartermaster`, uncommissioned support stations with fleet-wide reach. They serve the ship and the fleet rather than the flag deck, which is why they sit outside the `flag` segment. So four crewed stations at bootstrap: the commodore, one flag staff, and two support stations. Everything else in the tree is machinery. Each station is itself a small tree: a **crew** process that decides, an **equipment supervisor** with one child per fitted tool, and a **sampler** where the station observes at a frequency of its own. ### The stations and what they touch | Address | Role | Equipment | |---|---|---| | `flagship:flag:commodore` | decides what the work needs and allocates capacity | **none** | | `flagship:flag:comms` | owns the channel to the Admiral | the **bridge channel**: an effector that answers, a sensor that receives | | `flagship:bosun` | musters and retires stations | **none** | | `flagship:quartermaster` | provisions and retires model minds | a **mind host adapter** — LM Studio on this machine: an effector that loads and unloads, a sensor reporting free capacity | **Equipment is where a station touches something outside the ship.** Two of the four have it: Communications reaches a person and the quartermaster reaches a model host. The Commodore and the bosun have none, because everything they do is a decision or a message inside the fleet, and a message is not effector use. That asymmetry is the rule working rather than a gap — a station with nothing outside it to touch needs nothing fitted. Both fitted items come from the Galaxy's store, and both were in the bootstrap set deliberately: without the first there is no way for a person to reach the fleet, and without the second there is no cognition to borrow. **A channel belongs to one station, but it need not carry one person.** The flagship holds the channel to the Admiral because that is the route the flag deck needs; a station that must reach anybody else fits a channel of its own, private or shared. A watched chat channel, a group thread, a room several people use is still one channel with one owning station — and that station's job is to work out who spoke, then dispatch by a declared policy to the station responsible for that individual. That is what a department already is: no mind of its own, and a rule for who gets what. **How a reply finds its way home.** A reply that names what it answers — a quoted line, a reference, a thread — goes to the station that asked. One that names nothing goes to the station declared responsible for that person. Both are needed because they fail in different places: correlation is free and covers open questions; the declaration covers a reply that quotes nothing. Somebody with no declaration can still be answered to, but only by a correlated reply, which makes the declaration a fallback rather than a requirement. **Some stations are dedicated to one person, and some ask an open question.** An open question is addressed to nobody in particular and answerable by whoever knows, and it still has an owner — the station that asked. Its replies come home by correlation, and the person who answered is recorded because the log says who spoke, not because routing needed to know. **The mind host adapter is the same fitting whichever endpoint is behind it**: a base URL and a model alias, plus two questions that need answering per host — can it load and unload over an API, and can it require a token at all. An installation running `llama.cpp`, QVAC or Ollama instead of LM Studio changes the implementation and not the station. ### The minds Two model minds are in the Galaxy's inventory, allocated to the fleet, and reached over HTTP at LM Studio on this machine. The **command** mind is bound to the Commodore's station, because a flag officer with no cognition cannot turn an order into force design. The **work** mind is allocated and **unbound**: binding is made at muster, per station, and there is not yet a station doing work to bind it to. It waits for the first station whose work needs a judgment rather than a rule, and there is not one yet. ## What the disk looks like ``` galaxy/ ca/ the CA's key and certificate store/ bootstrap equipment: the bridge channel library/ starter, workshop skills/ ingest, enroll, survey, muster minds/ the inventory consorts/ empty nodes/<hostname>/ key, signed certificate, distribution config, identity ships/flagship/ log/ append-only, sequence numbers from 1 orders/ fleet.md, task-force.md, ship.md work/ empty: no campaign, no mission, no sortie departments/flag/stations/comms/ standing-orders.md rough-log.md ``` ## What is deliberately absent No second ship. No campaign, mission or sortie. No consorts. No enrolled devices. No second node. Nothing in reserve, nothing out of action, nothing decommissioned. And nothing decided yet above the ship: its copies of the fleet's and the task force's orders exist and are empty. ## Resuming rather than initialising Every act is idempotent, and re-running `galaxy init` against an existing installation does nothing rather than replacing it. That is not a nicety: it is how a galaxy comes back after its disk has been restored, since the record it reads is the one it wrote. A single node needs no second machine to be recoverable. It needs its own files, and a copy of them somewhere that outlives the disk — which is a backup question rather than a topology one, and true at any node count. ## Adding a node to a galaxy that already exists The first token comes from the forge. Every one after it comes from a command. That is not arbitrary. Joining is admission to the **installation** — the node becomes part of the Galaxy — but the Galaxy holds no authority of its own: no standing orders, no commission, nobody to decide. The decision to admit is therefore a command act, taken by whichever scope sits at the top of the ladder the fleet actually built. So bringing up a second core node is three things in order: 1. **A command authorises a token.** Single-use, short-lived, and the CA signs only what a token presents. 2. **The node joins as a new node.** Its own hostname, its own certificate from the same CA, its own identity declaring the roles it may host. It inherits nothing, because there is nothing to inherit — a node is hardware given a place in the installation, not a copy of another node. 3. **Ships move onto it by Maneuver.** Planned, quiet, addresses unchanged, because a ship's prefix is its own and is not derived from the node it happens to run on. **If the old core died rather than being replaced on purpose**, this is not the path: that is a declared loss and a resume, where the ship keeps the identity it already had. If it is being replaced deliberately, it is a Maneuver. The two look alike from the outside and are entirely different acts. Either way the Galaxy's own identity does not move. The CA, the record, the store and the definition library stay where they were, because none of them was ever on the node. ## Where this touches the ground **Settled since this was first written.** - **Who mints the first token.** `galaxy init`, because at that moment the Galaxy is being forged and there is nobody to ask. Every later token comes from a command, as above. - **Does a Galaxy take a label?** It does. The label is the installation's name and nothing more: it appears in the record and on the bridge, and it carries no authority. - **Does the bootstrap equipment prove itself?** The deployment's set is assumed to be basically tested when it ships. What is worth recording is that it is an *assumption*, so that when a channel fails on the first hail, the first question is whether it had ever been tried. - **A one-node galaxy hosting everything.** Not a compromise. It is a reasonable first configuration and probably the one most installations will run. It is also the one people expect to grow out of, which is a reason to keep the bridge movable rather than a reason to move it early. - **Who starts the bridge.** The node that declares it may host it, and on a one-node galaxy that is the only node there is — which is why the bridge belongs inside `node join` rather than to an act of its own. Because it is an OTP application, relocating it is start-elsewhere and stop-here rather than a migration, and the declaration in the Galaxy's record is what keeps the interface addressable across the move. Nothing on this list is open any more. What replaces it is the ordinary work of building M2 and finding out which of these statements the machine disagrees with. ## Reference - [[Low Passage]] — the specification; the bootstrap section is the authority for the three acts. - [[Low Passage Research]] — the toolchain as measured, the channel ranking, and what does not work on this host. - [[Low Passage Decisions]] — why the order is what it is, and what it replaced.