@forgezero/agent 0.1.78 → 0.1.80

package/dist/fz-agent.js

@@ -5114,16 +5114,38 @@ var runSoftwareCommand = async (argv, env = {}) => {
   return { exitCode, output: `${stdout}${stderr}` };
 };
 var run = runSoftwareCommand;
+var softwareDownloadCommand = (url, destination, maximumBytes) => {
+  const source = new URL(url);
+  if (source.protocol !== "https:" || source.username || source.password)
+    throw new Error("software download must use credential-free HTTPS");
+  if (!Number.isSafeInteger(maximumBytes) || maximumBytes < 1)
+    throw new Error("software download size bound is invalid");
+  return [
+    "/usr/bin/curl",
+    "--fail",
+    "--location",
+    "--silent",
+    "--show-error",
+    "--proto",
+    "=https",
+    "--tlsv1.2",
+    "--max-time",
+    "1800",
+    "--max-filesize",
+    String(maximumBytes),
+    "--output",
+    destination,
+    source.href
+  ];
+};
 var download = async (url, destination, sha2562, maximumBytes = 512 * 1024 * 1024) => {
-  const response = await fetch(url, { redirect: "follow", signal: AbortSignal.timeout(30 * 60000) });
-  if (!response.ok)
-    throw new Error(`download failed with HTTP ${response.status}`);
-  const declared = Number(response.headers.get("content-length") ?? 0);
-  if (declared > maximumBytes)
-    throw new Error("download exceeds reviewed size bound");
   if (existsSync2(destination))
     throw new Error("download destination already exists");
-  await Bun.write(destination, response);
+  const received = await run(softwareDownloadCommand(url, destination, maximumBytes));
+  if (received.exitCode !== 0) {
+    rmSync(destination, { force: true });
+    throw new Error(`software download failed (${received.exitCode}): ${received.output.trim()}`);
+  }
   chmodSync2(destination, 384);
   if (statSync(destination).size > maximumBytes) {
     rmSync(destination, { force: true });
@@ -6362,7 +6384,7 @@ function reference(value, where) {
   const row2 = object(value, where);
   exact3(row2, ["$ref"], where);
   const coordinate = boundedString(row2.$ref, `${where}.$ref`, 256);
-  if (!/^(inputs\.[a-z][A-Za-z0-9-]{0,62}|steps\.[a-z][A-Za-z0-9-]{0,62}\.(status|outputs\.[a-z][A-Za-z0-9-]{0,62})|components\.[a-z][A-Za-z0-9-]{0,62}\.[a-z][A-Za-z0-9-]{0,62}|targets\.[a-z][A-Za-z0-9-]{0,62}\.[a-z][A-Za-z0-9-]{0,62}|deployment\.[a-z][A-Za-z0-9-]{0,62}|execution\.(targetName|slot|releaseExecutor|runtime|cpuCores|memoryMiB|storageGiB))$/.test(coordinate)) {
+  if (!/^(inputs\.[a-z][A-Za-z0-9-]{0,62}|steps\.[a-z][A-Za-z0-9-]{0,62}\.(status|outputs\.[a-z][A-Za-z0-9-]{0,62})|components\.[a-z][A-Za-z0-9-]{0,62}\.[a-z][A-Za-z0-9-]{0,62}|targets\.[a-z][A-Za-z0-9-]{0,62}\.[a-z][A-Za-z0-9-]{0,62}|deployment\.[a-z][A-Za-z0-9-]{0,62}|execution\.(targetName|slot|releaseExecutor|runtime|cpuCores|memoryMiB|storageGiB|site|topologyRole|topologyTransport|localRelayAddress))$/.test(coordinate)) {
     fail(where, "contains an unsupported reference.");
   }
   return { $ref: coordinate };
@@ -6794,6 +6816,12 @@ function validateStep(value, where, targets, context) {
     if (!targets.has(String(scope.target)))
       fail(`${where}.scope.target`, "must name an existing target.");
     integer(scope.size, `${where}.scope.size`, 1, 32);
+  } else if (scope.kind === "topology-role") {
+    exact3(scope, ["kind", "target", "role"], `${where}.scope`);
+    if (!targets.has(String(scope.target)))
+      fail(`${where}.scope.target`, "must name an existing target.");
+    if (!["relay", "standby", "member"].includes(String(scope.role)))
+      fail(`${where}.scope.role`, "is unsupported.");
   } else
     fail(`${where}.scope.kind`, "is unsupported.");
   if (row2.timeoutMs !== undefined)
@@ -6948,7 +6976,7 @@ function compileDeployment(sourceValue) {
   const targetDefinitions = new Map;
   for (const [targetName, value] of targetEntries) {
     const target = object(value, `deployment.spec.targets.${targetName}`);
-    exact3(target, ["kind", "selector", "cardinality", "allocation", "provisioning", "connectivity", "placement"], `deployment.spec.targets.${targetName}`);
+    exact3(target, ["kind", "selector", "cardinality", "allocation", "provisioning", "connectivity", "topology", "placement"], `deployment.spec.targets.${targetName}`);
     if (target.kind !== "compute")
       fail(`deployment.spec.targets.${targetName}.kind`, "must be compute.");
     const selector = object(target.selector, `deployment.spec.targets.${targetName}.selector`);
@@ -7070,6 +7098,45 @@ function compileDeployment(sourceValue) {
         }
       }
     }
+    if (target.topology !== undefined) {
+      const topology = object(target.topology, `deployment.spec.targets.${targetName}.topology`);
+      exact3(topology, ["groupBy", "relays", "crossMetal"], `deployment.spec.targets.${targetName}.topology`);
+      if (topology.groupBy !== "metal")
+        fail(`deployment.spec.targets.${targetName}.topology.groupBy`, "must be metal.");
+      const relays = object(topology.relays, `deployment.spec.targets.${targetName}.topology.relays`);
+      exact3(relays, ["activePerMetal", "standbyPerMetal", "healthPort", "routedTcpPorts"], `deployment.spec.targets.${targetName}.topology.relays`);
+      if (relays.activePerMetal !== 1 || ![0, 1].includes(Number(relays.standbyPerMetal)))
+        fail(`deployment.spec.targets.${targetName}.topology.relays`, "requires one active relay and zero or one standby per metal.");
+      integer(relays.healthPort, `deployment.spec.targets.${targetName}.topology.relays.healthPort`, 1, 65535);
+      if (!Array.isArray(relays.routedTcpPorts) || relays.routedTcpPorts.length < 1 || relays.routedTcpPorts.length > 64 || new Set(relays.routedTcpPorts).size !== relays.routedTcpPorts.length) {
+        fail(`deployment.spec.targets.${targetName}.topology.relays.routedTcpPorts`, "must contain 1 to 64 unique ports.");
+      }
+      for (const [index, port] of relays.routedTcpPorts.entries()) {
+        integer(port, `deployment.spec.targets.${targetName}.topology.relays.routedTcpPorts.${index}`, 1, 65535);
+      }
+      if (!relays.routedTcpPorts.includes(relays.healthPort)) {
+        fail(`deployment.spec.targets.${targetName}.topology.relays`, "routedTcpPorts must include healthPort.");
+      }
+      const crossMetal = object(topology.crossMetal, `deployment.spec.targets.${targetName}.topology.crossMetal`);
+      if (crossMetal.mode === "private-lan")
+        exact3(crossMetal, ["mode"], `deployment.spec.targets.${targetName}.topology.crossMetal`);
+      else if (crossMetal.mode === "cloudflare-warp" || crossMetal.mode === "auto") {
+        exact3(crossMetal, crossMetal.mode === "auto" ? ["mode", "directPrivateMaximumMetals", "credential", "network"] : ["mode", "credential", "network"], `deployment.spec.targets.${targetName}.topology.crossMetal`);
+        if (crossMetal.mode === "auto" && crossMetal.directPrivateMaximumMetals !== 2)
+          fail(`deployment.spec.targets.${targetName}.topology.crossMetal.directPrivateMaximumMetals`, "must be 2.");
+        if (!credentials[named(crossMetal.credential, `deployment.spec.targets.${targetName}.topology.crossMetal.credential`)])
+          fail(`deployment.spec.targets.${targetName}.topology.crossMetal.credential`, "must name a declared credential.");
+        if (typeof crossMetal.network === "string")
+          named(crossMetal.network, `deployment.spec.targets.${targetName}.topology.crossMetal.network`);
+        else
+          reference(crossMetal.network, `deployment.spec.targets.${targetName}.topology.crossMetal.network`);
+      } else
+        fail(`deployment.spec.targets.${targetName}.topology.crossMetal.mode`, "is unsupported.");
+      if (allocation.sharing !== "exclusive")
+        fail(`deployment.spec.targets.${targetName}.allocation.sharing`, "must be exclusive for a per-metal relay topology.");
+      if (minimum < 1 + Number(relays.standbyPerMetal))
+        fail(`deployment.spec.targets.${targetName}.cardinality.minimum`, "must allow the declared relay and standby.");
+    }
     if (target.placement !== undefined)
       jsonValue(target.placement, `deployment.spec.targets.${targetName}.placement`);
     targetDefinitions.set(targetName, target);
@@ -7093,6 +7160,9 @@ function compileDeployment(sourceValue) {
     if (target.connectivity?.private?.mode === "cloudflare-warp" && ![...requirementDefinitions.values()].some(({ capability }) => capability === "network.private")) {
       fail(`deployment.spec.targets.${targetName}.connectivity.private`, "requires one network.private provider requirement.");
     }
+    if (target.topology && target.topology.crossMetal.mode !== "private-lan" && ![...requirementDefinitions.values()].some(({ capability }) => capability === "network.private")) {
+      fail(`deployment.spec.targets.${targetName}.topology.crossMetal`, "requires one network.private provider requirement.");
+    }
   }
   const components = object(spec.components, "deployment.spec.components");
   const componentEntries = Object.entries(components);
@@ -7350,6 +7420,19 @@ function resolveDeploymentTargets(plan, supplied = {}) {
         } : { mode: "disabled" } } : {}
       };
     }
+    let topology;
+    if (target.topology) {
+      const crossMetal = target.topology.crossMetal;
+      topology = {
+        groupBy: "metal",
+        relays: { ...target.topology.relays },
+        crossMetal: crossMetal.mode === "private-lan" ? { mode: "private-lan" } : {
+          ...crossMetal,
+          credential: credentialSource(crossMetal.credential, `target ${name} topology WARP credential`),
+          network: stringCoordinate(crossMetal.network, `target ${name} topology WARP network`)
+        }
+      };
+    }
     return {
       name,
       profiles: [...target.selector.profiles],
@@ -7368,7 +7451,8 @@ function resolveDeploymentTargets(plan, supplied = {}) {
         }
       },
       ...target.provisioning ? { provisioning: { ...target.provisioning } } : {},
-      ...connectivity ? { connectivity } : {}
+      ...connectivity ? { connectivity } : {},
+      ...topology ? { topology } : {}
     };
   });
 }
@@ -8074,12 +8158,19 @@ function createDeploymentManager(options) {
         if (!selected || mismatches.length > 0) {
           throw new DeploymentError("PIPELINE_FAILED", `the control-plane target assignment does not match this exact deployment plan (${mismatches.join(", ")})`);
         }
-        const expectedPrivate = selected.connectivity?.private;
+        const assignedTopology = assigned.topology;
+        const selectedTopology = selected.topology;
+        const topologyMatches = selectedTopology ? Boolean(assignedTopology && /^[A-Za-z0-9.-]{1,253}$/.test(assignedTopology.site) && /^[A-Za-z0-9.-]{1,253}$/.test(assignedTopology.nodeIdentity) && /^[A-Za-z0-9._:-]{1,256}$/.test(assignedTopology.localRelayReference) && /^sha256:[a-f0-9]{64}$/.test(assignedTopology.generation) && /^(?:\d{1,3}\.){3}0\/24$/.test(assignedTopology.siteCidr) && assignedTopology.localRelayAddress.length <= 64 && assignedTopology.localPeerAddresses.length <= 1023 && assignedTopology.localPeerAddresses.every((address) => typeof address === "string" && address.length <= 64) && assignedTopology.localPeerIdentities.length === assignedTopology.localPeerAddresses.length && assignedTopology.localPeerIdentities.every((identity) => /^[A-Za-z0-9.-]{1,253}$/.test(identity)) && assignedTopology.remoteRelayAddresses.length <= 1023 && assignedTopology.remoteRelayAddresses.every((address) => typeof address === "string" && address.length <= 64) && assignedTopology.remoteRelayIdentities.length === assignedTopology.remoteRelayAddresses.length && assignedTopology.remoteRelayIdentities.every((identity) => /^[A-Za-z0-9.-]{1,253}$/.test(identity)) && assignedTopology.memberIdentities.length >= 1 && assignedTopology.memberIdentities.length <= 1024 && new Set(assignedTopology.memberIdentities).size === assignedTopology.memberIdentities.length && assignedTopology.memberIdentities.includes(assignedTopology.nodeIdentity) && assignedTopology.memberIdentities.every((identity) => /^[A-Za-z0-9.-]{1,253}$/.test(identity)) && (assignedTopology.role === "member" ? assignedTopology.remoteRelayAddresses.length === 0 : assignedTopology.remoteSiteCidrs.length === assignedTopology.remoteRelayAddresses.length) && assignedTopology.remoteSiteCidrs.every((cidr) => typeof cidr === "string" && /^(?:\d{1,3}\.){3}0\/24$/.test(cidr)) && Number.isSafeInteger(assignedTopology.healthPort) && assignedTopology.healthPort >= 1 && assignedTopology.healthPort <= 65535 && assignedTopology.routedTcpPorts.length >= 1 && assignedTopology.routedTcpPorts.length <= 64 && new Set(assignedTopology.routedTcpPorts).size === assignedTopology.routedTcpPorts.length && assignedTopology.routedTcpPorts.includes(assignedTopology.healthPort) && assignedTopology.routedTcpPorts.every((port) => Number.isSafeInteger(port) && port >= 1 && port <= 65535) && (assignedTopology.role !== "member" || assignedTopology.transport === "private-lan" && assignedTopology.warpRequired === false && assignedTopology.remoteRelayAddresses.length === 0 && assignedTopology.localPeerAddresses.length === 1) && (assignedTopology.warpRequired ? assignedTopology.role !== "member" && assignedTopology.transport === "cloudflare-warp" && selectedTopology.crossMetal.mode !== "private-lan" : assignedTopology.transport === "private-lan")) : assignedTopology === undefined;
+        const expectedPrivate = selectedTopology ? assignedTopology?.warpRequired ? selectedTopology.crossMetal.mode === "private-lan" ? undefined : {
+          mode: "cloudflare-warp",
+          credential: selectedTopology.crossMetal.credential,
+          network: selectedTopology.crossMetal.network
+        } : { mode: "private-lan" } : selected.connectivity?.private;
         const expectedPublic = selected.connectivity?.public;
         const assignedPrivate = assigned.connectivity?.private;
         const assignedPublic = assigned.connectivity?.public;
         const publicMatches = expectedPublic?.mode === "cloudflare-tunnel" ? assignedPublic?.mode === "cloudflare-tunnel" && assignedPublic.credential === expectedPublic.credential && assignedPublic.service.protocol === expectedPublic.service.protocol && assignedPublic.service.port === expectedPublic.service.port && assignedPublic.hostname === (expectedPublic.hostname.mode === "static" ? `${expectedPublic.hostname.label}.${expectedPublic.zone}` : `${expectedPublic.hostname.prefix}${expectedPublic.hostname.startAt + assigned.slot}.${expectedPublic.zone}`) : expectedPublic?.mode === "disabled" ? assignedPublic?.mode === "disabled" : assignedPublic === undefined;
-        if (JSON.stringify(assignedPrivate) !== JSON.stringify(expectedPrivate) || !publicMatches) {
+        if (!topologyMatches || JSON.stringify(assignedPrivate) !== JSON.stringify(expectedPrivate) || !publicMatches) {
           throw new DeploymentError("PIPELINE_FAILED", "the control-plane connectivity assignment does not match this target slot");
         }
         targetNames = new Set([assigned.targetName]);
@@ -8096,7 +8187,24 @@ function createDeploymentManager(options) {
           FZ_TARGET_CPU_CORES: String(assigned.resources.cpuCores),
           FZ_TARGET_MEMORY_MIB: String(assigned.resources.memoryMiB),
           FZ_TARGET_STORAGE_GIB: String(assigned.resources.storageGiB),
-          FZ_TARGET_EXECUTION: assigned.execution
+          FZ_TARGET_EXECUTION: assigned.execution,
+          ...assigned.topology ? {
+            FZ_TOPOLOGY_SITE: assigned.topology.site,
+            FZ_TOPOLOGY_NODE_IDENTITY: assigned.topology.nodeIdentity,
+            FZ_TOPOLOGY_SITE_CIDR: assigned.topology.siteCidr,
+            FZ_TOPOLOGY_ROLE: assigned.topology.role,
+            FZ_TOPOLOGY_TRANSPORT: assigned.topology.transport,
+            FZ_TOPOLOGY_LOCAL_RELAY: assigned.topology.localRelayAddress,
+            FZ_TOPOLOGY_LOCAL_PEERS: assigned.topology.localPeerAddresses.join(","),
+            FZ_TOPOLOGY_LOCAL_PEER_IDENTITIES: assigned.topology.localPeerIdentities.join(","),
+            FZ_TOPOLOGY_REMOTE_RELAYS: assigned.topology.remoteRelayAddresses.join(","),
+            FZ_TOPOLOGY_REMOTE_RELAY_IDENTITIES: assigned.topology.remoteRelayIdentities.join(","),
+            FZ_TOPOLOGY_REMOTE_CIDRS: assigned.topology.remoteSiteCidrs.join(","),
+            FZ_TOPOLOGY_MEMBERS: assigned.topology.memberIdentities.join(","),
+            FZ_TOPOLOGY_HEALTH_PORT: String(assigned.topology.healthPort),
+            FZ_TOPOLOGY_ROUTED_TCP_PORTS: assigned.topology.routedTcpPorts.join(","),
+            FZ_TOPOLOGY_GENERATION: assigned.topology.generation
+          } : {}
         });
       for (const targetName of targetNames) {
         const capacity2 = resolvedTargets.find(({ name }) => name === targetName)?.allocation.resources;
@@ -8152,11 +8260,15 @@ function createDeploymentManager(options) {
           return { changed: true };
         },
         "forgezero.network/ensure@1": async ({ resolved }) => {
+          if (!assigned && bootstrapBundle && typeof resolved.target === "string" && targetNames.has(resolved.target)) {
+            return { changed: false, evidence: { target: resolved.target, authority: "attended-bootstrap" } };
+          }
           if (!assigned || typeof resolved.target !== "string" || resolved.target !== assigned.targetName) {
             throw new DeploymentActionError("refused", "network.ensure must target this exact control-plane assignment");
           }
-          if (!assigned.connectivity)
-            return { changed: false, evidence: { target: assigned.targetName } };
+          if (!assigned.connectivity) {
+            return { changed: false, evidence: { target: assigned.targetName, authority: "none" } };
+          }
           if (!options.ensureSoftware || !options.applyConnectivity) {
             throw new DeploymentActionError("provider-unavailable", "the supervised connectivity helper is unavailable");
           }
@@ -8165,12 +8277,31 @@ function createDeploymentManager(options) {
             requirements.push({ id: "cloudflared", version: "latest" });
           if (assigned.connectivity.private?.mode === "cloudflare-warp")
             requirements.push({ id: "cloudflare-warp", version: "latest" });
+          if (assigned.topology)
+            requirements.push({ id: "ufw", version: "latest" });
           if (requirements.length > 0)
             await options.ensureSoftware(requirements);
           const evidence = await options.applyConnectivity({
             key: `${options.key}:${assigned.targetName}:${assigned.slot}`,
             intent: assigned.connectivity,
-            capabilities: request.connectivityCapabilities ?? {}
+            capabilities: request.connectivityCapabilities ?? {},
+            ...assigned.topology ? { topology: {
+              site: assigned.topology.site,
+              nodeIdentity: assigned.topology.nodeIdentity,
+              siteCidr: assigned.topology.siteCidr,
+              role: assigned.topology.role,
+              transport: assigned.topology.transport,
+              localRelayAddress: assigned.topology.localRelayAddress,
+              localPeerAddresses: assigned.topology.localPeerAddresses,
+              localPeerIdentities: assigned.topology.localPeerIdentities,
+              remoteRelayAddresses: assigned.topology.remoteRelayAddresses,
+              remoteRelayIdentities: assigned.topology.remoteRelayIdentities,
+              remoteSiteCidrs: assigned.topology.remoteSiteCidrs,
+              memberIdentities: assigned.topology.memberIdentities,
+              healthPort: assigned.topology.healthPort,
+              routedTcpPorts: assigned.topology.routedTcpPorts,
+              generation: assigned.topology.generation
+            } } : {}
           });
           return { changed: true, evidence: structuredClone(evidence) };
         },
@@ -8279,7 +8410,13 @@ function createDeploymentManager(options) {
           runtime: assigned.execution,
           cpuCores: assigned.resources.cpuCores,
           memoryMiB: assigned.resources.memoryMiB,
-          storageGiB: assigned.resources.storageGiB
+          storageGiB: assigned.resources.storageGiB,
+          ...assigned.topology ? {
+            site: assigned.topology.site,
+            topologyRole: assigned.topology.role,
+            topologyTransport: assigned.topology.transport,
+            localRelayAddress: assigned.topology.localRelayAddress
+          } : {}
         } : {
           targetName: matchingTargetNames[0],
           slot: 0,
@@ -8289,7 +8426,7 @@ function createDeploymentManager(options) {
           memoryMiB: resolvedTargets[0].allocation.resources.memoryMiB,
           storageGiB: resolvedTargets[0].allocation.resources.storageGiB
         },
-        shouldRun: (step2) => step2.scope.kind === "release-executor" || step2.scope.kind === "elected-one" ? request.releaseExecutor === true : targetNames.has(step2.scope.target)
+        shouldRun: (step2) => step2.scope.kind === "release-executor" || step2.scope.kind === "elected-one" ? request.releaseExecutor === true : step2.scope.kind === "topology-role" ? targetNames.has(step2.scope.target) && assigned?.topology?.role === step2.scope.role : targetNames.has(step2.scope.target)
       });
       const phase = {
         pipeline: `${plan.name}:deploy`,
@@ -8729,7 +8866,8 @@ async function pullDeploymentOnce(options) {
       labels: { ...target.labels },
       allocation: { ...target.allocation, resources: { ...target.allocation.resources } },
       ...target.provisioning ? { provisioning: { ...target.provisioning } } : {},
-      ...target.connectivity ? { connectivity: structuredClone(target.connectivity) } : {}
+      ...target.connectivity ? { connectivity: structuredClone(target.connectivity) } : {},
+      ...target.topology ? { topology: structuredClone(target.topology) } : {}
     })) } : {},
     ...result.capacity ? { capacity: {
       recommendedConcurrency: result.capacity.recommendedConcurrency,
@@ -9193,7 +9331,7 @@ async function writeAndCloseProcessInput(input, value) {
 }
 
 // src/version.ts
-var VERSION2 = "0.1.78";
+var VERSION2 = "0.1.80";
 
 // src/ssh-bootstrap.ts
 class SshBootstrapError extends Error {
@@ -12838,6 +12976,7 @@ async function activateContainer(requestValue, host = defaultHost2) {
 // src/deployment-connectivity.ts
 import { createHash as createHash11 } from "crypto";
 import { mkdirSync as mkdirSync12, renameSync as renameSync10, writeFileSync as writeFileSync13 } from "fs";
+import { createConnection as createConnection2 } from "net";
 import { dirname as dirname9 } from "path";
 var TOKEN2 = /^[A-Za-z0-9._-]{40,16384}$/;
 var UUID = /^[a-f0-9]{8}-[a-f0-9]{4}-[1-5][a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/i;
@@ -12882,6 +13021,21 @@ var defaultHost3 = {
     const [stdout, stderr, exitCode] = await Promise.all([new Response(child.stdout).text(), new Response(child.stderr).text(), child.exited]);
     return { exitCode, output: `${stdout}${stderr}` };
   },
+  probe: (address, port, timeoutMs) => new Promise((resolve6) => {
+    const socket = createConnection2({ host: address, port });
+    let settled = false;
+    const finish = (value) => {
+      if (settled)
+        return;
+      settled = true;
+      socket.destroy();
+      resolve6(value);
+    };
+    socket.setTimeout(timeoutMs);
+    socket.once("connect", () => finish(true));
+    socket.once("timeout", () => finish(false));
+    socket.once("error", () => finish(false));
+  }),
   sleep: (ms) => Bun.sleep(ms)
 };
 function validate2(request) {
@@ -12896,7 +13050,7 @@ function validate2(request) {
   } else if (request.capabilities.public)
     throw new Error("unexpected public deployment capability");
   if (privateIntent?.mode === "cloudflare-warp") {
-    if (!NAME3.test(privateIntent.credential) || privateIntent.network.length < 1 || privateIntent.network.length > 128 || !request.capabilities.private || !UUID.test(request.capabilities.private.connectorId) || !TOKEN2.test(request.capabilities.private.connectorToken)) {
+    if (!NAME3.test(privateIntent.credential) || privateIntent.network.length < 1 || privateIntent.network.length > 128 || !request.capabilities.private || !UUID.test(request.capabilities.private.connectorId) || !UUID.test(request.capabilities.private.siteRouteId) || !TOKEN2.test(request.capabilities.private.connectorToken)) {
       throw new Error("private deployment connectivity is malformed");
     }
   } else if (request.capabilities.private)
@@ -12906,6 +13060,22 @@ async function applyDeploymentConnectivity(request, host = defaultHost3) {
   validate2(request);
   const id2 = idFor3(request.key);
   const evidence = { key: request.key };
+  const topology = request.topology;
+  if (topology) {
+    const values = [topology.localRelayAddress, ...topology.localPeerAddresses, ...topology.remoteRelayAddresses];
+    const identities = [
+      topology.nodeIdentity,
+      ...topology.localPeerIdentities,
+      ...topology.remoteRelayIdentities,
+      ...topology.memberIdentities
+    ];
+    if (!/^[A-Za-z0-9.-]{1,253}$/.test(topology.site) || !/^(?:\d{1,3}\.){3}0\/24$/.test(topology.siteCidr) || values.some((value) => !/^(?:\d{1,3}\.){3}\d{1,3}$/.test(value)) || identities.some((value) => !/^[A-Za-z0-9.-]{1,253}$/.test(value)) || topology.localPeerIdentities.length !== topology.localPeerAddresses.length || topology.remoteRelayIdentities.length !== topology.remoteRelayAddresses.length || topology.memberIdentities.length < 1 || topology.memberIdentities.length > 1024 || new Set(topology.memberIdentities).size !== topology.memberIdentities.length || !topology.memberIdentities.includes(topology.nodeIdentity) || !/^sha256:[a-f0-9]{64}$/.test(topology.generation) || (topology.role === "member" ? topology.remoteRelayAddresses.length !== 0 : topology.remoteSiteCidrs.length !== topology.remoteRelayAddresses.length) || topology.remoteSiteCidrs.some((value) => !/^(?:\d{1,3}\.){3}0\/24$/.test(value)) || new Set(topology.remoteSiteCidrs).size !== topology.remoteSiteCidrs.length || !Number.isSafeInteger(topology.healthPort) || topology.healthPort < 1 || topology.healthPort > 65535 || topology.routedTcpPorts.length < 1 || topology.routedTcpPorts.length > 64 || new Set(topology.routedTcpPorts).size !== topology.routedTcpPorts.length || !topology.routedTcpPorts.includes(topology.healthPort) || topology.routedTcpPorts.some((port) => !Number.isSafeInteger(port) || port < 1 || port > 65535) || topology.role === "member" && topology.transport !== "private-lan") {
+      throw new Error("deployment topology is malformed");
+    }
+    if (request.intent.private?.mode === "cloudflare-warp" !== (topology.transport === "cloudflare-warp")) {
+      throw new Error("deployment topology transport differs from private connectivity intent");
+    }
+  }
   if (request.intent.public?.mode === "cloudflare-tunnel") {
     const capability = request.capabilities.public;
     const credentialName = `FZ_TUNNEL_${id2.toUpperCase()}`;
@@ -12943,6 +13113,12 @@ WantedBy=multi-user.target
     const capability = request.capabilities.private;
     const credentialPath = "/etc/forgezero/creds/CF_WARP_CONNECTOR_TOKEN.cred";
     const unit2 = "forgezero-deployment-mesh.service";
+    const forwarding = "/etc/sysctl.d/99-forgezero-mesh.conf";
+    host.write(forwarding, `net.ipv4.ip_forward = 1
+net.ipv6.conf.all.forwarding = 1
+net.ipv6.conf.all.accept_ra = 2
+`, 420);
+    await checked7(host, ["/usr/sbin/sysctl", "-p", forwarding], "Mesh subnet forwarding");
     await host.seal("CF_WARP_CONNECTOR_TOKEN", credentialPath, capability.connectorToken);
     host.write(`/etc/systemd/system/${unit2}`, `[Unit]
 Description=ForgeZero deployment Mesh/WARP connector
@@ -12977,6 +13153,95 @@ WantedBy=multi-user.target
     if (!evidence.private)
       throw new Error("WARP connector readiness failed");
   }
+  if (topology) {
+    const syncAddresses = topology.role === "relay" ? [...topology.localPeerAddresses, ...topology.remoteRelayAddresses] : [topology.localRelayAddress];
+    const topologyEpoch = `topology-${topology.generation.slice("sha256:".length, "sha256:".length + 48)}`;
+    host.write("/etc/forgezero/deployment-topology.env", [
+      `FZ_TOPOLOGY_NODE_IDENTITY=${topology.nodeIdentity}`,
+      `FZ_TOPOLOGY_PEER_ADDRESSES=${[...new Set(syncAddresses)].join(",")}`,
+      `FZ_TOPOLOGY_MEMBERS=${topology.memberIdentities.join(",")}`,
+      `FZ_TOPOLOGY_EPOCH=${topologyEpoch}`,
+      `FZ_TOPOLOGY_SITE=${topology.site}`,
+      `FZ_TOPOLOGY_ROLE=${topology.role}`,
+      `FZ_TOPOLOGY_TRANSPORT=${topology.transport}`,
+      ""
+    ].join(`
+`), 384);
+    const routeUnit = "forgezero-deployment-topology.service";
+    const routeUnitPath = `/etc/systemd/system/${routeUnit}`;
+    const routePairs = topology.role === "member" ? topology.remoteSiteCidrs.map((network) => ({ network, via: topology.localRelayAddress })) : topology.transport === "private-lan" ? topology.remoteSiteCidrs.map((network, index) => ({ network, via: topology.remoteRelayAddresses[index] })) : [];
+    for (const { via } of routePairs) {
+      await checked7(host, ["/usr/sbin/ip", "route", "get", via], `private route gateway ${via}`);
+    }
+    await host.exec(["/usr/bin/systemctl", "disable", "--now", routeUnit]);
+    const forwarding = topology.role !== "member" && topology.remoteSiteCidrs.length > 0 ? `ExecStart=/usr/sbin/sysctl -w net.ipv4.ip_forward=1
+` : "";
+    const starts = routePairs.map(({ network, via }) => `ExecStart=/usr/sbin/ip route replace ${network} via ${via}`).join(`
+`);
+    const stops = routePairs.map(({ network, via }) => `ExecStop=-/usr/sbin/ip route del ${network} via ${via}`).join(`
+`);
+    const noOp = !forwarding && !starts ? `ExecStart=/usr/bin/true
+` : "";
+    host.write(routeUnitPath, `[Unit]
+Description=ForgeZero fenced deployment site routing
+After=network-online.target${topology.transport === "cloudflare-warp" ? " forgezero-deployment-mesh.service" : ""}
+Wants=network-online.target
+
+[Service]
+Type=oneshot
+RemainAfterExit=yes
+${forwarding}${noOp}${starts}${starts ? `
+` : ""}${stops}${stops ? `
+` : ""}
+[Install]
+WantedBy=multi-user.target
+`, 420);
+    for (const source of [...new Set([topology.siteCidr, ...topology.remoteSiteCidrs])]) {
+      for (const port of topology.routedTcpPorts) {
+        await checked7(host, ["/usr/sbin/ufw", "allow", "from", source, "to", "any", "port", String(port), "proto", "tcp"], `private service ${source}:${port}`);
+      }
+    }
+    if (topology.role !== "member")
+      for (const remoteCidr of topology.remoteSiteCidrs) {
+        for (const port of topology.routedTcpPorts) {
+          await checked7(host, [
+            "/usr/sbin/ufw",
+            "route",
+            "allow",
+            "proto",
+            "tcp",
+            "from",
+            topology.siteCidr,
+            "to",
+            remoteCidr,
+            "port",
+            String(port)
+          ], `private routed service ${topology.siteCidr}->${remoteCidr}:${port}`);
+        }
+      }
+    await checked7(host, ["/usr/bin/systemctl", "daemon-reload"], "topology daemon reload");
+    await checked7(host, ["/usr/bin/systemctl", "enable", "--now", routeUnit], "topology routes");
+    const probes = topology.role === "member" ? [topology.localRelayAddress] : topology.remoteRelayAddresses;
+    for (const address of [...new Set(probes)]) {
+      await checked7(host, ["/usr/sbin/ip", "route", "get", address], `private route ${address}`);
+      let ready = false;
+      for (let attempt = 0;attempt < 10; attempt += 1) {
+        if (await host.probe(address, topology.healthPort, 2000)) {
+          ready = true;
+          break;
+        }
+        await host.sleep(1000);
+      }
+      if (!ready)
+        throw new Error(`private topology relay ${address}:${topology.healthPort} is unreachable`);
+    }
+    evidence.topology = {
+      site: topology.site,
+      siteCidr: topology.siteCidr,
+      role: topology.role,
+      probed: [...new Set(probes)]
+    };
+  }
   return evidence;
 }
 
@@ -16417,6 +16682,115 @@ async function readBoundedStdin(maxBytes) {
     throw new Error(`stdin request exceeds ${maxBytes} bytes`);
   return Buffer.from(stdout).toString("utf8");
 }
+// src/deployment-topology.ts
+import { isIP as isIP6 } from "net";
+
+class DeploymentTopologyError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "DeploymentTopologyError";
+  }
+}
+var SAFE = /^(?=.{1,253}$)[A-Za-z0-9](?:[A-Za-z0-9.-]*[A-Za-z0-9])?$/;
+var PRIVATE_V4 = (value) => {
+  const parts = value.split(".").map(Number);
+  return parts.length === 4 && parts.every((part) => Number.isInteger(part) && part >= 0 && part <= 255) && (parts[0] === 10 || parts[0] === 172 && parts[1] >= 16 && parts[1] <= 31 || parts[0] === 192 && parts[1] === 168);
+};
+var validSiteCidr = (value) => {
+  const match = value.match(/^((?:\d{1,3}\.){3})0\/24$/);
+  return Boolean(match && PRIVATE_V4(`${match[1]}1`));
+};
+function planDeploymentTopology(args) {
+  const topology = args.target.topology;
+  if (!topology)
+    throw new DeploymentTopologyError(`target ${args.target.name} has no per-metal topology`);
+  if (!/^[a-z][a-z0-9-]{0,62}$/.test(args.target.name) || !/^[A-Za-z0-9._:-]{1,128}$/.test(args.generation)) {
+    throw new DeploymentTopologyError("topology identity is invalid");
+  }
+  if (args.placements.length < 1 || args.placements.length > 1024)
+    throw new DeploymentTopologyError("topology requires 1 to 1024 placements");
+  const references = new Set;
+  const slots = new Set;
+  for (const placement of args.placements) {
+    if (!SAFE.test(placement.computeReference) || !SAFE.test(placement.nodeIdentity) || !SAFE.test(placement.metalHostname) || isIP6(placement.privateAddress) !== 4 || !PRIVATE_V4(placement.privateAddress) || !validSiteCidr(placement.siteCidr) || !placement.privateAddress.startsWith(placement.siteCidr.slice(0, -4)) || !Number.isSafeInteger(placement.slot) || placement.slot < 0 || placement.slot > 1e6 || references.has(placement.computeReference) || slots.has(placement.slot)) {
+      throw new DeploymentTopologyError("topology placement is malformed or duplicated");
+    }
+    references.add(placement.computeReference);
+    slots.add(placement.slot);
+  }
+  const sites = new Map;
+  for (const placement of args.placements) {
+    const members2 = sites.get(placement.metalHostname) ?? [];
+    members2.push({ ...placement });
+    sites.set(placement.metalHostname, members2);
+  }
+  for (const members2 of sites.values())
+    members2.sort((left, right) => left.slot - right.slot || left.computeReference.localeCompare(right.computeReference));
+  const siteCidrs = new Map;
+  for (const [site, members2] of sites) {
+    const cidrs = new Set(members2.map(({ siteCidr }) => siteCidr));
+    if (cidrs.size !== 1)
+      throw new DeploymentTopologyError(`metal ${site} has inconsistent private CIDRs`);
+    siteCidrs.set(site, members2[0].siteCidr);
+  }
+  if (new Set(siteCidrs.values()).size !== siteCidrs.size) {
+    throw new DeploymentTopologyError("deployment metals require non-overlapping private CIDRs");
+  }
+  const required = 1 + topology.relays.standbyPerMetal;
+  for (const [site, members2] of sites)
+    if (members2.length < required) {
+      throw new DeploymentTopologyError(`metal ${site} cannot satisfy its relay and standby topology`);
+    }
+  const siteNames = [...sites.keys()].sort();
+  let crossTransport;
+  if (siteNames.length <= 2)
+    crossTransport = "private-lan";
+  else {
+    if (topology.crossMetal.mode === "private-lan") {
+      throw new DeploymentTopologyError("three or more metals require the declared Mesh/WARP authority");
+    }
+    crossTransport = "cloudflare-warp";
+  }
+  const active = new Map(siteNames.map((site) => [site, sites.get(site)[0]]));
+  const memberIdentities = [...args.placements].sort((left, right) => left.slot - right.slot || left.computeReference.localeCompare(right.computeReference)).map(({ nodeIdentity }) => nodeIdentity);
+  if (new Set(memberIdentities).size !== memberIdentities.length) {
+    throw new DeploymentTopologyError("deployment node identities must be unique");
+  }
+  if (!Number.isSafeInteger(topology.relays.healthPort) || topology.relays.healthPort < 1 || topology.relays.healthPort > 65535 || !Array.isArray(topology.relays.routedTcpPorts) || topology.relays.routedTcpPorts.length < 1 || topology.relays.routedTcpPorts.length > 64 || new Set(topology.relays.routedTcpPorts).size !== topology.relays.routedTcpPorts.length || !topology.relays.routedTcpPorts.includes(topology.relays.healthPort) || topology.relays.routedTcpPorts.some((port) => !Number.isSafeInteger(port) || port < 1 || port > 65535)) {
+    throw new DeploymentTopologyError("relay health and routed TCP ports are malformed");
+  }
+  return siteNames.flatMap((site) => {
+    const members2 = sites.get(site);
+    const relay = active.get(site);
+    const remoteRelayAddresses = siteNames.filter((other) => other !== site).map((other) => active.get(other).privateAddress);
+    const remoteRelayIdentities = siteNames.filter((other) => other !== site).map((other) => active.get(other).nodeIdentity);
+    const remoteSiteCidrs = siteNames.filter((other) => other !== site).map((other) => siteCidrs.get(other));
+    return members2.map((placement, index) => {
+      const role = index === 0 ? "relay" : index === 1 && topology.relays.standbyPerMetal === 1 ? "standby" : "member";
+      const crossSite = role !== "member" && siteNames.length > 1;
+      const localPeers = role === "relay" ? members2.filter(({ privateAddress }) => privateAddress !== placement.privateAddress) : [relay];
+      const localPeerAddresses = role === "relay" ? localPeers.map(({ privateAddress }) => privateAddress) : [relay.privateAddress];
+      const localPeerIdentities = role === "relay" ? localPeers.map(({ nodeIdentity }) => nodeIdentity) : [relay.nodeIdentity];
+      return {
+        ...placement,
+        role,
+        transport: crossSite ? crossTransport : "private-lan",
+        localRelayReference: relay.computeReference,
+        localRelayAddress: relay.privateAddress,
+        localPeerAddresses,
+        localPeerIdentities,
+        remoteRelayAddresses: crossSite ? remoteRelayAddresses : [],
+        remoteRelayIdentities: crossSite ? remoteRelayIdentities : [],
+        remoteSiteCidrs: siteNames.length > 1 ? remoteSiteCidrs : [],
+        healthPort: topology.relays.healthPort,
+        routedTcpPorts: [...topology.relays.routedTcpPorts],
+        memberIdentities,
+        warpRequired: crossSite && crossTransport === "cloudflare-warp",
+        generation: args.generation
+      };
+    });
+  });
+}
 
 // src/index.ts
 function agentCommandArgs(args, command3) {
@@ -17500,6 +17874,7 @@ export {
   projectVaultCoordinate,
   projectVaultCacheKey,
   probeAgentSocket,
+  planDeploymentTopology,
   observeSoftwareHost,
   observeAgentHost,
   normalizeEgressTcpPorts,
@@ -17555,6 +17930,7 @@ export {
   OS_CATALOG,
   METAL_SYSTEMD_CREDENTIALS,
   MAX_AGENT_TARBALL_BYTES,
+  DeploymentTopologyError,
   DeploymentInputError,
   DeploymentError,
   DEFAULT_SOFTWARE_HELPER_SOCKET,