Step 1: an invariant that holds of any raised scenario

The address collision was found by eye. This is the mechanical form of it: no
two machines hold one address on one segment.

Pure over already-collected facts, so the logic is tested without a hypervisor
— including the cases that would make it useless if got wrong: the same address
on DIFFERENT segments is normal and must not be reported, and one machine
holding an address twice is not two machines.

Asserted against whatever the integration suite has standing, read from the
hypervisor rather than from the declaration. The declaration is what was
accepted, and it was accepted.

test/integration/underlay.test.ts

@@ -13,6 +13,7 @@ import { labIsUsable, destroyAll } from "./harness.ts";
 import { diagramFromLive } from "../../src/diagram/from-live.ts";
 import { diagramFromDeclaration } from "../../src/diagram/from-declaration.ts";
 import { toDrawio } from "../../src/diagram/drawio.ts";
+import { duplicateAddresses, describeConflicts } from "../../src/lifecycle/invariants.ts";
 
 const capability = await labIsUsable();
 const skip = capability.usable ? false : `lab not usable: ${capability.why}`;
@@ -121,6 +122,25 @@ test("ADR 0032 — the workstation has no route into the scenario", { skip, time
   assert.equal(stdout.trim(), "inside", "exec is the only way in, and it works");
 });
 
+test("no two machines hold one address on one segment", { skip }, async () => {
+  // True of ANY raised scenario, so it is asserted against whatever is standing rather than
+  // against something this test declares. Two gateways with the same public address became
+  // two containers both holding it, and the address resolved to whichever answered ARP last.
+  //
+  // Read from the hypervisor, never from the declaration — the declaration is what was
+  // accepted, and it was accepted.
+  const drawn = await diagramFromLive(instanceId);
+  const held = drawn.machines.flatMap((machine) =>
+    machine.attachments.flatMap((attachment) =>
+      attachment.addresses.map((address) => ({ machine: machine.name, segment: attachment.segment, address })),
+    ),
+  );
+  assert.ok(held.length > 0, "no addresses were read back at all");
+
+  const conflicts = duplicateAddresses(held);
+  assert.deepEqual(conflicts, [], `address conflict: ${describeConflicts(conflicts)}`);
+});
+
 // The diagram tests read the instance the file raised, so they run before the one that
 // tears it down. Ordering is load-bearing here: appended after the destroy test they read
 // an instance that no longer existed, and reported it as the diagram failing.

test/invariants.test.ts

@@ -0,0 +1,60 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { duplicateAddresses, describeConflicts } from "../src/lifecycle/invariants.ts";
+
+/**
+ * The fault this defends against, in the shape it actually occurred: two gateways declared
+ * with the same public address became two router containers, both holding it on one segment.
+ */
+
+test("two machines holding one address on one segment is a conflict", () => {
+  const conflicts = duplicateAddresses([
+    { machine: "gw-home", segment: "isp-home", address: "198.51.100.7/24" },
+    { machine: "gw-devices", segment: "isp-home", address: "198.51.100.7/24" },
+    { machine: "transit", segment: "isp-home", address: "198.51.100.254/24" },
+  ]);
+  assert.equal(conflicts.length, 1);
+  assert.equal(conflicts[0]?.address, "198.51.100.7");
+  assert.deepEqual(conflicts[0]?.machines, ["gw-devices", "gw-home"]);
+  assert.match(describeConflicts(conflicts), /198\.51\.100\.7 is held by gw-devices and gw-home/);
+});
+
+test("the same address on different segments is NOT a conflict", () => {
+  // Every private network has its own `.1`. Reporting that would make the check useless.
+  assert.deepEqual(
+    duplicateAddresses([
+      { machine: "gw-a", segment: "home", address: "192.168.1.1/24" },
+      { machine: "gw-b", segment: "cafe", address: "192.168.1.1/24" },
+    ]),
+    [],
+  );
+});
+
+test("one machine holding an address twice is not two machines", () => {
+  // A machine multi-homed onto the same segment, or an address read back from two places.
+  assert.deepEqual(
+    duplicateAddresses([
+      { machine: "gw", segment: "isp", address: "198.51.100.7/24" },
+      { machine: "gw", segment: "isp", address: "198.51.100.7" },
+    ]),
+    [],
+  );
+});
+
+test("the prefix length is not part of the address", () => {
+  // The same address declared /24 in one place and /16 in another is still one address.
+  const conflicts = duplicateAddresses([
+    { machine: "a", segment: "isp", address: "198.51.100.7/24" },
+    { machine: "b", segment: "isp", address: "198.51.100.7/16" },
+  ]);
+  assert.equal(conflicts.length, 1);
+});
+
+test("both families are checked", () => {
+  const conflicts = duplicateAddresses([
+    { machine: "a", segment: "isp", address: "2001:db8:b::7/48" },
+    { machine: "b", segment: "isp", address: "2001:db8:b::7/48" },
+  ]);
+  assert.equal(conflicts.length, 1);
+  assert.equal(conflicts[0]?.address, "2001:db8:b::7");
+});