Scenario lifecycle: raise, exec, snapshot, restore, destroy

A declaration goes in and a disposable mesh comes out. Verified on a
workstation, not asserted: two machines raised and addressed in 14.6s,
snapshot 0.28s, restore-to-usable 11.6s, both families pinging with no
loss, and the workstation with no route into any of it.

The declaration layer implements the model in full — three positions a
machine can be in, keyed on forwardability; gateways carrying the address
the world sees them as; both address families; multi-homing; MTU;
inter-segment policy. It is validated hard because the failures it prevents
are silent: a private range on a public segment produces no error, the mesh
simply never forms. Public segments are refused unless they use RFC 5737 or
RFC 3849 space, and a range wider than the reserved block is refused too.
33 tests, all offline.

The runtime implements less than the model, and refuses the difference.
A scenario declaring gateways, published ports, policy, inbound deny or
place is rejected at raise with every gap named. Raising it would produce a
mesh that silently lacks what it declared, which is the fault this lab
exists to catch — 04-ISSUES/003, where a firewall key is declared in five
manifests and read by no code.

Three bugs found by review and by running it, all of one family:

The readiness check truthiness-tested incusOk's return. `exec … true`
succeeds with EMPTY output, so every machine reported unreachable while
incus exec on it worked perfectly. succeeds() now exists so the mistake is
not available, and network delete had the same bug — it counted zero
segments removed while removing them.

list() split instance from machine on the last dash, so a machine called
home-server absorbed half the instance id and destroy found nothing.
Resources are now found by the metadata they carry, never by name.

restore reported success in 0.79s while the machine's agent was still
starting, so the next command failed. Both raise and restore now wait for
usable and say how long that took — reporting the earlier number is
transport reported as effect, which is the fault the lab is being built to
find.

Two incus behaviours worth recording. Its CLI reads a YAML definition from
stdin when stdin is not a terminal, so a spawned command hangs until the
timeout kills it and arrives with empty stderr — a failure with no
explanation, on a command that works when typed. And it assigns a MAC at
runtime without recording it in device config, so MACs are derived and set
explicitly, which the guest needs anyway: it names interfaces by bus
position, and matching by name configures the wrong one on a multi-homed
machine.

No build step; Node strips the types. The lifecycle has no unit tests
because a fake hypervisor would assert that the fake behaves as expected,
which is the shape of test this project exists to stop shipping.

src/declaration/net.ts

@@ -0,0 +1,88 @@
+/**
+ * Address parsing, enough to answer two questions the validator asks: which family is
+ * this, and is it inside that range.
+ *
+ * Written rather than depended on because it is small, and because the one rule it
+ * exists to enforce — public segments use documentation ranges — is the difference
+ * between a lab that reproduces the internet and one that silently never forms a mesh.
+ */
+
+export type Family = "v4" | "v6";
+
+export interface Cidr {
+  family: Family;
+  /** Network address, as an integer. */
+  base: bigint;
+  prefix: number;
+  text: string;
+}
+
+const V4_BITS = 32n;
+const V6_BITS = 128n;
+
+export function familyOf(address: string): Family {
+  return address.includes(":") ? "v6" : "v4";
+}
+
+function parseV4(text: string): bigint {
+  const parts = text.split(".");
+  if (parts.length !== 4) throw new Error(`not an IPv4 address: ${text}`);
+  let value = 0n;
+  for (const part of parts) {
+    if (!/^\d{1,3}$/.test(part)) throw new Error(`not an IPv4 address: ${text}`);
+    const octet = Number(part);
+    if (octet > 255) throw new Error(`octet out of range in ${text}`);
+    value = (value << 8n) | BigInt(octet);
+  }
+  return value;
+}
+
+function parseV6(text: string): bigint {
+  // Reject the forms this does not implement rather than mis-parsing them. An embedded
+  // IPv4 suffix is legal and rare; getting it wrong silently would be worse than refusing.
+  if (text.includes(".")) throw new Error(`IPv4-in-IPv6 form is not supported: ${text}`);
+  const halves = text.split("::");
+  if (halves.length > 2) throw new Error(`not an IPv6 address: ${text}`);
+
+  const head = halves[0] ? halves[0].split(":").filter(Boolean) : [];
+  const tail = halves.length === 2 && halves[1] ? halves[1].split(":").filter(Boolean) : [];
+  const explicit = head.length + tail.length;
+  if (explicit > 8) throw new Error(`too many groups in ${text}`);
+  if (halves.length === 1 && explicit !== 8) throw new Error(`not an IPv6 address: ${text}`);
+
+  const groups = [...head, ...Array<string>(8 - explicit).fill("0"), ...tail];
+  let value = 0n;
+  for (const group of groups) {
+    if (!/^[0-9a-fA-F]{1,4}$/.test(group)) throw new Error(`not an IPv6 address: ${text}`);
+    value = (value << 16n) | BigInt(parseInt(group, 16));
+  }
+  return value;
+}
+
+export function parseAddress(text: string): { family: Family; value: bigint } {
+  const family = familyOf(text);
+  return { family, value: family === "v4" ? parseV4(text) : parseV6(text) };
+}
+
+export function parseCidr(text: string): Cidr {
+  const slash = text.lastIndexOf("/");
+  if (slash === -1) throw new Error(`not a CIDR range (no prefix length): ${text}`);
+  const addressText = text.slice(0, slash);
+  const prefix = Number(text.slice(slash + 1));
+  const { family, value } = parseAddress(addressText);
+  const bits = family === "v4" ? V4_BITS : V6_BITS;
+  if (!Number.isInteger(prefix) || prefix < 0 || BigInt(prefix) > bits) {
+    throw new Error(`prefix length out of range for ${family}: ${text}`);
+  }
+  const hostBits = bits - BigInt(prefix);
+  const base = (value >> hostBits) << hostBits;
+  return { family, base, prefix, text };
+}
+
+export function contains(range: Cidr, address: string): boolean {
+  const { family, value } = parseAddress(address);
+  if (family !== range.family) return false;
+  const bits = family === "v4" ? V4_BITS : V6_BITS;
+  const hostBits = bits - BigInt(range.prefix);
+  return ((value >> hostBits) << hostBits) === range.base;
+}