@forgezero/agent 0.1.40 → 0.1.42

package/dist/credential-schema.js

@@ -284,6 +284,51 @@ var AGENT_CREDENTIAL_LOCATIONS = [
   "platform-compute",
   "tenant-compute"
 ];
+var CLOUDFLARE_CREDENTIAL_NAMES = {
+  api: "CF_API_TOKEN",
+  tunnel: "CF_TUNNEL_TOKEN",
+  connector: "CF_TUNNEL_CONNECTOR_TOKEN",
+  realtimePublish: "REALTIME_PUBLISH_SECRET",
+  realtimeTicket: "REALTIME_TICKET_SECRET"
+};
+var CLOUDFLARE_CREDENTIAL_SCHEMA = {
+  CF_TUNNEL_TOKEN: {
+    permissions: [
+      "Account:Cloudflare Tunnel Write",
+      "Account:Cloudflare One Connector: WARP Write",
+      "Account:Cloudflare One Networks Write",
+      "Account:Zero Trust Write",
+      "Zone:DNS Write"
+    ],
+    platformBootstrap: "attended-file",
+    platformRuntime: "vault",
+    tenantControl: "vault"
+  },
+  CF_API_TOKEN: {
+    permissions: ["Account:Workers KV Storage Write", "Account:Workers Scripts Write"],
+    platformBootstrap: "attended-file",
+    platformRuntime: "vault-then-systemd",
+    tenantControl: "vault"
+  },
+  CF_TUNNEL_CONNECTOR_TOKEN: {
+    permissions: ["one named Tunnel connector"],
+    platformBootstrap: "derived",
+    platformRuntime: "systemd",
+    tenantControl: "derived"
+  },
+  REALTIME_PUBLISH_SECRET: {
+    permissions: ["Worker realtime publish endpoint"],
+    platformBootstrap: "generated-and-installed-worker-secret",
+    platformRuntime: "vault-then-systemd",
+    tenantControl: "vault"
+  },
+  REALTIME_TICKET_SECRET: {
+    permissions: ["Worker realtime subscription tickets"],
+    platformBootstrap: "generated-and-installed-worker-secret",
+    platformRuntime: "vault-then-systemd",
+    tenantControl: "vault"
+  }
+};
 var AGENT_CREDENTIAL_POLICY = {
   operator: { vault: false, systemdFallback: false, attendedFile: true },
   metal: { vault: false, systemdFallback: true, attendedFile: false },
@@ -330,6 +375,8 @@ export {
   deploymentCredentialSchema,
   credentialBinding,
   METAL_SYSTEMD_CREDENTIALS,
+  CLOUDFLARE_CREDENTIAL_SCHEMA,
+  CLOUDFLARE_CREDENTIAL_NAMES,
   AGENT_CREDENTIAL_POLICY,
   AGENT_CREDENTIAL_LOCATIONS
 };

package/dist/definition.d.ts

@@ -2,17 +2,42 @@ import type { Pipeline, PipelineStep } from './pipeline';
 import { type DeploymentChannel, type SoftwareRequirement } from './software';
 import { type CapacityCalibrationOptions } from './capacity-calibration';
 /**
- * Version two separates a repository's deploy recipe from the computes that use
- * it. A target chooses one named profile in the control plane; compute names,
- * counts and cluster leadership never belong in Git.
+ * Version three keeps fleet coordinates out of Git and replaces shell command
+ * strings with exact argv vectors. A target chooses one named profile in the
+ * control plane; compute names, counts and cluster leadership never belong in
+ * the repository definition.
  */
-export declare const PIPELINE_VERSION: 2;
-export declare const DEPLOY_SCHEMA_URL = "https://www.forgezero.net/schemas/deploy-v2.json";
+export declare const PIPELINE_VERSION: 3;
+export declare const DEPLOY_SCHEMA_URL = "https://www.forgezero.net/schemas/deploy-v3.json";
 export interface PipelineProfile {
     software: readonly SoftwareRequirement[];
+    /** Optional Agent-supervised HTTP service behind one stable nginx port. */
+    service?: DeploymentService;
     /** Explicit opt-in, provider-neutral loopback GET probe run after target health. */
     capacityCalibration?: CapacityCalibrationOptions;
 }
+export type DeploymentPortAllocation = {
+    mode: 'fixed';
+    ports: readonly number[];
+} | {
+    mode: 'dynamic';
+    from: number;
+    to: number;
+};
+export interface DeploymentService {
+    strategy: 'direct' | 'blue-green';
+    /** Stable loopback ingress used by Tunnel/nginx consumers. */
+    publicPort: number;
+    /** One application port for direct, two for blue-green. */
+    applicationPorts: DeploymentPortAllocation;
+    /** Exact argv. `${FZ_APP_PORT}` and `${FZ_RELEASE}` are materialized by the Agent. */
+    command: readonly string[];
+    healthPath: string;
+    /** Optional node-wide active connection ceiling enforced by nginx with HTTP 503. */
+    maxConnections?: number;
+    websocket?: boolean;
+    drainMs?: number;
+}
 export interface DeployStep extends PipelineStep {
     phase: 'build' | 'release' | 'migrate' | 'health';
     /** Run on this target, or on the one deterministic release executor. */
@@ -32,6 +57,7 @@ export interface DeployDefinition {
 export declare class DefinitionError extends Error {
     constructor(message: string);
 }
+export declare function validateDeploymentService(value: unknown, where?: string): DeploymentService;
 /** Validate parsed JSON before any command from it is allowed to run. */
 export declare function parseDeployDefinition(value: unknown, options?: {
     channel?: DeploymentChannel;

package/dist/definition.js

@@ -1,7 +1,22 @@
 // src/software.ts
-import { readFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import {
+  accessSync,
+  chmodSync,
+  copyFileSync,
+  mkdtempSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  symlinkSync,
+  unlinkSync,
+  writeFileSync
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 var PINNED_BUN_VERSION = "1.3.14";
-var BUN_INSTALLER_SHA256 = "bab8acfb046aac8c72407bdcce903957665d655d7acaa3e11c7c4616beae68dd";
+var BUN_RELEASE_SHA256 = "951ee2aee855f08595aeec6225226a298d3fea83a3dcd6465c09cbccdf7e848f";
 var ARANGO_SHA256 = "b5a9197b4343f2ed554e1ebc1ef8e6529c7c39cde0035cdc311a4747a3355066";
 var CLOUDFLARED_SHA256 = "9d71c677db00134c1bd4144b7783486b654ad281b1ea62b4972098d19f770f17";
 var OS_CATALOG = [
@@ -12,41 +27,151 @@ var SOFTWARE_CATALOG = [
   { id: "nginx", version: "ubuntu-26.04", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
   { id: "arangodb", version: "3.11.14", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
   { id: "cloudflared", version: "2026.7.3", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
+  { id: "cloudflare-warp", version: "2026.6.822.0-min", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
   { id: "ufw", version: "ubuntu-26.04", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
   { id: "openssh-client", version: "ubuntu-26.04", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" }
 ];
 var UBUNTU_2604_X64 = [
-  {
-    requirement: { id: "bun", version: "1.3.14" },
-    check: 'test "$(/usr/local/bin/bun --version 2>/dev/null)" = 1.3.14',
-    install: `tmp=$(mktemp -d); trap 'rm -rf "$tmp"' EXIT; ` + `curl -fsSL https://bun.sh/install -o "$tmp/install"; ` + `echo "${BUN_INSTALLER_SHA256}  $tmp/install" | sha256sum -c -; ` + `BUN_INSTALL="$tmp/bun" BUN_VERSION=1.3.14 bash "$tmp/install" >/dev/null; ` + `install -d -m 0755 /usr/local/lib/forgezero/runtime; ` + `install -m 0755 "$tmp/bun/bin/bun" /usr/local/lib/forgezero/runtime/bun.next; ` + `mv -Tf /usr/local/lib/forgezero/runtime/bun.next /usr/local/lib/forgezero/runtime/bun; ` + `ln -sfn /usr/local/lib/forgezero/runtime/bun /usr/local/bin/bun`
-  },
-  {
-    requirement: { id: "nginx", version: "ubuntu-26.04" },
-    check: "command -v nginx >/dev/null && systemctl is-active --quiet nginx",
-    install: "DEBIAN_FRONTEND=noninteractive apt-get update -qq && apt-get install -y nginx && systemctl enable --now nginx"
-  },
-  {
-    requirement: { id: "arangodb", version: "3.11.14" },
-    check: `arangod --version 2>/dev/null | head -1 | grep -q '3.11.14' && ` + `! systemctl is-active --quiet arangodb3.service && ` + `! systemctl is-enabled --quiet arangodb3.service`,
-    install: `tmp=$(mktemp -d); trap 'rm -rf "$tmp"' EXIT; ` + `curl -fsSL 'https://download.arangodb.com/arangodb311/DEBIAN/amd64/arangodb3_3.11.14-1_amd64.deb' -o "$tmp/arangodb.deb"; ` + `echo "${ARANGO_SHA256}  $tmp/arangodb.deb" | sha256sum -c -; ` + `DEBIAN_FRONTEND=noninteractive dpkg -i "$tmp/arangodb.deb" >/dev/null 2>&1 || ` + `DEBIAN_FRONTEND=noninteractive apt-get -y -f install; ` + `systemctl disable --now arangodb3.service`
-  },
-  {
-    requirement: { id: "cloudflared", version: "2026.7.3" },
-    check: `cloudflared --version 2>/dev/null | grep -q '2026.7.3'`,
-    install: `tmp=$(mktemp -d); trap 'rm -rf "$tmp"' EXIT; ` + `curl -fsSL 'https://github.com/cloudflare/cloudflared/releases/download/2026.7.3/cloudflared-linux-amd64' -o "$tmp/cloudflared"; ` + `echo "${CLOUDFLARED_SHA256}  $tmp/cloudflared" | sha256sum -c -; ` + `install -m 0755 "$tmp/cloudflared" /usr/local/bin/cloudflared`
-  },
-  {
-    requirement: { id: "ufw", version: "ubuntu-26.04" },
-    check: "command -v ufw >/dev/null",
-    install: "DEBIAN_FRONTEND=noninteractive apt-get update -qq && apt-get install -y ufw"
-  },
-  {
-    requirement: { id: "openssh-client", version: "ubuntu-26.04" },
-    check: "command -v ssh >/dev/null && command -v scp >/dev/null && command -v ssh-keyscan >/dev/null && command -v ssh-keygen >/dev/null",
-    install: "DEBIAN_FRONTEND=noninteractive apt-get update -qq && apt-get install -y openssh-client"
-  }
+  { requirement: { id: "bun", version: "1.3.14" } },
+  { requirement: { id: "nginx", version: "ubuntu-26.04" } },
+  { requirement: { id: "arangodb", version: "3.11.14" } },
+  { requirement: { id: "cloudflared", version: "2026.7.3" } },
+  { requirement: { id: "cloudflare-warp", version: "2026.6.822.0-min" } },
+  { requirement: { id: "ufw", version: "ubuntu-26.04" } },
+  { requirement: { id: "openssh-client", version: "ubuntu-26.04" } }
 ];
+var path = "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin";
+var run = async (argv, env = {}) => {
+  const child = Bun.spawn([...argv], { stdout: "pipe", stderr: "pipe", env: { PATH: path, LANG: "C", LC_ALL: "C", ...env } });
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(child.stdout).text(),
+    new Response(child.stderr).text(),
+    child.exited
+  ]);
+  return { exitCode, output: `${stdout}${stderr}` };
+};
+var download = async (url, destination, sha256) => {
+  const response = await fetch(url, { redirect: "follow", signal: AbortSignal.timeout(120000) });
+  if (!response.ok)
+    throw new Error(`download failed with HTTP ${response.status}`);
+  const bytes = new Uint8Array(await response.arrayBuffer());
+  if (createHash("sha256").update(bytes).digest("hex") !== sha256)
+    throw new Error("download checksum mismatch");
+  writeFileSync(destination, bytes, { mode: 384, flag: "wx" });
+};
+var successful = (result, pattern) => result.exitCode === 0 && (!pattern || pattern.test(result.output));
+var aptInstall = async (name) => {
+  const environment = { DEBIAN_FRONTEND: "noninteractive" };
+  const update = await run(["/usr/bin/apt-get", "update", "-qq"], environment);
+  return update.exitCode === 0 ? run(["/usr/bin/apt-get", "install", "-y", name], environment) : update;
+};
+async function executeSoftwareOperation(operation) {
+  const { software, version } = operation;
+  if (!UBUNTU_2604_X64.some(({ requirement }) => requirement.id === software && requirement.version === version)) {
+    return { exitCode: 2, output: "unsupported software operation" };
+  }
+  if (operation.kind === "check") {
+    if (software === "bun")
+      return run(["/usr/local/bin/bun", "--version"]).then((r) => ({ ...r, exitCode: successful(r, /^1\.3\.14\s*$/m) ? 0 : 1 }));
+    if (software === "nginx") {
+      const binary = await run(["/usr/sbin/nginx", "-v"]);
+      return binary.exitCode === 0 ? run(["/usr/bin/systemctl", "is-active", "--quiet", "nginx.service"]) : binary;
+    }
+    if (software === "arangodb") {
+      const binary = await run(["/usr/bin/arangod", "--version"]);
+      if (!successful(binary, /3\.11\.14/))
+        return { ...binary, exitCode: 1 };
+      const [active, enabled] = await Promise.all([
+        run(["/usr/bin/systemctl", "is-active", "--quiet", "arangodb3.service"]),
+        run(["/usr/bin/systemctl", "is-enabled", "--quiet", "arangodb3.service"])
+      ]);
+      return active.exitCode !== 0 && enabled.exitCode !== 0 ? { exitCode: 0, output: binary.output } : { exitCode: 1, output: "vendor standalone unit remains active or enabled" };
+    }
+    if (software === "cloudflared")
+      return run(["/usr/local/bin/cloudflared", "--version"]).then((r) => ({ ...r, exitCode: successful(r, /2026\.7\.3/) ? 0 : 1 }));
+    if (software === "cloudflare-warp")
+      return run(["/usr/bin/warp-cli", "--version"]).then((result) => {
+        const match = result.output.match(/(\d{4})\.(\d+)\.(\d+)\.(\d+)/);
+        const observed = match?.slice(1).map(Number);
+        const minimum = [2026, 6, 822, 0];
+        const supported = observed && observed.some((part, index) => part > minimum[index] && observed.slice(0, index).every((prior, priorIndex) => prior === minimum[priorIndex])) || observed?.every((part, index) => part === minimum[index]);
+        return { ...result, exitCode: result.exitCode === 0 && supported ? 0 : 1 };
+      });
+    const binaries = software === "ufw" ? ["/usr/sbin/ufw"] : ["/usr/bin/ssh", "/usr/bin/scp", "/usr/bin/ssh-keyscan", "/usr/bin/ssh-keygen"];
+    try {
+      binaries.forEach((binary) => accessSync(binary));
+      return { exitCode: 0, output: "" };
+    } catch (cause) {
+      return { exitCode: 1, output: cause instanceof Error ? cause.message : String(cause) };
+    }
+  }
+  if (software === "nginx" || software === "ufw" || software === "openssh-client") {
+    const installed = await aptInstall(software === "openssh-client" ? "openssh-client" : software);
+    if (installed.exitCode !== 0 || software !== "nginx")
+      return installed;
+    return run(["/usr/bin/systemctl", "enable", "--now", "nginx.service"]);
+  }
+  const directory = mkdtempSync(join(tmpdir(), "forgezero-software-"));
+  try {
+    if (software === "cloudflare-warp") {
+      const key = join(directory, "cloudflare-warp-key.gpg");
+      await download("https://pkg.cloudflareclient.com/pubkey.gpg", key, "0f37fc298c98e88ee3c0ee68c95b69f1dba9eb477abe3167e13982105911264d");
+      mkdirSync("/usr/share/keyrings", { recursive: true, mode: 493 });
+      const dearmored = await run([
+        "/usr/bin/gpg",
+        "--batch",
+        "--yes",
+        "--dearmor",
+        "-o",
+        "/usr/share/keyrings/cloudflare-warp-archive-keyring.gpg",
+        key
+      ]);
+      if (dearmored.exitCode !== 0)
+        return dearmored;
+      mkdirSync("/etc/apt/sources.list.d", { recursive: true, mode: 493 });
+      writeFileSync("/etc/apt/sources.list.d/cloudflare-client.list", `deb [signed-by=/usr/share/keyrings/cloudflare-warp-archive-keyring.gpg] https://pkg.cloudflareclient.com/ resolute main
+`, { mode: 420 });
+      return aptInstall("cloudflare-warp");
+    }
+    if (software === "bun") {
+      const archive = join(directory, "bun.zip");
+      await download("https://github.com/oven-sh/bun/releases/download/bun-v1.3.14/bun-linux-x64.zip", archive, BUN_RELEASE_SHA256);
+      const unpacked = join(directory, "unpacked");
+      mkdirSync(unpacked, { mode: 448 });
+      const unzipped = await run(["/usr/bin/unzip", "-q", archive, "-d", unpacked]);
+      if (unzipped.exitCode !== 0)
+        return unzipped;
+      mkdirSync("/usr/local/lib/forgezero/runtime", { recursive: true, mode: 493 });
+      copyFileSync(join(unpacked, "bun-linux-x64", "bun"), "/usr/local/lib/forgezero/runtime/bun.next");
+      chmodSync("/usr/local/lib/forgezero/runtime/bun.next", 493);
+      renameSync("/usr/local/lib/forgezero/runtime/bun.next", "/usr/local/lib/forgezero/runtime/bun");
+      try {
+        unlinkSync("/usr/local/bin/bun");
+      } catch {}
+      symlinkSync("/usr/local/lib/forgezero/runtime/bun", "/usr/local/bin/bun");
+      return { exitCode: 0, output: "" };
+    }
+    if (software === "cloudflared") {
+      const binary = join(directory, "cloudflared");
+      await download("https://github.com/cloudflare/cloudflared/releases/download/2026.7.3/cloudflared-linux-amd64", binary, CLOUDFLARED_SHA256);
+      chmodSync(binary, 493);
+      copyFileSync(binary, "/usr/local/bin/cloudflared");
+      chmodSync("/usr/local/bin/cloudflared", 493);
+      return { exitCode: 0, output: "" };
+    }
+    const deb = join(directory, "arangodb.deb");
+    await download("https://download.arangodb.com/arangodb311/DEBIAN/amd64/arangodb3_3.11.14-1_amd64.deb", deb, ARANGO_SHA256);
+    let installed = await run(["/usr/bin/dpkg", "-i", deb], { DEBIAN_FRONTEND: "noninteractive" });
+    if (installed.exitCode !== 0)
+      installed = await run(["/usr/bin/apt-get", "-y", "-f", "install"], { DEBIAN_FRONTEND: "noninteractive" });
+    if (installed.exitCode !== 0)
+      return installed;
+    await run(["/usr/bin/systemctl", "disable", "--now", "arangodb3.service"]);
+    return { exitCode: 0, output: "" };
+  } finally {
+    rmSync(directory, { recursive: true, force: true });
+  }
+}
 function observeSoftwareHost(osRelease = readFileSync("/etc/os-release", "utf8"), architecture = process.arch) {
   const values = Object.fromEntries(osRelease.split(`
 `).flatMap((line) => {
@@ -69,7 +194,7 @@ function validateSoftwareRequirements(value, _options = {}) {
     if (Object.keys(row).some((key) => key !== "id" && key !== "version")) {
       throw new Error("software requirement contains an unknown field");
     }
-    if (!["bun", "nginx", "arangodb", "cloudflared", "ufw", "openssh-client"].includes(String(row.id)) || typeof row.version !== "string" || !/^[A-Za-z0-9][A-Za-z0-9.-]{0,31}$/.test(row.version)) {
+    if (!["bun", "nginx", "arangodb", "cloudflared", "cloudflare-warp", "ufw", "openssh-client"].includes(String(row.id)) || typeof row.version !== "string" || !/^[A-Za-z0-9][A-Za-z0-9.-]{0,31}$/.test(row.version)) {
       throw new Error("software requirement coordinate is invalid");
     }
     const requirement = { id: row.id, version: row.version };
@@ -95,15 +220,15 @@ async function ensureSoftwareRequirements(requirementsInput, options) {
     const strategy = UBUNTU_2604_X64.find(({ requirement: candidate }) => candidate.id === requirement.id && candidate.version === requirement.version);
     if (!strategy)
       throw new Error(`unsupported software requirement: ${requirement.id}@${requirement.version}`);
-    const before = await options.exec(strategy.check);
+    const before = await options.exec({ kind: "check", software: requirement.id, version: requirement.version });
     if (before.exitCode === 0) {
       results.push({ ...requirement, changed: false });
       continue;
     }
-    const installed = await options.exec(strategy.install);
+    const installed = await options.exec({ kind: "install", software: requirement.id, version: requirement.version });
     if (installed.exitCode !== 0)
       throw new Error(`could not install ${requirement.id}@${requirement.version}: ${installed.output.trim()}`);
-    const after = await options.exec(strategy.check);
+    const after = await options.exec({ kind: "check", software: requirement.id, version: requirement.version });
     if (after.exitCode !== 0)
       throw new Error(`${requirement.id}@${requirement.version} did not pass its post-install check`);
     results.push({ ...requirement, changed: true });
@@ -227,8 +352,8 @@ async function calibrateHttpConcurrency(options, fetcher = fetch) {
 }
 
 // src/definition.ts
-var PIPELINE_VERSION = 2;
-var DEPLOY_SCHEMA_URL = "https://www.forgezero.net/schemas/deploy-v2.json";
+var PIPELINE_VERSION = 3;
+var DEPLOY_SCHEMA_URL = "https://www.forgezero.net/schemas/deploy-v3.json";
 
 class DefinitionError extends Error {
   constructor(message) {
@@ -248,6 +373,29 @@ var text = (value, where) => {
   }
   return value;
 };
+var argv = (value, where) => {
+  if (!Array.isArray(value) || value.length === 0 || value.length > 256) {
+    throw new DefinitionError(`${where} must contain from 1 to 256 arguments.`);
+  }
+  let bytes = 0;
+  const parsed = value.map((argument, index) => {
+    if (typeof argument !== "string" || argument.length === 0 || argument.length > 16384 || argument.includes("\x00")) {
+      throw new DefinitionError(`${where}[${index}] must be a non-empty bounded string without NUL.`);
+    }
+    if (argument.includes("${") && !/^\$\{FZ_[A-Z0-9_]+\}$/.test(argument)) {
+      throw new DefinitionError(`${where}[${index}] contains unsupported interpolation; only one exact FZ coordinate is allowed.`);
+    }
+    bytes += Buffer.byteLength(argument);
+    if (bytes > 64 * 1024)
+      throw new DefinitionError(`${where} is larger than 64 KiB.`);
+    return argument;
+  });
+  const executable = parsed[0].split("/").at(-1).toLowerCase();
+  if (new Set(["sh", "bash", "dash", "zsh", "ksh", "fish", "busybox", "env"]).has(executable)) {
+    throw new DefinitionError(`${where}[0] may not invoke a shell or command dispatcher.`);
+  }
+  return parsed;
+};
 var exactKeys = (value, allowed, where) => {
   const unknown = Object.keys(value).filter((key) => !allowed.includes(key));
   if (unknown.length > 0)
@@ -313,6 +461,76 @@ function capacityCalibration(value, where) {
   }
   return parsed;
 }
+function validateDeploymentService(value, where = "service") {
+  const service = record(value, where);
+  exactKeys(service, [
+    "strategy",
+    "publicPort",
+    "applicationPorts",
+    "command",
+    "healthPath",
+    "maxConnections",
+    "websocket",
+    "drainMs"
+  ], where);
+  if (service.strategy !== "direct" && service.strategy !== "blue-green") {
+    throw new DefinitionError(`${where}.strategy must be direct or blue-green.`);
+  }
+  const publicPort = Number(service.publicPort);
+  if (!Number.isSafeInteger(publicPort) || publicPort < 1024 || publicPort > 65535) {
+    throw new DefinitionError(`${where}.publicPort must be an unprivileged TCP port.`);
+  }
+  const allocation = record(service.applicationPorts, `${where}.applicationPorts`);
+  let applicationPorts;
+  const required = service.strategy === "blue-green" ? 2 : 1;
+  if (allocation.mode === "fixed") {
+    exactKeys(allocation, ["mode", "ports"], `${where}.applicationPorts`);
+    if (!Array.isArray(allocation.ports) || allocation.ports.length !== required || allocation.ports.some((port) => !Number.isSafeInteger(port) || Number(port) < 1024 || Number(port) > 65535) || new Set(allocation.ports).size !== allocation.ports.length || allocation.ports.includes(publicPort)) {
+      throw new DefinitionError(`${where}.applicationPorts needs ${required} distinct unprivileged port(s), disjoint from publicPort.`);
+    }
+    applicationPorts = { mode: "fixed", ports: allocation.ports };
+  } else if (allocation.mode === "dynamic") {
+    exactKeys(allocation, ["mode", "from", "to"], `${where}.applicationPorts`);
+    const from = Number(allocation.from);
+    const to = Number(allocation.to);
+    if (!Number.isSafeInteger(from) || !Number.isSafeInteger(to) || from < 1024 || to > 65535 || to - from + 1 < required || publicPort >= from && publicPort <= to) {
+      throw new DefinitionError(`${where}.applicationPorts dynamic range is invalid or includes publicPort.`);
+    }
+    applicationPorts = { mode: "dynamic", from, to };
+  } else
+    throw new DefinitionError(`${where}.applicationPorts.mode must be fixed or dynamic.`);
+  const command = argv(service.command, `${where}.command`);
+  for (const argument of command) {
+    const coordinate = argument.match(/^\$\{(FZ_[A-Z0-9_]+)\}$/)?.[1];
+    if (coordinate && !["FZ_APP_PORT", "FZ_RELEASE"].includes(coordinate)) {
+      throw new DefinitionError(`${where}.command uses unsupported coordinate ${coordinate}.`);
+    }
+  }
+  if (typeof service.healthPath !== "string" || !/^\/[A-Za-z0-9._~!$&'()*+,;=:@%/-]{0,255}$/.test(service.healthPath) || service.healthPath.includes("..") || service.healthPath.includes("//")) {
+    throw new DefinitionError(`${where}.healthPath must be one bounded absolute path.`);
+  }
+  if (service.websocket !== undefined && typeof service.websocket !== "boolean") {
+    throw new DefinitionError(`${where}.websocket must be a boolean.`);
+  }
+  const maxConnections = service.maxConnections === undefined ? undefined : Number(service.maxConnections);
+  if (maxConnections !== undefined && (!Number.isSafeInteger(maxConnections) || maxConnections < 1 || maxConnections > 1e6)) {
+    throw new DefinitionError(`${where}.maxConnections must be from 1 to 1000000.`);
+  }
+  const drainMs = service.drainMs === undefined ? 30000 : Number(service.drainMs);
+  if (!Number.isSafeInteger(drainMs) || drainMs < 0 || drainMs > 300000) {
+    throw new DefinitionError(`${where}.drainMs must be from 0 to 300000.`);
+  }
+  return {
+    strategy: service.strategy,
+    publicPort,
+    applicationPorts,
+    command,
+    healthPath: service.healthPath,
+    ...maxConnections === undefined ? {} : { maxConnections },
+    websocket: service.websocket === true,
+    drainMs
+  };
+}
 function parseDeployDefinition(value, options = {}) {
   const root = record(value, "pipeline");
   exactKeys(root, ["$schema", "version", "name", "requireAttestation", "profiles", "steps"], "pipeline");
@@ -330,20 +548,28 @@ function parseDeployDefinition(value, options = {}) {
   if (profileEntries.length === 0 || profileEntries.length > 32) {
     throw new DefinitionError("pipeline.profiles must contain from 1 to 32 named profiles.");
   }
-  if (!Array.isArray(root.steps) || root.steps.length === 0) {
-    throw new DefinitionError("pipeline.steps must contain at least one step.");
+  if (!Array.isArray(root.steps) || root.steps.length === 0 || root.steps.length > 256) {
+    throw new DefinitionError("pipeline.steps must contain from 1 to 256 steps.");
   }
   const profiles = {};
   for (const [name2, raw] of profileEntries) {
     if (!NAME.test(name2))
       throw new DefinitionError(`pipeline profile name is invalid: ${name2}.`);
     const profile = record(raw, `profiles.${name2}`);
-    exactKeys(profile, ["software", "capacityCalibration"], `profiles.${name2}`);
+    exactKeys(profile, ["software", "service", "capacityCalibration"], `profiles.${name2}`);
     if (!Array.isArray(profile.software)) {
       throw new DefinitionError(`profiles.${name2}.software must be an array.`);
     }
+    const software = validateSoftwareRequirements(profile.software, options);
+    const service = profile.service === undefined ? undefined : validateDeploymentService(profile.service, `profiles.${name2}.service`);
+    if (service && !software.some(({ id }) => id === "nginx")) {
+      throw new DefinitionError(`profiles.${name2}.service requires the reviewed nginx software strategy.`);
+    }
     profiles[name2] = {
-      software: validateSoftwareRequirements(profile.software, options),
+      software,
+      ...profile.service === undefined ? {} : {
+        service
+      },
       ...profile.capacityCalibration === undefined ? {} : {
         capacityCalibration: capacityCalibration(profile.capacityCalibration, `profiles.${name2}.capacityCalibration`)
       }
@@ -352,7 +578,7 @@ function parseDeployDefinition(value, options = {}) {
   const phases = new Set(["build", "release", "migrate", "health"]);
   const steps = root.steps.map((raw, index) => {
     const step = record(raw, `steps[${index}]`);
-    exactKeys(step, ["name", "run", "phase", "scope", "profiles", "secrets", "always", "timeoutMs", "when"], `steps[${index}]`);
+    exactKeys(step, ["name", "exec", "phase", "scope", "profiles", "secrets", "always", "timeoutMs", "when"], `steps[${index}]`);
     const phase = text(step.phase, `steps[${index}].phase`);
     if (!phases.has(phase))
       throw new DefinitionError(`steps[${index}].phase is not supported.`);
@@ -400,7 +626,7 @@ function parseDeployDefinition(value, options = {}) {
     }
     return {
       name: text(step.name, `steps[${index}].name`),
-      run: text(step.run, `steps[${index}].run`),
+      exec: argv(step.exec, `steps[${index}].exec`),
       phase,
       scope: step.scope,
       profiles: selectedProfiles,
@@ -440,6 +666,7 @@ function phasePipeline(definition, phase, profile, executeRelease = false) {
   };
 }
 export {
+  validateDeploymentService,
   phasePipeline,
   parseDeployDefinition,
   PIPELINE_VERSION,