@forgezero/agent 0.1.79 → 0.1.80

package/README.md

@@ -64,7 +64,8 @@ Every row links to the detailed explanation and named-import/example area below.
 | @forgezero/agent/definition | Legacy version 3 JSON deployment compatibility contract. | Bun/Node host | [Reference + usage](#forgezero-agent-definition) |
 | @forgezero/agent/deploy | Typed deployment authoring builders, built-in provider requirements and versioned action constructors. | Bun/Node host | [Reference + usage](#forgezero-agent-deploy) |
 | @forgezero/agent/deployment-targets | Bounded input resolution and stable compute-target assignment for typed plans; emits requirements and slots rather than physical hostnames. | Bun/Node host | [Reference + usage](#forgezero-agent-deployment-targets) |
-| @forgezero/agent/deployment-connectivity | Root-owned application of per-target Cloudflare Tunnel or WARP connector capabilities without exposing the project management token to a compute. | Bun/Node host | [Reference + usage](#forgezero-agent-deployment-connectivity) |
+| @forgezero/agent/deployment-connectivity | Root-owned convergence of exact private routes, routed-port firewall rules and per-target Cloudflare Tunnel or Mesh connector capabilities without exposing the project management token to a compute. | Bun/Node host | [Reference + usage](#forgezero-agent-deployment-connectivity) |
+| @forgezero/agent/deployment-topology | Pure per-Metal relay election and hierarchical peer assignment: one or two Metals stay direct-private, while three or more grant Mesh/WARP only to relay and standby. | Bun/Node host | [Reference + usage](#forgezero-agent-deployment-topology) |
 | @forgezero/agent/deploy-plan | Runtime validation, canonicalization and semantic digest for inert deployment plans. | Bun/Node host | [Reference + usage](#forgezero-agent-deploy-plan) |
 | @forgezero/agent/deploy-plan-runner | Conditional DAG execution with bounded retry, compensation and failure policy over injected action handlers. | Bun/Node host | [Reference + usage](#forgezero-agent-deploy-plan-runner) |
 | @forgezero/agent/deploy-compiler | Explicit developer/CI compiler from forgezero.deploy.ts to canonical .fz/deploy.plan.json; never used to execute project TypeScript in production. | Bun/Node host | [Reference + usage](#forgezero-agent-deploy-compiler) |
@@ -1067,7 +1068,7 @@ export const selectedCapability = DEPLOY_SCHEMA_URL;
 <a id="forgezero-agent-deploy"></a>
 ## @forgezero/agent/deploy
 
-Typed deployment authoring builders, built-in provider requirements and versioned action constructors. This entry exposes 14 named value exports and 41 named type exports. The generated import block lists one name per line for scanning and copying; keep only the names used by your file.
+Typed deployment authoring builders, built-in provider requirements and versioned action constructors. This entry exposes 14 named value exports and 42 named type exports. The generated import block lists one name per line for scanning and copying; keep only the names used by your file.
 
 ```text
 import {
@@ -1096,6 +1097,7 @@ import type {
   ComponentDefinition,
   ComputeConnectivityDefinition,
   ComputePoolDefinition,
+  ComputeTopologyDefinition,
   Condition,
   ConditionOperand,
   ContainerdProviderConfig,
@@ -1134,7 +1136,7 @@ import type {
 
 ## @forgezero/agent/deploy — Author a typed, placed containerd deployment
 
-TypeScript is authoring only. The checked-in canonical plan is what Agents validate and execute. Targets declare bounded resource/cardinality intent, not hostnames. The API reserves eligible project capacity or provisions only under the reviewed plan and spend ceiling, assigns stable slots, and the Agent runs only its exact assignment. runc containers must declare hard CPU, memory and PID limits, bounded storage, loopback ingress and a health-gated rollout; select Kata QEMU SNP when the workload needs host isolation.
+TypeScript is authoring only. The checked-in canonical plan is what Agents validate and execute. Targets declare bounded resource/cardinality intent, not hostnames. The API reserves eligible project capacity or provisions only under the reviewed plan and spend ceiling, assigns stable slots, and the Agent runs only its exact assignment. An optional per-metal topology elects one active relay and one standby without naming computes: one or two Metals use proven private relay links and never install WARP, while three or more give Mesh/WARP authority only to relay and standby. runc containers must declare hard CPU, memory and PID limits, bounded storage, loopback ingress and a health-gated rollout; select Kata QEMU SNP when the workload needs host isolation.
 
 ```text
 import {
@@ -1174,7 +1176,23 @@ export default defineDeployment({
 	  connectivity: {
 	    private: { mode: 'private-lan' },
 	    public: { mode: 'cloudflare-tunnel', credential: 'cloudflare', zone: 'example.com', hostname: { mode: 'indexed', prefix: 'api' } }
-	  }
+	  },
+	  topology: {
+	    groupBy: 'metal',
+	    relays: {
+	      activePerMetal: 1,
+	      standbyPerMetal: 1,
+	      healthPort: 3000,
+	      routedTcpPorts: [3000]
+	    },
+	    crossMetal: {
+	      mode: 'auto',
+	      directPrivateMaximumMetals: 2,
+	      credential: 'cloudflare',
+	      network: 'orders-api'
+	    }
+	  },
+	  placement: { spreadBy: ['metal'], antiAffinity: ['orders-api'] }
 	}) },
 	requirements: {
 	  containerd: providers.containerd.require(), nginx: providers.nginx.require(),
@@ -1237,7 +1255,7 @@ export const selectedCapability = DeploymentInputError;
 <a id="forgezero-agent-deployment-connectivity"></a>
 ## @forgezero/agent/deployment-connectivity
 
-Root-owned application of per-target Cloudflare Tunnel or WARP connector capabilities without exposing the project management token to a compute. This entry exposes 1 named value export and 5 named type exports. The generated import block lists one name per line for scanning and copying; keep only the names used by your file.
+Root-owned convergence of exact private routes, routed-port firewall rules and per-target Cloudflare Tunnel or Mesh connector capabilities without exposing the project management token to a compute. This entry exposes 1 named value export and 6 named type exports. The generated import block lists one name per line for scanning and copying; keep only the names used by your file.
 
 ```text
 import {
@@ -1250,6 +1268,7 @@ import type {
   DeploymentConnectivityHost,
   DeploymentConnectivityIntent,
   DeploymentConnectivityRequest,
+  DeploymentConnectivityTopology,
 } from '@forgezero/agent/deployment-connectivity';
 ```
 
@@ -1265,6 +1284,37 @@ import {
 export const selectedCapability = applyDeploymentConnectivity;
 ```
 
+<a id="forgezero-agent-deployment-topology"></a>
+## @forgezero/agent/deployment-topology
+
+Pure per-Metal relay election and hierarchical peer assignment: one or two Metals stay direct-private, while three or more grant Mesh/WARP only to relay and standby. This entry exposes 2 named value exports and 4 named type exports. The generated import block lists one name per line for scanning and copying; keep only the names used by your file.
+
+```text
+import {
+  DeploymentTopologyError,
+  planDeploymentTopology,
+} from '@forgezero/agent/deployment-topology';
+
+import type {
+  DeploymentTopologyAssignment,
+  DeploymentTopologyPlacement,
+  DeploymentTopologyRole,
+  DeploymentTopologyTransport,
+} from '@forgezero/agent/deployment-topology';
+```
+
+## @forgezero/agent/deployment-topology — Use this entry point
+
+This minimal executable use imports one concrete value from this exact entry point without a wildcard or package-root detour. Keep the value or values the application actually needs; the full named inventory remains directly above it.
+
+```text
+import {
+  DeploymentTopologyError,
+} from '@forgezero/agent/deployment-topology';
+
+export const selectedCapability = DeploymentTopologyError;
+```
+
 <a id="forgezero-agent-deploy-plan"></a>
 ## @forgezero/agent/deploy-plan
 
@@ -1645,7 +1695,7 @@ if (!validate(deploymentDefinition)) throw new Error(JSON.stringify(validate.err
 <a id="forgezero-agent-software"></a>
 ## @forgezero/agent/software
 
-Exact managed-software inventory, requirement and evidence contracts. This entry exposes 13 named value exports and 10 named type exports. The generated import block lists one name per line for scanning and copying; keep only the names used by your file.
+Exact managed-software inventory, requirement and evidence contracts. This entry exposes 14 named value exports and 10 named type exports. The generated import block lists one name per line for scanning and copying; keep only the names used by your file.
 
 ```text
 import {
@@ -1660,6 +1710,7 @@ import {
   executeSoftwareOperation,
   observeSoftwareHost,
   runSoftwareCommand,
+  softwareDownloadCommand,
   softwareSpawnFailure,
   validateSoftwareRequirements,
 } from '@forgezero/agent/software';

package/dist/agent-heartbeat.js

@@ -750,7 +750,7 @@ async function postSignedNode(options, path, body) {
 }
 
 // src/version.ts
-var VERSION3 = "0.1.79";
+var VERSION3 = "0.1.80";
 
 // src/agent-heartbeat.ts
 function readAgentHostMetrics() {

package/dist/bootstrap.js

@@ -1416,7 +1416,7 @@ var UPDATE_RETRY_BASE_MS = 5 * 60000;
 var UPDATE_RETRY_MAX_MS = 24 * 60 * 60000;
 
 // src/version.ts
-var VERSION = "0.1.79";
+var VERSION = "0.1.80";
 
 // src/software.ts
 var PINNED_BUN_VERSION = "1.3.14";
@@ -3089,7 +3089,14 @@ function validatePlatformSharedEnvironment(input) {
     throw new Error("Bootstrap email provider must be smtp or jetemail.");
   }
   boundedInteger("publicApiPort", input.publicApiPort, 1024, 65533);
-  boundedInteger("seedSyncMembers", input.seedSyncMembers, 1, 64);
+  if (!Array.isArray(input.seedSyncMembers) || input.seedSyncMembers.length < 3 || input.seedSyncMembers.length > 64 || new Set(input.seedSyncMembers).size !== input.seedSyncMembers.length) {
+    throw new Error("seedSyncMembers must contain 3 to 64 unique physical host identities.");
+  }
+  for (const member of input.seedSyncMembers)
+    safeAtom("seedSyncMembers item", member);
+  if (!input.seedSyncMembers.includes(input.nodeHostname)) {
+    throw new Error("seedSyncMembers must include this nodeHostname.");
+  }
   boundedInteger("concurrencyLimit", input.concurrencyLimit, 1, 1e6);
   boundedInteger("drainDeadlineMs", input.drainDeadlineMs, 1000, 300000);
   boundedInteger("otlpFlushIntervalMs", input.otlpFlushIntervalMs, 1000, 300000);
@@ -3169,7 +3176,7 @@ function renderPlatformSharedEnvironment(input) {
     FZ_DB_MASTER: value.databaseMaster ?? "",
     FZ_DB_NETWORK_MODE: value.databaseNetworkMode,
     FZ_SEED_SYNC_PEERS: value.seedSyncPeers.join(","),
-    FZ_SEED_SYNC_MEMBERS: String(value.seedSyncMembers),
+    FZ_SEED_SYNC_MEMBERS: value.seedSyncMembers.join(","),
     FZ_SEED_SYNC_EPOCH: value.seedSyncEpoch,
     FZ_SEED_SYNC_CREDENTIAL: "seed-sync-root",
     FZ_SHARED_DIR: value.sharedDirectory,
@@ -3238,7 +3245,12 @@ function platformApiCredentialSpecs(options) {
   ];
 }
 function renderPlatformApiUnits(input) {
-  for (const path of [input.sharedDirectory, input.sharedEnvironmentFile, input.slotsDirectory]) {
+  for (const path of [
+    input.sharedDirectory,
+    input.sharedEnvironmentFile,
+    input.slotsDirectory,
+    ...input.topologyEnvironmentFile ? [input.topologyEnvironmentFile] : []
+  ]) {
     if (!path.startsWith("/") || /[\r\n]/.test(path))
       throw new Error("Runtime paths must be absolute and single-line.");
   }
@@ -3252,6 +3264,8 @@ function renderPlatformApiUnits(input) {
   const credentials = input.credentials.map((credential) => `LoadCredentialEncrypted=${credential.name}:${credential.encryptedPath}`).join(`
 `);
   const capacityEnvironment = input.capacityEnvironmentFile ? `EnvironmentFile=-${input.capacityEnvironmentFile}
+` : "";
+  const topologyEnvironment = input.topologyEnvironmentFile ? `EnvironmentFile=-${input.topologyEnvironmentFile}
 ` : "";
   const template = `[Unit]
 Description=ForgeZero (%i slot)
@@ -3265,7 +3279,7 @@ WorkingDirectory=${input.slotsDirectory}/%i
 Environment=NODE_ENV=production
 Environment=FZ_SLOT=%i
 EnvironmentFile=${input.sharedEnvironmentFile}
-${capacityEnvironment}${credentials}
+${capacityEnvironment}${topologyEnvironment}${credentials}
 ExecStart=/usr/local/bin/bun run ${input.slotsDirectory}/%i/src/index.ts
 Restart=always
 RestartSec=2
@@ -4517,7 +4531,8 @@ async function applyBootstrap(input, host = localBootstrapHost(), secrets, depen
       greenPort: runtime.greenPort,
       collectorUnit: runtime.environment.otlpCollectorUnit,
       credentials,
-      capacityEnvironmentFile: "/etc/forgezero/capacity.env"
+      capacityEnvironmentFile: "/etc/forgezero/capacity.env",
+      topologyEnvironmentFile: "/etc/forgezero/deployment-topology.env"
     });
     const edge = renderPlatformNginx({
       publicPort: runtime.environment.publicApiPort,

package/dist/deploy-compiler.js

@@ -203,7 +203,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 };
@@ -635,6 +635,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)
@@ -789,7 +795,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`);
@@ -911,6 +917,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);
@@ -934,6 +979,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);

package/dist/deploy-plan-runner.js

@@ -203,7 +203,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 };
@@ -635,6 +635,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)
@@ -789,7 +795,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`);
@@ -911,6 +917,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);
@@ -934,6 +979,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);

package/dist/deploy-plan.js

@@ -203,7 +203,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 };
@@ -635,6 +635,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)
@@ -789,7 +795,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`);
@@ -911,6 +917,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);
@@ -934,6 +979,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);

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. */