Describe an installation in a file, and converge to it

One file describes the whole installation: which machine runs what, under
which names. Each machine acts on its own part of it and prints the command
to run on the others, which nobody but their operator runs. Emit, never
execute -- no agent, no console-held credential, no machine reaching
another.

  inbuxa plan  -f topology.json     what would change here; changes nothing
  inbuxa apply -f topology.json     make this machine match it
  inbuxa export                     the file, from what is already here

plan diffs the file against what is installed rather than against what
happens to be running: a container stopped by hand is still installed, and
offering to install it again would be a lie about what is about to happen.
The state that makes that possible -- intent, which the machine itself
cannot tell you -- is /etc/inbuxa/install.json.

Front ends across machines, not a clustered mail server. Two machines each
running one is refused, and the refusal says why: a second node needs a
shared store and cluster configuration, which this does not set up. Two of
the same component on one machine is refused too -- two webmails need two
ports and two names, and the file says neither.

The shrink is the half worth proving, and it found the bug that mattered:
apply ran first boot every time, so the second one asked a configured server
for bootstrap credentials it had stopped accepting, and adding or removing a
front end could not work at all. An installed machine now converges instead:
the deployment is rewritten from the shapes asked for, --remove-orphans
takes away what the file no longer lists, data volumes are left alone, and
the secrets generated the first time are kept rather than rolled.

Two more found the same way:

- Certificates were turned on even where nothing holds port 80. On a machine
  with no proxy the order can only fail, and it stopped the install over it.
  It now says whose job they are instead.
- A converge that restarts the server reported "Done" while it was still
  coming back. It waits.

Twenty-eight checks, on Debian 13 and Fedora 43: install from a file, plan
the same file and be told there is nothing to do, remove the webmail and
watch it go while the mail stays, put it back.

internal/state/state.go

@@ -0,0 +1,76 @@
+// SPDX-FileCopyrightText: 2026 Coffey Labs
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+// Package state is what this machine remembers about what was installed on
+// it, so a second run converges instead of building a second one.
+//
+// It is deliberately small, and deliberately not the truth: the truth is the
+// machine, and a plan is built by reading both. What this adds is intent --
+// which components this installer put here, in which shape, from which
+// topology -- which the machine itself cannot tell you. A container that was
+// stopped by hand is still ours; a container we never installed is not.
+package state
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"time"
+)
+
+// Path is where it lives. /etc, not the deployment directory: it survives
+// the deployment directory being moved or rebuilt, and an operator looking
+// for "what did this thing do to my machine" looks in /etc.
+const Path = "/etc/inbuxa/install.json"
+
+// State is the file.
+type State struct {
+	Version   int               `json:"version"`
+	Machine   string            `json:"machine"`             // its name in the topology
+	Dir       string            `json:"dir"`                 // the deployment directory
+	Runtime   string            `json:"runtime,omitempty"`   // docker or podman
+	Domain    string            `json:"domain,omitempty"`    //
+	Shapes    map[string]string `json:"shapes"`              // component -> container|host
+	Topology  string            `json:"topology,omitempty"`  // the file this came from, if any
+	Updated   time.Time         `json:"updated"`             //
+	Installer string            `json:"installer,omitempty"` // the version that wrote this
+}
+
+const Version = 1
+
+// Load reads the state, returning an empty one when there is none. A machine
+// with nothing installed is not an error; it is the ordinary first case.
+func Load() (*State, error) {
+	b, err := os.ReadFile(Path)
+	if os.IsNotExist(err) {
+		return &State{Version: Version, Shapes: map[string]string{}}, nil
+	}
+	if err != nil {
+		return nil, err
+	}
+	var s State
+	if err := json.Unmarshal(b, &s); err != nil {
+		return nil, err
+	}
+	if s.Shapes == nil {
+		s.Shapes = map[string]string{}
+	}
+	return &s, nil
+}
+
+// Save writes it, creating /etc/inbuxa if it is not there.
+func (s *State) Save() error {
+	s.Version = Version
+	s.Updated = time.Now().UTC().Truncate(time.Second)
+	if err := os.MkdirAll(filepath.Dir(Path), 0o755); err != nil {
+		return err
+	}
+	b, err := json.MarshalIndent(s, "", "  ")
+	if err != nil {
+		return err
+	}
+	return os.WriteFile(Path, append(b, '\n'), 0o644)
+}
+
+// Installed is whether anything is recorded here at all.
+func (s *State) Installed() bool { return len(s.Shapes) > 0 }