@forgezero/agent 0.1.0 → 0.1.9

package/dist/metal-provision.js

@@ -0,0 +1,1014 @@
+// src/compute.ts
+class ComputeError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "ComputeError";
+  }
+}
+var NAME = /^[a-z][a-z0-9-]{1,30}[a-z0-9]$/;
+var unitName = (name) => {
+  if (!NAME.test(name)) {
+    throw new ComputeError("BAD_NAME", `"${name}" is not a usable guest name — lower case, digits and hyphens, 3-32 characters.`);
+  }
+  return `forgezero-guest@${name}.service`;
+};
+function qemuArgv(spec) {
+  if (spec.vcpu < 1 || spec.memoryGib < 1) {
+    throw new ComputeError("BAD_SPEC", "a guest needs at least 1 vCPU and 1 GiB");
+  }
+  const argv = [
+    "/usr/bin/qemu-system-x86_64",
+    "-name",
+    spec.name,
+    "-accel",
+    "kvm",
+    "-cpu",
+    "host",
+    "-m",
+    `${spec.memoryGib}G`,
+    "-smp",
+    String(spec.vcpu)
+  ];
+  if (spec.confidential) {
+    const { cbitpos, reducedPhysBits, policy } = spec.confidential;
+    argv.push("-machine", `q35,confidential-guest-support=snp,memory-backend=ram`, "-object", `memory-backend-memfd,id=ram,size=${spec.memoryGib}G,share=true`, "-object", `sev-snp-guest,id=snp,cbitpos=${cbitpos},reduced-phys-bits=${reducedPhysBits},policy=${policy}`, "-bios", "/usr/share/ovmf/OVMF.fd");
+  } else {
+    argv.push("-machine", "q35");
+  }
+  argv.push("-drive", `file=${spec.disk},format=raw,if=none,id=disk0,cache=none,aio=native`, "-device", "virtio-blk-pci,drive=disk0,iommu_platform=on", "-drive", `file=${spec.seed},format=raw,if=none,id=seed0,readonly=on`, "-device", "virtio-blk-pci,drive=seed0,iommu_platform=on", "-netdev", spec.tap ? `tap,id=net0,ifname=${spec.tap},script=no,downscript=no` : `bridge,id=net0,br=${spec.bridge}`, "-device", `virtio-net-pci,netdev=net0,mac=${spec.mac},iommu_platform=on`, "-display", "none");
+  if (spec.consoleLog)
+    argv.push("-serial", `file:${spec.consoleLog}`);
+  return argv;
+}
+function guestUnit(spec) {
+  const argv = qemuArgv(spec).map((part) => /[\s"']/.test(part) ? JSON.stringify(part) : part).join(" ");
+  if (spec.egress && !spec.tap) {
+    throw new ComputeError("BAD_SPEC", "shaped egress needs a stable tap device");
+  }
+  const tapSetup = spec.tap ? [
+    `ExecStartPre=-/usr/sbin/ip link del ${spec.tap}`,
+    `ExecStartPre=/usr/sbin/ip tuntap add dev ${spec.tap} mode tap`,
+    `ExecStartPre=/usr/sbin/ip link set ${spec.tap} master ${spec.bridge}`,
+    `ExecStartPre=/usr/sbin/ip link set ${spec.tap} up`,
+    ...spec.egress ? shapeEgressUnitDirectives(spec.tap, spec.egress.guaranteedMbps, spec.egress.burstMbps) : [],
+    `ExecStopPost=-/usr/sbin/ip link del ${spec.tap}`
+  ].join(`
+`) : "";
+  return `[Unit]
+Description=ForgeZero guest ${spec.name}
+Documentation=https://www.forgezero.net
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+Slice=forgezero-guests.slice
+${tapSetup}
+ExecStart=${argv}
+Restart=always
+RestartSec=5
+${spec.allowedCpus ? `AllowedCPUs=${spec.allowedCpus}
+` : ""}${spec.allowedMemoryNodes ? `AllowedMemoryNodes=${spec.allowedMemoryNodes}
+` : ""}# The affinity belongs to the unit rather than only QEMU's vCPU threads. Its
+# emulator and IO threads can otherwise run on a different tenant's cores.
+# The agent is NOT the parent. Restarting or upgrading fz-agent must never stop
+# a tenant's compute, which is the whole reason this is a unit rather than a
+# child process.
+KillMode=mixed
+TimeoutStopSec=120
+
+[Install]
+WantedBy=multi-user.target
+`;
+}
+function parseCensus(psOutput) {
+  const guests = [];
+  for (const line of psOutput.split(`
+`)) {
+    const trimmed = line.trim();
+    if (!trimmed || !trimmed.includes("qemu-system"))
+      continue;
+    const pid = Number(trimmed.split(/\s+/)[0]);
+    const name = /-name\s+([^\s]+)/.exec(trimmed)?.[1];
+    if (!Number.isFinite(pid) || !name)
+      continue;
+    const disks = [...trimmed.matchAll(/file=([^,\s]+)/g)].map((match) => match[1]);
+    guests.push({ name, pid, disks });
+  }
+  return guests;
+}
+var deviceInUse = (census, device) => census.some((guest) => guest.disks.includes(device));
+function shapeEgressCommands(tap, mbps, burstMbps = mbps * 2) {
+  if (!/^[a-z][a-z0-9]{0,14}$/.test(tap)) {
+    throw new ComputeError("BAD_SPEC", `"${tap}" is not a device name`);
+  }
+  if (mbps <= 0)
+    return [
+      `tc qdisc del dev ${tap} root 2>/dev/null || true`,
+      `tc qdisc del dev ${tap} ingress 2>/dev/null || true`
+    ];
+  const ceiling = `${Math.floor(Math.max(burstMbps, mbps))}mbit`;
+  return [
+    `tc qdisc del dev ${tap} root 2>/dev/null || true`,
+    `tc qdisc del dev ${tap} ingress 2>/dev/null || true`,
+    `tc qdisc add dev ${tap} handle ffff: ingress`,
+    `tc filter add dev ${tap} parent ffff: protocol all u32 match u32 0 0 action police rate ${ceiling} burst 16mb conform-exceed drop`
+  ];
+}
+function shapeEgressUnitDirectives(tap, guaranteedMbps, burstMbps) {
+  if (!/^[a-z][a-z0-9]{0,14}$/.test(tap)) {
+    throw new ComputeError("BAD_SPEC", `"${tap}" is not a device name`);
+  }
+  if (!Number.isInteger(guaranteedMbps) || guaranteedMbps < 0 || !Number.isInteger(burstMbps) || burstMbps < guaranteedMbps) {
+    throw new ComputeError("BAD_SPEC", "egress rates must be whole numbers and burst must cover the guarantee");
+  }
+  const clear = [
+    `ExecStartPre=-/usr/sbin/tc qdisc del dev ${tap} root`,
+    `ExecStartPre=-/usr/sbin/tc qdisc del dev ${tap} ingress`
+  ];
+  if (guaranteedMbps === 0)
+    return clear;
+  return [
+    ...clear,
+    `ExecStartPre=/usr/sbin/tc qdisc add dev ${tap} handle ffff: ingress`,
+    `ExecStartPre=/usr/sbin/tc filter add dev ${tap} parent ffff: protocol all u32 match u32 0 0 action police rate ${burstMbps}mbit burst 16mb conform-exceed drop`
+  ];
+}
+var tapFor = (guestIndex) => `tap${guestIndex}`;
+
+// src/provision.ts
+function atLeast(version, floor) {
+  const parse = (value) => (value.trim().replace(/^v/, "").match(/\d+/g) ?? []).slice(0, 3).map(Number);
+  const got = parse(version);
+  const want = parse(floor);
+  if (got.length === 0)
+    return false;
+  for (let index = 0;index < want.length; index += 1) {
+    const a = got[index] ?? 0;
+    const b = want[index] ?? 0;
+    if (a > b)
+      return true;
+    if (a < b)
+      return false;
+  }
+  return true;
+}
+var CAPABILITY_CHECKS = {
+  snpGuest: {
+    command: "test -e /dev/sev-guest && echo yes || echo no",
+    satisfied: (stdout) => stdout.trim() === "yes",
+    remedy: "Not a confidential guest. The agent will run in `enrolled` mode, which is still stronger than an API key in the application."
+  },
+  systemd: {
+    command: "test -d /run/systemd/system && echo yes || echo no",
+    satisfied: (stdout) => stdout.trim() === "yes",
+    remedy: "systemd is what supervises the agent. On a non-systemd host, run `fz-agent` under whatever supervises services there."
+  },
+  bun: {
+    command: "bun --version 2>/dev/null || echo missing",
+    satisfied: (stdout) => atLeast(stdout, "1.1.0"),
+    remedy: "Install bun: curl -fsSL https://bun.sh/install | bash"
+  },
+  python: {
+    command: "python3 --version 2>/dev/null || echo missing",
+    satisfied: (stdout, exitCode) => exitCode === 0 && /^Python 3\./.test(stdout.trim()),
+    remedy: "Install Python 3. It supplies the standard-library ioctl boundary for SNP reports."
+  }
+};
+var modeFor = (capabilities) => capabilities.snpGuest ? "attested" : "enrolled";
+var reasonFor = (mode) => mode === "attested" ? "SEV-SNP guest device present, so the agent can prove what it is running and the platform can refuse it if the measurement is wrong." : "No SEV-SNP guest device. The agent authenticates with its enrolment token and hybrid Ed25519 + ML-DSA signature — weaker than attestation, stronger than an API key in the application.";
+var DEPLOYMENT_RUNNER_USER = "forgezero-runner";
+var DEPLOYMENT_GROUP = "forgezero-deploy";
+var DEPLOYMENT_RUNNER_UNIT_PATH = "/etc/systemd/system/forgezero-deploy-runner.service";
+var DEPLOYMENT_RUNNER_SOCKET_UNIT_PATH = "/etc/systemd/system/forgezero-deploy-runner.socket";
+var DEPLOYMENT_RUNNER_SOCKET = "/run/forgezero-deploy/runner.sock";
+var ENROLMENT_UNIT_PATH = "/etc/systemd/system/forgezero-agent-enrol.service";
+function agentEnrolmentUnit(options) {
+  if (!options.apiUrl || !options.enrolTokenCredentialPath || !options.enrolStatePath) {
+    throw new Error("direct enrolment needs API, credential and state paths");
+  }
+  const bin = options.binPath ?? "fz-agent";
+  const user = options.user ?? "forgezero";
+  const seedCredentialPath = options.seedCredentialPath ?? "/etc/forgezero/creds/agent-seed.cred";
+  const label = options.nodeLabel ? `Environment=FZ_NODE_LABEL=${options.nodeLabel}
+` : "";
+  const gitPublicKey = options.gitPublicKeyPath ? `Environment=FZ_GIT_PUBLIC_KEY_FILE=${options.gitPublicKeyPath}
+` : "";
+  const stateDir = options.enrolStatePath.replace(/\/[^/]+$/, "");
+  return `[Unit]
+Description=Bind this machine to its ForgeZero compute
+After=network-online.target
+Wants=network-online.target
+Before=forgezero-agent.service
+ConditionPathExists=!${options.enrolStatePath}
+
+[Service]
+Type=oneshot
+User=${user}
+Group=${user}
+LoadCredentialEncrypted=agent-seed:${seedCredentialPath}
+LoadCredentialEncrypted=enrol-token:${options.enrolTokenCredentialPath}
+Environment=FZ_SEED_CREDENTIAL=agent-seed
+Environment=FZ_ENROL_TOKEN_CREDENTIAL=enrol-token
+Environment=FZ_ENROL_STATE_FILE=${options.enrolStatePath}
+Environment=FZ_API=${options.apiUrl}
+${label}${gitPublicKey}ExecStart=${bin} enrol
+# A '+' fixed command runs as root solely to remove the host-bound one-time
+# ciphertext. Tenant code and the agent never receive a privilege boundary.
+ExecStartPost=+/usr/bin/rm -f ${options.enrolTokenCredentialPath}
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=strict
+ProtectHome=true
+ReadWritePaths=${stateDir}
+LimitCORE=0
+
+[Install]
+WantedBy=multi-user.target
+`;
+}
+function deploymentRunnerSocketUnit(agentUser) {
+  return `[Unit]
+Description=ForgeZero private project-command socket
+
+[Socket]
+ListenStream=${DEPLOYMENT_RUNNER_SOCKET}
+SocketUser=${agentUser}
+SocketGroup=${agentUser}
+SocketMode=0600
+DirectoryMode=0710
+RemoveOnStop=true
+
+[Install]
+WantedBy=sockets.target
+`;
+}
+function deploymentRunnerUnit(options) {
+  const bin = options.binPath ?? "fz-agent";
+  const root = options.deployRoot ?? "/opt/forgezero";
+  return `[Unit]
+Description=ForgeZero credential-free project command runner
+Documentation=https://www.forgezero.net/docs/agent
+After=forgezero-deploy-runner.socket
+Requires=forgezero-deploy-runner.socket
+
+[Service]
+Type=simple
+User=${DEPLOYMENT_RUNNER_USER}
+Group=${DEPLOYMENT_GROUP}
+Environment=FZ_DEPLOY_RUNNER_SOCKET=${DEPLOYMENT_RUNNER_SOCKET}
+Sockets=forgezero-deploy-runner.socket
+ExecStart=${bin} deploy-runner --root=${root} --home=${root}/runner-home
+Restart=always
+RestartSec=2
+UMask=0007
+LimitCORE=0
+NoNewPrivileges=false
+PrivateTmp=true
+ProtectSystem=strict
+ProtectHome=true
+ProtectKernelTunables=true
+ProtectKernelModules=true
+ProtectControlGroups=true
+RestrictRealtime=true
+MemoryDenyWriteExecute=true
+LockPersonality=true
+ReadWritePaths=${root}/releases ${root}/runner-home
+
+[Install]
+WantedBy=multi-user.target
+`;
+}
+function agentUnit(options) {
+  const bin = options.binPath ?? "fz-agent";
+  const user = options.user ?? "forgezero";
+  const seedCredentialPath = options.seedCredentialPath ?? "/etc/forgezero/creds/agent-seed.cred";
+  const controlSocketPath = options.controlSocketPath ?? "/run/forgezero/control.sock";
+  const deployRoot = options.deployRoot ?? "/opt/forgezero";
+  const deploymentEnabled = Boolean(options.repository || options.pullDeployments);
+  const enrolmentEnabled = Boolean(options.enrolTokenCredentialPath && options.enrolStatePath);
+  const deploymentEnvironment = options.deploymentEnvironment ?? {};
+  const deploymentCredentials = options.deploymentCredentials ?? {};
+  for (const [name, value] of Object.entries(deploymentEnvironment)) {
+    if (!/^[A-Z_][A-Z0-9_]*$/.test(name) || !/^[A-Za-z0-9._:\/@+-]+$/.test(value)) {
+      throw new Error(`invalid deployment environment entry: ${name}`);
+    }
+  }
+  for (const [name, path] of Object.entries(deploymentCredentials)) {
+    if (!/^[A-Z_][A-Z0-9_]*$/.test(name) || !path.startsWith("/") || /[\r\n:]/.test(path)) {
+      throw new Error(`invalid deployment credential entry: ${name}`);
+    }
+  }
+  const environment = [
+    `FZ_SOCKET_PATH=${options.socketPath}`,
+    `FZ_CONTROL_SOCKET=${controlSocketPath}`,
+    `FZ_SEED_CREDENTIAL=agent-seed`,
+    `FZ_AGENT_MODE=${options.mode}`,
+    options.apiUrl ? `FZ_API=${options.apiUrl}` : null,
+    options.project ? `FZ_PROJECT=${options.project}` : null,
+    options.environment ? `FZ_ENVIRONMENT=${options.environment}` : null,
+    options.enrolStatePath ? `FZ_ENROL_STATE_FILE=${options.enrolStatePath}` : null,
+    options.nodeLabel ? `FZ_NODE_LABEL=${options.nodeLabel}` : null,
+    options.gitPublicKeyPath ? `FZ_GIT_PUBLIC_KEY_FILE=${options.gitPublicKeyPath}` : null,
+    options.repository ? `FZ_DEPLOY_REPO=${options.repository}` : null,
+    options.branch ? `FZ_DEPLOY_BRANCH=${options.branch}` : null,
+    options.role ? `FZ_DEPLOY_ROLE=${options.role}` : null,
+    options.repository && options.branch ? `FZ_DEPLOY_KEY=${options.project ?? "platform"}:${options.environment ?? "production"}` : null,
+    deploymentEnabled ? `FZ_DEPLOY_ROOT=${deployRoot}` : null,
+    deploymentEnabled ? `FZ_DEPLOY_RUNNER_SOCKET=${DEPLOYMENT_RUNNER_SOCKET}` : null,
+    Object.keys(deploymentCredentials).length > 0 ? `FZ_DEPLOY_SYSTEMD_SECRETS=${Object.keys(deploymentCredentials).join(",")}` : null,
+    Object.keys(deploymentEnvironment).length > 0 ? `FZ_DEPLOY_ENV_NAMES=${Object.keys(deploymentEnvironment).join(",")}` : null,
+    ...Object.entries(deploymentEnvironment).map(([name, value]) => `${name}=${value}`),
+    options.publicApiUrl ? `FZ_PUBLIC_API_URL=${options.publicApiUrl}` : null,
+    options.pullDeployments ? "FZ_DEPLOY_PULL=true" : null
+  ].filter((line) => line !== null);
+  if (deploymentEnabled) {
+    environment.push(`HOME=${deployRoot}/agent-home`, `XDG_CACHE_HOME=${deployRoot}/cache`);
+  }
+  const gitCredential = options.gitCredentialPath ? `LoadCredentialEncrypted=git-deploy-key:${options.gitCredentialPath}
+` : "";
+  const projectCredentials = Object.entries(deploymentCredentials).map(([name, path]) => `LoadCredentialEncrypted=${name}:${path}`).join(`
+`);
+  const deploymentWrites = deploymentEnabled ? `ReadWritePaths=${deployRoot}/releases ${deployRoot}/agent-home ${deployRoot}/cache` : "";
+  const deploymentGroup = deploymentEnabled ? `SupplementaryGroups=${DEPLOYMENT_GROUP}` : "";
+  const after = [
+    "network-online.target",
+    deploymentEnabled ? "forgezero-deploy-runner.service" : null,
+    enrolmentEnabled ? "forgezero-agent-enrol.service" : null
+  ].filter((value) => value !== null);
+  const requires = [
+    deploymentEnabled ? "forgezero-deploy-runner.service" : null,
+    enrolmentEnabled ? "forgezero-agent-enrol.service" : null
+  ].filter((value) => value !== null);
+  const deploymentDependency = [
+    `After=${after.join(" ")}`,
+    "Wants=network-online.target",
+    requires.length > 0 ? `Requires=${requires.join(" ")}` : null
+  ].filter((value) => value !== null).join(`
+`);
+  const snpDevice = options.mode === "attested" ? `DevicePolicy=closed
+DeviceAllow=/dev/sev-guest rw` : "";
+  const snpPrepare = options.mode === "attested" ? `ExecStartPre=+/bin/chgrp ${user} /dev/sev-guest
+ExecStartPre=+/bin/chmod 0640 /dev/sev-guest
+` : "";
+  return `[Unit]
+Description=ForgeZero node agent (${options.mode})
+Documentation=https://www.forgezero.net/docs/agent
+${deploymentDependency}
+
+[Service]
+Type=simple
+User=${user}
+Group=${user}
+${deploymentGroup}
+LoadCredentialEncrypted=agent-seed:${seedCredentialPath}
+${gitCredential}${projectCredentials}${projectCredentials ? `
+` : ""}${snpPrepare}ExecStart=${bin}
+Restart=always
+RestartSec=2
+
+${environment.map((line) => `Environment=${line}`).join(`
+`)}
+
+# The node seed and the vault replica live in this process's memory. A core dump
+# writes both to disk, which is the one artefact this design exists to remove.
+LimitCORE=0
+
+# The socket is the entire interface: anything that can read it can read the
+# scope. So it lives in a directory systemd creates with a known owner rather
+# than wherever the process happened to have write access.
+RuntimeDirectory=forgezero
+RuntimeDirectoryMode=0710
+UMask=0077
+
+# Tenant-controlled commands execute in forgezero-deploy-runner.service. This
+# credential-bearing process never needs to cross a privilege boundary.
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=strict
+ProtectHome=true
+ProtectKernelTunables=true
+ProtectKernelModules=true
+ProtectControlGroups=true
+RestrictSUIDSGID=true
+RestrictRealtime=true
+MemoryDenyWriteExecute=true
+LockPersonality=true
+${snpDevice}
+${deploymentWrites}
+
+[Install]
+WantedBy=multi-user.target
+`;
+}
+var UNIT_PATH = "/etc/systemd/system/forgezero-agent.service";
+function planProvision(options) {
+  const mode = options.mode;
+  const user = options.user ?? "forgezero";
+  const seedCredentialPath = options.seedCredentialPath ?? "/etc/forgezero/creds/agent-seed.cred";
+  const credentialDir = seedCredentialPath.replace(/\/[^/]+$/, "");
+  const deployRoot = options.deployRoot ?? "/opt/forgezero";
+  const deploymentEnabled = Boolean(options.repository || options.pullDeployments);
+  const enrolmentEnabled = Boolean(options.enrolTokenSourcePath && options.enrolTokenCredentialPath && options.enrolStatePath);
+  if (Boolean(options.enrolTokenSourcePath) !== Boolean(options.enrolTokenCredentialPath) || Boolean(options.enrolTokenCredentialPath) !== Boolean(options.enrolStatePath))
+    throw new Error("direct enrolment paths must be supplied together");
+  const safePath = (value, label) => {
+    if (!value || !/^\/[A-Za-z0-9._@/-]+$/.test(value))
+      throw new Error(`invalid ${label} path`);
+    return value;
+  };
+  const enrolTokenSourcePath = enrolmentEnabled ? safePath(options.enrolTokenSourcePath, "enrolment source") : undefined;
+  const enrolTokenCredentialPath = enrolmentEnabled ? safePath(options.enrolTokenCredentialPath, "enrolment credential") : undefined;
+  const enrolStatePath = enrolmentEnabled ? safePath(options.enrolStatePath, "enrolment state") : undefined;
+  const enrolStateDir = enrolStatePath?.replace(/\/[^/]+$/, "");
+  const sourceBinPath = options.sourceBinPath ? safePath(options.sourceBinPath, "agent source binary") : undefined;
+  const binPath = options.binPath ? safePath(options.binPath, "agent binary") : undefined;
+  const gitCredentialPath = options.gitCredentialPath ? safePath(options.gitCredentialPath, "Git credential") : undefined;
+  const gitPublicKeyPath = options.gitPublicKeyPath ? safePath(options.gitPublicKeyPath, "Git public key") : undefined;
+  if (options.generateGitIdentity && (!gitCredentialPath || !gitPublicKeyPath)) {
+    throw new Error("generated Git identity needs credential and public-key paths");
+  }
+  const gitPublicKeyDir = gitPublicKeyPath?.replace(/\/[^/]+$/, "");
+  return {
+    mode,
+    reason: reasonFor(mode),
+    unitPath: UNIT_PATH,
+    unit: agentUnit({ ...options, mode }),
+    auxiliaryUnits: [
+      ...deploymentEnabled ? [
+        { path: DEPLOYMENT_RUNNER_SOCKET_UNIT_PATH, unit: deploymentRunnerSocketUnit(user) },
+        { path: DEPLOYMENT_RUNNER_UNIT_PATH, unit: deploymentRunnerUnit(options) }
+      ] : [],
+      ...enrolmentEnabled ? [
+        { path: ENROLMENT_UNIT_PATH, unit: agentEnrolmentUnit(options) }
+      ] : []
+    ],
+    socketPath: options.socketPath,
+    user,
+    steps: [
+      ...sourceBinPath && binPath ? [{
+        label: "root-owned agent runtime",
+        command: `install -d -o root -g root -m 0755 ${binPath.replace(/\/[^/]+$/, "")}; ` + `install -o root -g root -m 0755 ${sourceBinPath} ${binPath}`
+      }] : [],
+      ...deploymentEnabled ? [{
+        label: "deployment isolation group",
+        command: `groupadd --system ${DEPLOYMENT_GROUP} || true`
+      }] : [],
+      {
+        label: "service account",
+        command: `useradd --system --no-create-home --shell /usr/sbin/nologin ${user} || true`
+      },
+      ...deploymentEnabled ? [{
+        label: "credential-free deployment account",
+        command: `useradd --system --no-create-home --shell /usr/sbin/nologin --gid ${DEPLOYMENT_GROUP} ${DEPLOYMENT_RUNNER_USER} || true; ` + `usermod -a -G ${DEPLOYMENT_GROUP} ${user}`
+      }] : [],
+      {
+        label: "credential directory",
+        command: `install -d -o root -g root -m 0700 ${credentialDir}`
+      },
+      {
+        label: "encrypted node identity",
+        command: `test -s ${seedCredentialPath} || { ` + `openssl rand -base64 32 | tr '+/' '-_' | tr -d '=\\n' | ` + `systemd-creds encrypt --name=agent-seed - ${seedCredentialPath}; ` + `chmod 0400 ${seedCredentialPath}; }`
+      },
+      ...options.generateGitIdentity && gitCredentialPath && gitPublicKeyPath ? [
+        {
+          label: "Git deploy identity directory",
+          command: `install -d -o root -g root -m 0755 ${gitPublicKeyDir}`
+        },
+        {
+          label: "unique encrypted Git deploy identity",
+          command: `test -s ${gitCredentialPath} || { ` + `rm -f /run/forgezero-git-deploy-key /run/forgezero-git-deploy-key.pub; ` + `ssh-keygen -q -t ed25519 -N '' -C forgezero-compute -f /run/forgezero-git-deploy-key; ` + `systemd-creds encrypt --name=git-deploy-key /run/forgezero-git-deploy-key ${gitCredentialPath}; ` + `install -o root -g root -m 0444 /run/forgezero-git-deploy-key.pub ${gitPublicKeyPath}; ` + `rm -f /run/forgezero-git-deploy-key /run/forgezero-git-deploy-key.pub; ` + `chmod 0400 ${gitCredentialPath}; }; ` + `test -s ${gitPublicKeyPath} || { ` + `systemd-creds decrypt --name=git-deploy-key ${gitCredentialPath} /run/forgezero-git-deploy-key; ` + `ssh-keygen -y -f /run/forgezero-git-deploy-key | ` + `sed 's/$/ forgezero-compute/' > /run/forgezero-git-deploy-key.pub; ` + `install -o root -g root -m 0444 /run/forgezero-git-deploy-key.pub ${gitPublicKeyPath}; ` + `rm -f /run/forgezero-git-deploy-key /run/forgezero-git-deploy-key.pub; }; ` + `test -s ${gitCredentialPath} && test -s ${gitPublicKeyPath}`
+        }
+      ] : [],
+      ...enrolmentEnabled ? [
+        {
+          label: "enrolment state directory",
+          command: `install -d -o ${user} -g ${user} -m 0700 ${enrolStateDir}`
+        },
+        {
+          label: "encrypted one-time enrolment capability",
+          command: `test -s ${enrolTokenCredentialPath} || { test -r ${enrolTokenSourcePath}; ` + `systemd-creds encrypt --name=enrol-token ${enrolTokenSourcePath} ${enrolTokenCredentialPath}; ` + `chmod 0400 ${enrolTokenCredentialPath}; rm -f ${enrolTokenSourcePath}; }`
+        }
+      ] : [],
+      ...deploymentEnabled ? [{
+        label: "deployment directories",
+        command: `install -d -o root -g root -m 0755 ${deployRoot} && ` + `install -d -o root -g ${DEPLOYMENT_GROUP} -m 3770 ${deployRoot}/releases && ` + `install -d -o ${user} -g ${user} -m 0750 ${deployRoot}/cache && ` + `install -d -o ${user} -g ${user} -m 0700 ${deployRoot}/agent-home && ` + `install -d -o ${DEPLOYMENT_RUNNER_USER} -g ${DEPLOYMENT_GROUP} -m 0700 ${deployRoot}/runner-home ${deployRoot}/runner-home/cache`
+      }] : [],
+      { label: "reload units", command: "systemctl daemon-reload" },
+      {
+        label: "enable and start",
+        command: `systemctl enable --now ${[
+          ...deploymentEnabled ? ["forgezero-deploy-runner.socket", "forgezero-deploy-runner.service"] : [],
+          ...enrolmentEnabled ? ["forgezero-agent-enrol.service"] : [],
+          "forgezero-agent.service"
+        ].join(" ")}`
+      },
+      ...enrolmentEnabled ? [{
+        label: "prove the compute binding is durable",
+        command: `test -s ${enrolStatePath}`
+      }] : [],
+      { label: "prove it is running", command: "systemctl is-active forgezero-agent.service" },
+      { label: "prove the vault socket exists", command: `test -S ${options.socketPath}` },
+      ...deploymentEnabled ? [{
+        label: "prove the deployment runner socket exists",
+        command: `test -S ${DEPLOYMENT_RUNNER_SOCKET}`
+      }] : [],
+      ...options.repository ? [{
+        label: "prove the deployment control socket exists",
+        command: `test -S ${options.controlSocketPath ?? "/run/forgezero/control.sock"}`
+      }] : []
+    ]
+  };
+}
+
+// src/metal-provision.ts
+import { createHash } from "node:crypto";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  statSync,
+  unlinkSync,
+  writeFileSync
+} from "node:fs";
+import { dirname, isAbsolute, join } from "node:path";
+var SAFE_NAME = /^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,63}$/;
+var DEVICE = /^[a-zA-Z][a-zA-Z0-9_.-]{0,14}$/;
+var SHA256 = /^[a-f0-9]{64}$/;
+var IPV4_PREFIX = /^(?:25[0-5]|2[0-4]\d|1?\d?\d)\.(?:25[0-5]|2[0-4]\d|1?\d?\d)\.(?:25[0-5]|2[0-4]\d|1?\d?\d)$/;
+var LINUX_LIST = /^\d+(?:-\d+)?(?:,\d+(?:-\d+)?)*$/;
+
+class MetalProvisionError extends Error {
+}
+function membersOfLinuxList(value, label) {
+  if (!LINUX_LIST.test(value))
+    throw new MetalProvisionError(`invalid ${label} list`);
+  const members = [];
+  for (const part of value.split(",")) {
+    const [startText, endText = startText] = part.split("-");
+    const start = Number(startText);
+    const end = Number(endText);
+    if (!Number.isSafeInteger(start) || !Number.isSafeInteger(end) || start < 0 || end < start || end > 65535) {
+      throw new MetalProvisionError(`invalid ${label} list`);
+    }
+    for (let value2 = start;value2 <= end; value2 += 1)
+      members.push(value2);
+  }
+  if (new Set(members).size !== members.length)
+    throw new MetalProvisionError(`${label} list overlaps itself`);
+  return members;
+}
+var guestNameFor = (computeKey) => `fzg-${createHash("sha256").update(computeKey).digest("hex").slice(0, 16)}`;
+var tapNameFor = (computeKey) => `fzt${createHash("sha256").update(computeKey).digest("hex").slice(0, 12)}`;
+var macForAddress = (address) => {
+  const octets = address.split(".").map(Number);
+  if (octets.length !== 4 || octets.some((value) => !Number.isInteger(value) || value < 0 || value > 255)) {
+    throw new MetalProvisionError("invalid guest address");
+  }
+  return `52:54:00:f0:${octets[2].toString(16).padStart(2, "0")}:${octets[3].toString(16).padStart(2, "0")}`;
+};
+function validateMetalProfile(profile) {
+  if (!SAFE_NAME.test(profile.volumeGroup))
+    throw new MetalProvisionError("invalid volume group");
+  if (!DEVICE.test(profile.bridge))
+    throw new MetalProvisionError("invalid bridge");
+  if (!IPV4_PREFIX.test(profile.subnetPrefix))
+    throw new MetalProvisionError("invalid subnet prefix");
+  if (!Number.isInteger(profile.addressStart) || !Number.isInteger(profile.addressEnd) || profile.addressStart < 2 || profile.addressEnd > 254 || profile.addressStart > profile.addressEnd)
+    throw new MetalProvisionError("invalid guest address range");
+  for (const path of [profile.stateDir, profile.seedDir, profile.unitDir]) {
+    if (!isAbsolute(path))
+      throw new MetalProvisionError("metal paths must be absolute");
+  }
+  new URL(profile.apiUrl);
+  if (!Array.isArray(profile.cpuPools) || profile.cpuPools.length === 0) {
+    throw new MetalProvisionError("at least one exclusive CPU pool is required");
+  }
+  const keys = new Set;
+  const assigned = new Set;
+  const assignedMemory = new Set;
+  let poolsWithMemory = 0;
+  for (const pool of profile.cpuPools) {
+    if (!SAFE_NAME.test(pool.key) || keys.has(pool.key))
+      throw new MetalProvisionError("invalid or duplicate CPU pool key");
+    keys.add(pool.key);
+    const cpus = membersOfLinuxList(pool.cpus, "CPU");
+    if (!Number.isInteger(pool.physicalCores) || pool.physicalCores < 1 || pool.physicalCores > cpus.length) {
+      throw new MetalProvisionError("invalid CPU pool physical-core count");
+    }
+    for (const cpu of cpus) {
+      if (assigned.has(cpu))
+        throw new MetalProvisionError("CPU pools overlap");
+      assigned.add(cpu);
+    }
+    if (pool.memoryNodes) {
+      poolsWithMemory += 1;
+      for (const node of membersOfLinuxList(pool.memoryNodes, "memory-node")) {
+        if (assignedMemory.has(node))
+          throw new MetalProvisionError("guest memory-node pools overlap");
+        assignedMemory.add(node);
+      }
+    }
+  }
+  if (poolsWithMemory !== 0 && poolsWithMemory !== profile.cpuPools.length) {
+    throw new MetalProvisionError("every CPU pool must name memory nodes when NUMA isolation is enabled");
+  }
+  const housekeeping = membersOfLinuxList(profile.housekeepingCpus, "housekeeping CPU");
+  if (housekeeping.some((cpu) => assigned.has(cpu))) {
+    throw new MetalProvisionError("housekeeping CPUs overlap guest CPU pools");
+  }
+  if (profile.housekeepingMemoryNodes) {
+    const housekeepingMemory = membersOfLinuxList(profile.housekeepingMemoryNodes, "housekeeping memory-node");
+    if (housekeepingMemory.some((node) => assignedMemory.has(node))) {
+      throw new MetalProvisionError("housekeeping memory nodes overlap guest memory-node pools");
+    }
+  } else if (assignedMemory.size > 0) {
+    throw new MetalProvisionError("NUMA-isolated guest pools require housekeeping memory nodes");
+  }
+}
+var readManifests = (stateDir) => {
+  if (!existsSync(stateDir))
+    return [];
+  return readdirSync(stateDir).filter((name) => name.endsWith(".json")).map((name) => JSON.parse(readFileSync(join(stateDir, name), "utf8")));
+};
+function allocateAddress(profile, computeKey, rows) {
+  const existing = rows.find((row) => row.computeKey === computeKey);
+  if (existing)
+    return existing.address;
+  const used = new Set(rows.map((row) => row.address));
+  const width = profile.addressEnd - profile.addressStart + 1;
+  const start = createHash("sha256").update(computeKey).digest().readUInt16BE(0) % width;
+  for (let offset = 0;offset < width; offset += 1) {
+    const last = profile.addressStart + (start + offset) % width;
+    const address = `${profile.subnetPrefix}.${last}`;
+    if (!used.has(address))
+      return address;
+  }
+  throw new MetalProvisionError("guest address range is full");
+}
+function allocateCpuPool(profile, claim, rows) {
+  const prior = rows.find((row) => row.computeKey === claim.computeKey);
+  if (prior) {
+    const retained = profile.cpuPools.find((pool) => pool.key === prior.cpuPoolKey);
+    if (!retained || retained.cpus !== prior.allowedCpus || retained.memoryNodes !== prior.allowedMemoryNodes) {
+      throw new MetalProvisionError("persisted guest CPU pool no longer matches the host profile");
+    }
+    return retained;
+  }
+  const used = new Set(rows.map((row) => row.cpuPoolKey));
+  const candidates = profile.cpuPools.filter((pool) => !used.has(pool.key) && pool.physicalCores >= claim.spec.physicalCores && membersOfLinuxList(pool.cpus, "CPU").length >= claim.spec.vcpu).sort((left, right) => left.physicalCores - right.physicalCores || membersOfLinuxList(left.cpus, "CPU").length - membersOfLinuxList(right.cpus, "CPU").length || left.key.localeCompare(right.key));
+  const selected = candidates[0];
+  if (!selected)
+    throw new MetalProvisionError("no exclusive CPU pool can satisfy this guest");
+  return selected;
+}
+var base64 = (value) => Buffer.from(value).toString("base64");
+var yamlFile = (path, content, permissions) => `  - path: ${JSON.stringify(path)}
+    permissions: '${permissions}'
+    encoding: b64
+    content: ${base64(content)}
+`;
+function guestBootstrapScript(profile, attested = Boolean(profile.confidential)) {
+  const agentBun = "/usr/local/lib/forgezero/bun";
+  const attestationSetup = attested ? `# The report device is not part of the encryption path, so a guest can appear
+# healthy and encrypted while attestation is silently impossible. Install and
+# load the exact running-kernel module before the agent is allowed to start.
+DEBIAN_FRONTEND=noninteractive apt-get install -y linux-image-generic "linux-modules-extra-$(uname -r)"
+printf 'sev-guest
+' >/etc/modules-load.d/sev-guest.conf
+modprobe sev-guest
+test -c /dev/sev-guest
+` : "";
+  return `#!/usr/bin/env bash
+set -Eeuo pipefail
+${attestationSetup}useradd --system --no-create-home --shell /usr/sbin/nologin forgezero-agent 2>/dev/null || true
+groupadd --system ${DEPLOYMENT_GROUP} 2>/dev/null || true
+useradd --system --no-create-home --shell /usr/sbin/nologin --gid ${DEPLOYMENT_GROUP} ${DEPLOYMENT_RUNNER_USER} 2>/dev/null || true
+usermod -a -G ${DEPLOYMENT_GROUP} forgezero-agent
+install -d -o root -g root -m 0700 /etc/forgezero/creds
+install -d -o root -g root -m 0755 /etc/forgezero/git
+install -d -o forgezero-agent -g forgezero-agent -m 0700 /var/lib/forgezero
+install -d -o root -g root -m 0755 /opt/forgezero
+install -d -o root -g ${DEPLOYMENT_GROUP} -m 3770 /opt/forgezero/releases
+install -d -o forgezero-agent -g forgezero-agent -m 0700 /opt/forgezero/cache /opt/forgezero/home
+install -d -o ${DEPLOYMENT_RUNNER_USER} -g ${DEPLOYMENT_GROUP} -m 0700 /opt/forgezero/runner-home /opt/forgezero/runner-home/cache
+if [[ -s /run/forgezero-enrol-token ]]; then
+  systemd-creds encrypt --name=enrol-token /run/forgezero-enrol-token /var/lib/forgezero/enrol-token.cred
+  rm -f /run/forgezero-enrol-token
+fi
+chown root:root /var/lib/forgezero/enrol-token.cred
+chmod 0400 /var/lib/forgezero/enrol-token.cred
+if [[ ! -x /usr/local/bin/bun ]]; then
+  curl -fsSL https://bun.sh/install -o /run/fz-bun-install
+  printf '%s  %s
+' '${profile.bunInstallerSha256}' /run/fz-bun-install | sha256sum -c -
+  BUN_INSTALL=${agentBun} BUN_VERSION=${profile.bunVersion} bash /run/fz-bun-install
+  install -m 0755 ${agentBun}/bin/bun /usr/local/bin/bun
+  rm -f /run/fz-bun-install
+fi
+if [[ ! -x /usr/local/bin/fz-agent ]]; then
+  env BUN_INSTALL=${agentBun} /usr/local/bin/bun add -g @forgezero/agent@${profile.agentVersion}
+  ln -sfn ${agentBun}/bin/fz-agent /usr/local/bin/fz-agent
+fi
+if [[ ! -s /etc/forgezero/creds/agent-seed.cred ]]; then
+  umask 077
+  openssl rand -base64 32 | tr '+/' '-_' | tr -d '=
+' >/run/fz-agent-seed
+  systemd-creds encrypt --name=agent-seed /run/fz-agent-seed /etc/forgezero/creds/agent-seed.cred
+  rm -f /run/fz-agent-seed
+fi
+chmod 0400 /etc/forgezero/creds/agent-seed.cred
+if [[ ! -s /etc/forgezero/creds/git-deploy-key.cred ]]; then
+  umask 077
+  rm -f /run/fz-git-deploy-key /run/fz-git-deploy-key.pub
+  ssh-keygen -q -t ed25519 -N '' -C forgezero-compute -f /run/fz-git-deploy-key
+  systemd-creds encrypt --name=git-deploy-key /run/fz-git-deploy-key /etc/forgezero/creds/git-deploy-key.cred
+  install -o root -g root -m 0444 /run/fz-git-deploy-key.pub /etc/forgezero/git/deploy.pub
+  rm -f /run/fz-git-deploy-key /run/fz-git-deploy-key.pub
+fi
+if [[ ! -s /etc/forgezero/git/deploy.pub ]]; then
+  systemd-creds decrypt --name=git-deploy-key /etc/forgezero/creds/git-deploy-key.cred /run/fz-git-deploy-key
+  ssh-keygen -y -f /run/fz-git-deploy-key | sed 's/$/ forgezero-compute/' >/run/fz-git-deploy-key.pub
+  install -o root -g root -m 0444 /run/fz-git-deploy-key.pub /etc/forgezero/git/deploy.pub
+  rm -f /run/fz-git-deploy-key /run/fz-git-deploy-key.pub
+fi
+chmod 0400 /etc/forgezero/creds/git-deploy-key.cred
+systemctl daemon-reload
+systemctl enable --now forgezero-deploy-runner.socket forgezero-deploy-runner.service forgezero-agent.service
+`;
+}
+function guestAgentUnit(profile, name, attested = Boolean(profile.confidential)) {
+  const attestationPrepare = attested ? `ExecStartPre=+/bin/chgrp forgezero-agent /dev/sev-guest
+ExecStartPre=+/bin/chmod 0640 /dev/sev-guest
+` : "";
+  const attestationDevice = attested ? `DevicePolicy=closed
+DeviceAllow=/dev/sev-guest rw
+` : "";
+  return `[Unit]
+Description=ForgeZero compute agent (${name})
+After=network-online.target forgezero-deploy-runner.service
+Wants=network-online.target
+Requires=forgezero-deploy-runner.service
+
+[Service]
+Type=simple
+User=forgezero-agent
+Group=forgezero-agent
+SupplementaryGroups=${DEPLOYMENT_GROUP}
+LoadCredentialEncrypted=agent-seed:/etc/forgezero/creds/agent-seed.cred
+LoadCredentialEncrypted=git-deploy-key:/etc/forgezero/creds/git-deploy-key.cred
+Environment=FZ_SEED_CREDENTIAL=agent-seed
+Environment=FZ_GIT_PUBLIC_KEY_FILE=/etc/forgezero/git/deploy.pub
+Environment=FZ_API=${profile.apiUrl}
+Environment=FZ_ENROL_STATE_FILE=/var/lib/forgezero/enrolment.json
+Environment=FZ_NODE_LABEL=${name}
+Environment=FZ_SOCKET_PATH=/run/forgezero/vault.sock
+Environment=FZ_DEPLOY_ROOT=/opt/forgezero
+Environment=FZ_DEPLOY_PULL=true
+Environment=FZ_DEPLOY_RUNNER_SOCKET=${DEPLOYMENT_RUNNER_SOCKET}
+Environment=HOME=/opt/forgezero/home
+${attestationPrepare}ExecStart=/usr/local/bin/fz-agent
+Restart=on-failure
+RestartSec=5
+RuntimeDirectory=forgezero
+RuntimeDirectoryMode=0710
+UMask=0077
+LimitCORE=0
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=strict
+ProtectHome=true
+ReadWritePaths=/var/lib/forgezero /opt/forgezero
+${attestationDevice}
+
+[Install]
+WantedBy=multi-user.target
+`;
+}
+function guestEnrolmentDropIn() {
+  return `[Service]
+LoadCredentialEncrypted=enrol-token:/var/lib/forgezero/enrol-token.cred
+Environment=FZ_ENROL_TOKEN_CREDENTIAL=enrol-token
+`;
+}
+function guestEnrolmentCleanupScript() {
+  return `#!/usr/bin/env bash
+set -Eeuo pipefail
+for _ in $(seq 1 180); do
+  [[ -s /var/lib/forgezero/enrolment.json ]] && break
+  sleep 1
+done
+[[ -s /var/lib/forgezero/enrolment.json ]] || { echo 'guest enrolment did not become durable' >&2; exit 1; }
+rm -f /var/lib/forgezero/enrol-token.cred
+rm -f /etc/systemd/system/forgezero-agent.service.d/enrolment.conf
+systemctl daemon-reload
+systemctl disable forgezero-enrolment-cleanup.service
+`;
+}
+function guestEnrolmentCleanupUnit() {
+  return `[Unit]
+Description=Remove the consumed ForgeZero guest enrolment credential
+After=forgezero-agent.service
+Requires=forgezero-agent.service
+ConditionPathExists=/var/lib/forgezero/enrol-token.cred
+
+[Service]
+Type=oneshot
+ExecStart=/usr/local/sbin/forgezero-enrolment-cleanup
+TimeoutStartSec=4min
+
+[Install]
+WantedBy=multi-user.target
+`;
+}
+function cloudInit(profile, claim, manifest) {
+  const bootstrap = guestBootstrapScript(profile, claim.spec.confidential);
+  const agentUnit2 = guestAgentUnit(profile, manifest.name, claim.spec.confidential);
+  const enrolmentDropIn = guestEnrolmentDropIn();
+  const cleanupScript = guestEnrolmentCleanupScript();
+  const cleanupUnit = guestEnrolmentCleanupUnit();
+  const runnerSocketUnit = deploymentRunnerSocketUnit("forgezero-agent");
+  const runnerUnit = deploymentRunnerUnit({ binPath: "/usr/local/bin/fz-agent", deployRoot: "/opt/forgezero" });
+  return {
+    userData: `#cloud-config
+package_update: true
+# Git is part of the deployment transport, not a tenant-selected prerequisite:
+# every dynamically claimed repository must be cloneable on a clean image.
+packages: [curl, ca-certificates, openssl, openssh-client, git${claim.spec.confidential ? ", python3" : ""}]
+write_files:
+${yamlFile("/run/forgezero-enrol-token", `${claim.enrolment.token}
+`, "0600")}${yamlFile("/usr/local/sbin/forgezero-guest-bootstrap", bootstrap, "0700")}${yamlFile("/usr/local/sbin/forgezero-enrolment-cleanup", cleanupScript, "0700")}${yamlFile("/etc/systemd/system/forgezero-deploy-runner.socket", runnerSocketUnit, "0644")}${yamlFile("/etc/systemd/system/forgezero-deploy-runner.service", runnerUnit, "0644")}${yamlFile("/etc/systemd/system/forgezero-agent.service", agentUnit2, "0644")}${yamlFile("/etc/systemd/system/forgezero-agent.service.d/enrolment.conf", enrolmentDropIn, "0644")}${yamlFile("/etc/systemd/system/forgezero-enrolment-cleanup.service", cleanupUnit, "0644")}runcmd:
+  - [ bash, /usr/local/sbin/forgezero-guest-bootstrap ]
+  - [ systemctl, enable, --now, forgezero-enrolment-cleanup.service ]
+`,
+    metaData: `instance-id: ${manifest.name}-${claim.attempt}
+local-hostname: ${manifest.name}
+`,
+    networkConfig: `version: 2
+ethernets:
+  primary:
+    match: { name: "en*" }
+    addresses: [ ${manifest.address}/24 ]
+    gateway4: ${profile.gateway}
+    nameservers: { addresses: [${(profile.nameservers ?? ["1.1.1.1", "9.9.9.9"]).join(", ")}] }
+`
+  };
+}
+var checked = async (exec, argv) => {
+  const result = await exec(argv);
+  if (result.exitCode !== 0) {
+    throw new MetalProvisionError(`${argv[0]} failed: ${(result.stderr || result.stdout).trim()}`);
+  }
+  return result;
+};
+async function provisionMetalGuest(profile, claim, exec) {
+  validateMetalProfile(profile);
+  if (!claim.computeKey || !claim.spec.reference || !SAFE_NAME.test(claim.spec.imageKey) || !Number.isInteger(claim.spec.physicalCores) || claim.spec.physicalCores < 1 || claim.spec.physicalCores > 256 || !Number.isInteger(claim.spec.vcpu) || claim.spec.vcpu < 1 || claim.spec.vcpu > 512 || !Number.isInteger(claim.spec.memoryGib) || claim.spec.memoryGib < 1 || claim.spec.memoryGib > 8192 || !Number.isInteger(claim.spec.diskGib) || claim.spec.diskGib < 8 || claim.spec.diskGib > 65536 || !Number.isInteger(claim.spec.egressGuaranteedMbps) || claim.spec.egressGuaranteedMbps < 0 || !Number.isInteger(claim.spec.egressBurstMbps) || claim.spec.egressBurstMbps < claim.spec.egressGuaranteedMbps)
+    throw new MetalProvisionError("invalid compute claim");
+  const image = profile.images[claim.spec.imageKey];
+  if (!image || !isAbsolute(image.path) || !SHA256.test(image.sha256)) {
+    throw new MetalProvisionError(`image ${claim.spec.imageKey} is not configured locally`);
+  }
+  if (!statSync(image.path).isFile())
+    throw new MetalProvisionError("configured image is not a file");
+  const digest = (await checked(exec, ["sha256sum", image.path])).stdout.trim().split(/\s+/)[0];
+  if (digest !== image.sha256)
+    throw new MetalProvisionError("configured image checksum mismatch");
+  for (const path of [profile.stateDir, profile.seedDir, profile.unitDir])
+    mkdirSync(path, { recursive: true, mode: 448 });
+  const manifests = readManifests(profile.stateDir);
+  const name = guestNameFor(claim.computeKey);
+  const manifestPath = join(profile.stateDir, `${name}.json`);
+  const prior = manifests.find((row) => row.computeKey === claim.computeKey);
+  if (prior && prior.reference !== claim.spec.reference)
+    throw new MetalProvisionError("compute identity conflicts with host inventory");
+  const address = allocateAddress(profile, claim.computeKey, manifests);
+  const cpuPool = allocateCpuPool(profile, claim, manifests);
+  const manifest = prior ?? {
+    computeKey: claim.computeKey,
+    reference: claim.spec.reference,
+    name,
+    address,
+    mac: macForAddress(address),
+    cpuPoolKey: cpuPool.key,
+    allowedCpus: cpuPool.cpus,
+    allowedMemoryNodes: cpuPool.memoryNodes,
+    phase: "allocating"
+  };
+  const save = () => writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}
+`, { mode: 384 });
+  save();
+  const lv = `/dev/${profile.volumeGroup}/${name}`;
+  const exists = (await exec(["lvs", "--noheadings", lv])).exitCode === 0;
+  if (!exists)
+    await checked(exec, ["lvcreate", "-y", "-n", name, "-L", `${claim.spec.diskGib}G`, profile.volumeGroup]);
+  if (manifest.phase === "allocating") {
+    await checked(exec, ["qemu-img", "convert", "-O", "raw", image.path, lv]);
+    manifest.phase = "image-ready";
+    save();
+  }
+  const seedBase = join(profile.seedDir, name);
+  const init = cloudInit(profile, claim, manifest);
+  writeFileSync(`${seedBase}-user-data`, init.userData, { mode: 384 });
+  writeFileSync(`${seedBase}-meta-data`, init.metaData, { mode: 384 });
+  writeFileSync(`${seedBase}-network-config`, init.networkConfig, { mode: 384 });
+  const seed = `${seedBase}-seed.iso`;
+  await checked(exec, [
+    "cloud-localds",
+    "-N",
+    `${seedBase}-network-config`,
+    seed,
+    `${seedBase}-user-data`,
+    `${seedBase}-meta-data`
+  ]);
+  const spec = {
+    name,
+    vcpu: claim.spec.vcpu,
+    memoryGib: claim.spec.memoryGib,
+    allowedCpus: manifest.allowedCpus,
+    allowedMemoryNodes: manifest.allowedMemoryNodes,
+    disk: lv,
+    seed,
+    bridge: profile.bridge,
+    mac: manifest.mac,
+    tap: tapNameFor(claim.computeKey),
+    egress: {
+      guaranteedMbps: claim.spec.egressGuaranteedMbps,
+      burstMbps: claim.spec.egressBurstMbps
+    },
+    confidential: claim.spec.confidential ? profile.confidential : undefined,
+    consoleLog: `/var/log/forgezero/${name}.log`
+  };
+  if (claim.spec.confidential && !spec.confidential) {
+    throw new MetalProvisionError("confidential compute requested but host SNP profile is absent");
+  }
+  const service = `forgezero-guest@${name}.service`;
+  const unitPath = join(profile.unitDir, service);
+  mkdirSync(dirname(unitPath), { recursive: true });
+  writeFileSync(unitPath, guestUnit(spec), { mode: 420 });
+  await checked(exec, ["systemctl", "daemon-reload"]);
+  if (prior?.phase === "running") {
+    await checked(exec, ["systemctl", "restart", service]);
+  } else {
+    await checked(exec, ["systemctl", "enable", "--now", service]);
+  }
+  await checked(exec, ["systemctl", "is-active", service]);
+  manifest.phase = "running";
+  save();
+  return { guestAddress: address };
+}
+async function removeMetalGuest(profile, claim, exec) {
+  validateMetalProfile(profile);
+  if (claim.action !== "delete")
+    throw new MetalProvisionError("create claim cannot remove a guest");
+  const name = guestNameFor(claim.computeKey);
+  const manifestPath = join(profile.stateDir, `${name}.json`);
+  if (!existsSync(manifestPath))
+    return {};
+  const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+  if (manifest.computeKey !== claim.computeKey || manifest.reference !== claim.spec.reference || manifest.name !== name) {
+    throw new MetalProvisionError("compute identity conflicts with host inventory");
+  }
+  const service = `forgezero-guest@${name}.service`;
+  const unitPath = join(profile.unitDir, service);
+  if (existsSync(unitPath))
+    await checked(exec, ["systemctl", "disable", "--now", service]);
+  else if ((await exec(["systemctl", "is-active", service])).exitCode === 0) {
+    throw new MetalProvisionError("guest unit is active but its owned unit file is missing");
+  }
+  const lv = `/dev/${profile.volumeGroup}/${name}`;
+  if ((await exec(["lvs", "--noheadings", lv])).exitCode === 0)
+    await checked(exec, ["lvremove", "-fy", lv]);
+  for (const path of [
+    unitPath,
+    join(profile.seedDir, `${name}-seed.iso`),
+    join(profile.seedDir, `${name}-user-data`),
+    join(profile.seedDir, `${name}-meta-data`),
+    join(profile.seedDir, `${name}-network-config`),
+    manifestPath
+  ])
+    if (existsSync(path))
+      unlinkSync(path);
+  await checked(exec, ["systemctl", "daemon-reload"]);
+  return {};
+}
+export {
+  validateMetalProfile,
+  tapNameFor,
+  removeMetalGuest,
+  provisionMetalGuest,
+  macForAddress,
+  guestNameFor,
+  guestEnrolmentDropIn,
+  guestEnrolmentCleanupUnit,
+  guestEnrolmentCleanupScript,
+  guestBootstrapScript,
+  guestAgentUnit,
+  cloudInit,
+  allocateCpuPool,
+  allocateAddress,
+  MetalProvisionError
+};