@forgezero/agent 0.1.78 → 0.1.80

package/dist/deploy.d.ts

@@ -74,6 +74,36 @@ export interface ComputeConnectivityDefinition {
         };
     };
 }
+/**
+ * A deployment may require one stable coordination role per physical site.
+ * The control plane groups computes by their admitted Metal identity; users do
+ * not name a particular machine as "master".  A failed relay is replaced by
+ * the declared standby and the assignment generation is fenced by the API.
+ */
+export interface ComputeTopologyDefinition {
+    groupBy: 'metal';
+    relays: {
+        activePerMetal: 1;
+        standbyPerMetal: 0 | 1;
+        /** Exact TCP endpoint used to prove the selected relay is actually serving. */
+        healthPort: number;
+        /** Exact private TCP services routed and admitted between deployment sites. */
+        routedTcpPorts: readonly number[];
+    };
+    crossMetal: {
+        mode: 'private-lan';
+    } | {
+        mode: 'cloudflare-warp';
+        credential: string;
+        network: StringValue;
+    } | {
+        mode: 'auto';
+        /** One or two directly reachable sites never install WARP. */
+        directPrivateMaximumMetals: 2;
+        credential: string;
+        network: StringValue;
+    };
+}
 export type ResolvableJsonValue = JsonPrimitive | ValueReference | readonly ResolvableJsonValue[] | {
     [key: string]: ResolvableJsonValue;
 };
@@ -165,6 +195,7 @@ export interface TargetDefinition {
     };
     /** Per-slot connectivity intent. Credential names resolve through the scoped Vault, never to plan values. */
     connectivity?: ComputeConnectivityDefinition;
+    topology?: ComputeTopologyDefinition;
     placement?: {
         spreadBy?: readonly ('metal' | 'region' | 'zone')[];
         antiAffinity?: readonly string[];
@@ -190,6 +221,7 @@ export interface ComputePoolDefinition {
     reuse?: 'prefer' | 'require';
     provisioning?: TargetDefinition['provisioning'];
     connectivity?: ComputeConnectivityDefinition;
+    topology?: ComputeTopologyDefinition;
     labels?: Readonly<Record<string, string>>;
     placement?: TargetDefinition['placement'];
 }
@@ -354,6 +386,10 @@ export type StepScope = {
     kind: 'target-batches';
     target: string;
     size: number;
+} | {
+    kind: 'topology-role';
+    target: string;
+    role: 'relay' | 'standby' | 'member';
 };
 export interface RetryDefinition {
     attempts: number;
@@ -480,7 +516,7 @@ export declare const ref: {
     target: (target: string, property: string) => ValueReference;
     deployment: (property: string) => ValueReference;
     /** Secret-free control-plane assignment of the compute executing this step. */
-    execution: (property: "targetName" | "slot" | "releaseExecutor" | "runtime" | "cpuCores" | "memoryMiB" | "storageGiB") => ValueReference;
+    execution: (property: "targetName" | "slot" | "releaseExecutor" | "runtime" | "cpuCores" | "memoryMiB" | "storageGiB" | "site" | "topologyRole" | "topologyTransport" | "localRelayAddress") => ValueReference;
 };
 export declare const conditions: {
     all: (...values: Condition[]) => Condition;

package/dist/deploy.js

@@ -173,6 +173,7 @@ var target = {
       },
       ...value.provisioning ? { provisioning: value.provisioning } : {},
       ...value.connectivity ? { connectivity: value.connectivity } : {},
+      ...value.topology ? { topology: value.topology } : {},
       ...value.placement ? { placement: value.placement } : {}
     };
   }

package/dist/deployment-connectivity.d.ts

@@ -28,12 +28,31 @@ export interface DeploymentConnectivityCapabilities {
     private?: {
         connectorId: string;
         connectorToken: string;
+        siteRouteId: string;
     };
 }
+export interface DeploymentConnectivityTopology {
+    site: string;
+    nodeIdentity: string;
+    siteCidr: string;
+    role: 'relay' | 'standby' | 'member';
+    transport: 'private-lan' | 'cloudflare-warp';
+    localRelayAddress: string;
+    localPeerAddresses: readonly string[];
+    localPeerIdentities: readonly string[];
+    remoteRelayAddresses: readonly string[];
+    remoteRelayIdentities: readonly string[];
+    remoteSiteCidrs: readonly string[];
+    memberIdentities: readonly string[];
+    healthPort: number;
+    routedTcpPorts: readonly number[];
+    generation: string;
+}
 export interface DeploymentConnectivityRequest {
     key: string;
     intent: DeploymentConnectivityIntent;
     capabilities: DeploymentConnectivityCapabilities;
+    topology?: DeploymentConnectivityTopology;
 }
 export interface DeploymentConnectivityEvidence {
     key: string;
@@ -49,6 +68,12 @@ export interface DeploymentConnectivityEvidence {
         unit: string;
         active: true;
     };
+    topology?: {
+        site: string;
+        siteCidr: string;
+        role: DeploymentConnectivityTopology['role'];
+        probed: string[];
+    };
 }
 export interface DeploymentConnectivityHost {
     seal(name: string, path: string, value: string): Promise<void>;
@@ -57,6 +82,7 @@ export interface DeploymentConnectivityHost {
         exitCode: number;
         output: string;
     }>;
+    probe(address: string, port: number, timeoutMs: number): Promise<boolean>;
     sleep(ms: number): Promise<void>;
 }
 /** Apply only connector-scoped capabilities; the broad Cloudflare token never reaches this helper. */

package/dist/deployment-connectivity.js

@@ -1,6 +1,7 @@
 // src/deployment-connectivity.ts
 import { createHash } from "node:crypto";
 import { mkdirSync, renameSync, writeFileSync } from "node:fs";
+import { createConnection } from "node:net";
 import { dirname } from "node:path";
 
 // src/process-input.ts
@@ -53,6 +54,21 @@ var defaultHost = {
     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((resolve) => {
+    const socket = createConnection({ host: address, port });
+    let settled = false;
+    const finish = (value) => {
+      if (settled)
+        return;
+      settled = true;
+      socket.destroy();
+      resolve(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 validate(request) {
@@ -67,7 +83,7 @@ function validate(request) {
   } else if (request.capabilities.public)
     throw new Error("unexpected public deployment capability");
   if (privateIntent?.mode === "cloudflare-warp") {
-    if (!NAME.test(privateIntent.credential) || privateIntent.network.length < 1 || privateIntent.network.length > 128 || !request.capabilities.private || !UUID.test(request.capabilities.private.connectorId) || !TOKEN.test(request.capabilities.private.connectorToken)) {
+    if (!NAME.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) || !TOKEN.test(request.capabilities.private.connectorToken)) {
       throw new Error("private deployment connectivity is malformed");
     }
   } else if (request.capabilities.private)
@@ -77,6 +93,22 @@ async function applyDeploymentConnectivity(request, host = defaultHost) {
   validate(request);
   const id = idFor(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_${id.toUpperCase()}`;
@@ -114,6 +146,12 @@ WantedBy=multi-user.target
     const capability = request.capabilities.private;
     const credentialPath = "/etc/forgezero/creds/CF_WARP_CONNECTOR_TOKEN.cred";
     const unit = "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 checked(host, ["/usr/sbin/sysctl", "-p", forwarding], "Mesh subnet forwarding");
     await host.seal("CF_WARP_CONNECTOR_TOKEN", credentialPath, capability.connectorToken);
     host.write(`/etc/systemd/system/${unit}`, `[Unit]
 Description=ForgeZero deployment Mesh/WARP connector
@@ -148,6 +186,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 checked(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 checked(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 checked(host, [
+            "/usr/sbin/ufw",
+            "route",
+            "allow",
+            "proto",
+            "tcp",
+            "from",
+            topology.siteCidr,
+            "to",
+            remoteCidr,
+            "port",
+            String(port)
+          ], `private routed service ${topology.siteCidr}->${remoteCidr}:${port}`);
+        }
+      }
+    await checked(host, ["/usr/bin/systemctl", "daemon-reload"], "topology daemon reload");
+    await checked(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 checked(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;
 }
 export {

package/dist/deployment-targets.js

@@ -99,6 +99,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],
@@ -117,7 +130,8 @@ function resolveDeploymentTargets(plan, supplied = {}) {
         }
       },
       ...target.provisioning ? { provisioning: { ...target.provisioning } } : {},
-      ...connectivity ? { connectivity } : {}
+      ...connectivity ? { connectivity } : {},
+      ...topology ? { topology } : {}
     };
   });
 }

package/dist/deployment-topology.d.ts

@@ -0,0 +1,46 @@
+import type { ResolvedDeploymentTarget } from './deployment';
+export type DeploymentTopologyRole = 'relay' | 'standby' | 'member';
+export type DeploymentTopologyTransport = 'private-lan' | 'cloudflare-warp';
+export interface DeploymentTopologyPlacement {
+    computeReference: string;
+    /** Stable non-secret node identity generated by the control plane. */
+    nodeIdentity: string;
+    slot: number;
+    metalHostname: string;
+    privateAddress: string;
+    /** Exact non-overlapping private subnet owned by this admitted Metal. */
+    siteCidr: string;
+}
+export interface DeploymentTopologyAssignment extends DeploymentTopologyPlacement {
+    role: DeploymentTopologyRole;
+    transport: DeploymentTopologyTransport;
+    localRelayReference: string;
+    localRelayAddress: string;
+    /** Same-metal peers; ordinary members receive only the active relay. */
+    localPeerAddresses: readonly string[];
+    localPeerIdentities: readonly string[];
+    remoteRelayAddresses: readonly string[];
+    remoteRelayIdentities: readonly string[];
+    remoteSiteCidrs: readonly string[];
+    memberIdentities: readonly string[];
+    healthPort: number;
+    routedTcpPorts: readonly number[];
+    /** Only relay and standby computes may carry the cross-metal WARP connector. */
+    warpRequired: boolean;
+    generation: string;
+}
+export declare class DeploymentTopologyError extends Error {
+    constructor(message: string);
+}
+/**
+ * Deterministically elect one relay per admitted Metal site. Auto transport
+ * keeps one- and two-metal deployments on their private addresses and uses
+ * WARP only after a third Metal site is admitted. Network-specific deploy
+ * steps still own readiness probes; a failed private route must stop the
+ * release, never silently broaden authority by installing WARP.
+ */
+export declare function planDeploymentTopology(args: {
+    target: Pick<ResolvedDeploymentTarget, 'name' | 'topology'>;
+    placements: readonly DeploymentTopologyPlacement[];
+    generation: string;
+}): DeploymentTopologyAssignment[];

package/dist/deployment-topology.js

@@ -0,0 +1,113 @@
+// src/deployment-topology.ts
+import { isIP } from "node: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) || isIP(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 members = sites.get(placement.metalHostname) ?? [];
+    members.push({ ...placement });
+    sites.set(placement.metalHostname, members);
+  }
+  for (const members of sites.values())
+    members.sort((left, right) => left.slot - right.slot || left.computeReference.localeCompare(right.computeReference));
+  const siteCidrs = new Map;
+  for (const [site, members] of sites) {
+    const cidrs = new Set(members.map(({ siteCidr }) => siteCidr));
+    if (cidrs.size !== 1)
+      throw new DeploymentTopologyError(`metal ${site} has inconsistent private CIDRs`);
+    siteCidrs.set(site, members[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, members] of sites)
+    if (members.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 members = 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 members.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" ? members.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
+      };
+    });
+  });
+}
+export {
+  planDeploymentTopology,
+  DeploymentTopologyError
+};

package/dist/deployment.d.ts

@@ -36,6 +36,25 @@ export interface DeploymentRequest {
         sharing: ResolvedDeploymentTarget['allocation']['sharing'];
         resources: ResolvedDeploymentTarget['allocation']['resources'];
         connectivity?: DeploymentConnectivityIntent;
+        topology?: {
+            site: string;
+            nodeIdentity: string;
+            role: 'relay' | 'standby' | 'member';
+            transport: 'private-lan' | 'cloudflare-warp';
+            siteCidr: string;
+            localRelayReference: string;
+            localRelayAddress: string;
+            localPeerAddresses: readonly string[];
+            localPeerIdentities: readonly string[];
+            remoteRelayAddresses: readonly string[];
+            remoteRelayIdentities: readonly string[];
+            remoteSiteCidrs: readonly string[];
+            memberIdentities: readonly string[];
+            healthPort: number;
+            routedTcpPorts: readonly number[];
+            warpRequired: boolean;
+            generation: string;
+        };
     };
     /** Connector-scoped, one-claim capabilities. Never the project Cloudflare management token. */
     connectivityCapabilities?: DeploymentConnectivityCapabilities;
@@ -121,6 +140,27 @@ export interface ResolvedDeploymentTarget {
             };
         };
     };
+    topology?: {
+        groupBy: 'metal';
+        relays: {
+            activePerMetal: 1;
+            standbyPerMetal: 0 | 1;
+            healthPort: number;
+            routedTcpPorts: readonly number[];
+        };
+        crossMetal: {
+            mode: 'private-lan';
+        } | {
+            mode: 'cloudflare-warp';
+            credential: string;
+            network: string;
+        } | {
+            mode: 'auto';
+            directPrivateMaximumMetals: 2;
+            credential: string;
+            network: string;
+        };
+    };
 }
 /**
  * How the credential-bearing agent may read one server-owned Git source.