A network is a shape, so that it can be removed

novox/hq ADR 0029, and work breakdown 1.3. A module of several
containers had no way to let them reach each other by name: a container
declaration could join a network and nothing could create one.

An action was the obvious alternative and is refused on removal —
"an action has no footprint the host can undo", so a network made that
way outlives every module that is ever unassigned, and the mesh cannot
tell. A resource the mesh can create and never clean up is one it should
not create.

A name and nothing else. Not a driver, a subnet or a gateway: each is
something a module would have to know about the machine it lands on, and
a module naming a subnet collides with whatever else chose the same one.

It needs no new ordering rule. Resources apply in declaration order and
orphans are removed in reverse, so a network written before the
containers that join it is created first and removed last — after they
are gone. A runtime refusing to remove one still in use is reported
rather than swallowed, because that means something undeclared is
holding it.

The vocabulary guard fired on the change, as designed, and now names the
record instead of a number: nine shapes, with the argument beside the
count.

Creation reads back rather than trusting an exit status (ADR 0018): a
runtime that reports success and made nothing leaves every container
that joins it failing to start, one step from the cause.

internal/apply/vocabulary_test.go

@@ -9,6 +9,7 @@ import (
 	"encoding/base64"
 	"encoding/hex"
 	"encoding/json"
+	"fmt"
 	"net/http"
 	"net/http/httptest"
 	"os"
@@ -248,3 +249,71 @@ func TestAnArchiveMustBePinned(t *testing.T) {
 		t.Fatalf("unhelpful refusal: %v", err)
 	}
 }
+
+// Defends novox/hq ADR 0029: a network is a shape so that it can be removed.
+//
+// The whole argument for widening the vocabulary is lifecycle — an action could create one and
+// nothing could ever take it away — so removal is the assertion that matters, not creation.
+func TestANetworkIsCreatedAndThenRemovedWhenNoLongerDeclared(t *testing.T) {
+	var calls []string
+	there := map[string]bool{}
+	run := func(_ context.Context, name string, args ...string) (string, error) {
+		calls = append(calls, name+" "+strings.Join(args, " "))
+		if name != "docker" || len(args) < 2 || args[0] != "network" {
+			return "", nil // the runtime probe
+		}
+		switch args[1] {
+		case "inspect":
+			if !there[args[2]] {
+				return "", fmt.Errorf("no such network")
+			}
+		case "create":
+			there[args[2]] = true
+		case "rm":
+			delete(there, args[2])
+		}
+		return "", nil
+	}
+
+	d := declare(t, `{"id":"private","type":"network","name":"mail"}`)
+	_, state, err := Apply(context.Background(), archHost(t), d, store.State{},
+		store.OriginDeclared, run, nil, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !there["mail"] {
+		t.Fatal("the network was not created")
+	}
+
+	// The module is unassigned: the mesh now declares nothing.
+	empty := declare(t, `{"id":"unrelated","type":"directory","path":"`+t.TempDir()+`"}`)
+	if _, _, err := Apply(context.Background(), archHost(t), empty, state,
+		store.OriginDeclared, run, nil, nil); err != nil {
+		t.Fatal(err)
+	}
+	if there["mail"] {
+		t.Fatal("the network outlived the module that declared it, which is the entire reason " +
+			"this is a shape rather than an action")
+	}
+}
+
+// A network is created once and left alone when it is already there.
+func TestANetworkAlreadyThereIsNotRebuilt(t *testing.T) {
+	var created int
+	run := func(_ context.Context, name string, args ...string) (string, error) {
+		if name == "docker" && len(args) > 1 && args[0] == "network" && args[1] == "create" {
+			created++
+		}
+		return "", nil // inspect succeeds: it is already there
+	}
+
+	d := declare(t, `{"id":"private","type":"network","name":"mail"}`)
+	if _, _, err := Apply(context.Background(), archHost(t), d, store.State{},
+		store.OriginDeclared, run, nil, nil); err != nil {
+		t.Fatal(err)
+	}
+	if created != 0 {
+		t.Fatalf("a network that was already there was created %d time(s); the mesh owns the "+
+			"name and not the thing, so it does not tear one down and rebuild it", created)
+	}
+}