@forgezero/agent 0.1.79 → 0.1.81

package/dist/fz.js

@@ -4810,8 +4810,8 @@ async function spawnWith(command, env, report = () => {}, options = {}) {
 }
 
 // src/cli/index.ts
-import { existsSync as existsSync12, lstatSync as lstatSync10, mkdirSync as mkdirSync13, readFileSync as readFileSync15, writeFileSync as writeFileSync13 } from "fs";
-import { basename as basename3, dirname as dirname14, isAbsolute as isAbsolute7, join as join12, resolve as resolve11 } from "path";
+import { existsSync as existsSync12, lstatSync as lstatSync10, mkdirSync as mkdirSync13, readFileSync as readFileSync16, writeFileSync as writeFileSync13 } from "fs";
+import { basename as basename3, dirname as dirname14, isAbsolute as isAbsolute7, join as join12, resolve as resolve12 } from "path";
 
 // src/process-input.ts
 async function writeAndCloseProcessInput(input, value) {
@@ -4837,7 +4837,7 @@ var UPDATE_RETRY_BASE_MS = 5 * 60000;
 var UPDATE_RETRY_MAX_MS = 24 * 60 * 60000;
 
 // src/version.ts
-var VERSION2 = "0.1.79";
+var VERSION2 = "0.1.81";
 
 // src/software.ts
 var PINNED_BUN_VERSION = "1.3.14";
@@ -10573,7 +10573,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)) {
     fail2(where, "contains an unsupported reference.");
   }
   return { $ref: coordinate };
@@ -11005,6 +11005,12 @@ function validateStep(value, where, targets, context) {
     if (!targets.has(String(scope.target)))
       fail2(`${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)))
+      fail2(`${where}.scope.target`, "must name an existing target.");
+    if (!["relay", "standby", "member"].includes(String(scope.role)))
+      fail2(`${where}.scope.role`, "is unsupported.");
   } else
     fail2(`${where}.scope.kind`, "is unsupported.");
   if (row2.timeoutMs !== undefined)
@@ -11159,7 +11165,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")
       fail2(`deployment.spec.targets.${targetName}.kind`, "must be compute.");
     const selector = object(target.selector, `deployment.spec.targets.${targetName}.selector`);
@@ -11281,6 +11287,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")
+        fail2(`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)))
+        fail2(`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) {
+        fail2(`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)) {
+        fail2(`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)
+          fail2(`deployment.spec.targets.${targetName}.topology.crossMetal.directPrivateMaximumMetals`, "must be 2.");
+        if (!credentials[named(crossMetal.credential, `deployment.spec.targets.${targetName}.topology.crossMetal.credential`)])
+          fail2(`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
+        fail2(`deployment.spec.targets.${targetName}.topology.crossMetal.mode`, "is unsupported.");
+      if (allocation.sharing !== "exclusive")
+        fail2(`deployment.spec.targets.${targetName}.allocation.sharing`, "must be exclusive for a per-metal relay topology.");
+      if (minimum < 1 + Number(relays.standbyPerMetal))
+        fail2(`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);
@@ -11304,6 +11349,9 @@ function compileDeployment(sourceValue) {
     if (target.connectivity?.private?.mode === "cloudflare-warp" && ![...requirementDefinitions.values()].some(({ capability }) => capability === "network.private")) {
       fail2(`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")) {
+      fail2(`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);
@@ -12058,7 +12106,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);
@@ -12138,7 +12193,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,
@@ -12207,7 +12262,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.");
   }
@@ -12221,6 +12281,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)
@@ -12234,7 +12296,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
@@ -14722,7 +14784,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,
@@ -15487,6 +15550,17 @@ function membersOfLinuxList(value, label) {
     throw new MetalProvisionError(`${label} list overlaps itself`);
   return members;
 }
+function physicalCoreGroups(pool) {
+  const cpus = membersOfLinuxList(pool.cpus, "CPU");
+  if (cpus.length % pool.physicalCores !== 0) {
+    throw new MetalProvisionError("CPU pool threads must divide evenly across physical cores");
+  }
+  const threadsPerCore = cpus.length / pool.physicalCores;
+  if (!Number.isInteger(threadsPerCore) || threadsPerCore < 1 || threadsPerCore > 8) {
+    throw new MetalProvisionError("invalid CPU pool threads-per-core topology");
+  }
+  return Array.from({ length: pool.physicalCores }, (_, core) => Array.from({ length: threadsPerCore }, (_2, thread) => cpus[core + thread * pool.physicalCores]));
+}
 function validateMetalProfile(profile) {
   if (!SAFE_NAME2.test(profile.volumeGroup))
     throw new MetalProvisionError("invalid volume group");
@@ -15535,6 +15609,7 @@ function validateMetalProfile(profile) {
     if (!Number.isInteger(pool.physicalCores) || pool.physicalCores < 1 || pool.physicalCores > cpus.length) {
       throw new MetalProvisionError("invalid CPU pool physical-core count");
     }
+    physicalCoreGroups(pool);
     for (const cpu of cpus) {
       if (assigned.has(cpu))
         throw new MetalProvisionError("CPU pools overlap");
@@ -17298,8 +17373,8 @@ function platformGenesisBootstrapConfigs(template, guests, nodes, metalHostname,
       databaseAddress: guest.address,
       databaseMaster: role === "joiner" ? master : undefined,
       nodeHostname: node.nodeHostname,
-      seedSyncPeers: fleet.filter((_, peer) => peer !== index).map((peer) => `ws://${peer.address}:${config.runtime.bluePort}/internal/seed`),
-      seedSyncMembers: 3,
+      seedSyncPeers: fleet.filter((_, peer) => peer !== index).flatMap((peer) => [config.runtime.bluePort, config.runtime.greenPort].map((port) => `ws://${peer.address}:${port}/_internal/forgezero/seed-mesh/v2`)),
+      seedSyncMembers: nodes.map(({ nodeHostname }) => nodeHostname),
       initialInventory,
       custodianEmail: index === 0 ? template.runtime.environment.custodianEmail : undefined
     };
@@ -17615,6 +17690,38 @@ async function runRepositoryOperation(operation, requestedRoot, args = []) {
 `), { cwd: resolved.cwd });
 }
 
+// src/cli/app-build.ts
+import { readFileSync as readFileSync15 } from "fs";
+import { resolve as resolve11 } from "path";
+function planAppBuild(input) {
+  const cwd = resolve11(input.root);
+  let manifest;
+  try {
+    manifest = JSON.parse(readFileSync15(resolve11(cwd, "package.json"), "utf8"));
+  } catch {
+    throw new Error(`--root must name a ForgeZero App checkout: ${cwd}`);
+  }
+  if (manifest.name !== "@forgezero/app") {
+    throw new Error(`--root must name @forgezero/app, not ${manifest.name ?? "an unnamed package"}.`);
+  }
+  if (input.profile && !["local", "development", "production"].includes(input.profile)) {
+    throw new Error("--profile must be local, development, or production.");
+  }
+  if (input.profile && input.api)
+    throw new Error("Choose --profile or --api, not both.");
+  return {
+    cwd,
+    command: [
+      "bun",
+      "run",
+      "build",
+      "--",
+      ...input.profile ? ["--profile", input.profile] : [],
+      ...input.api ? ["--api", input.api] : []
+    ]
+  };
+}
+
 // src/cli/index.ts
 var DEFAULT_MODE = (THRESHOLD_MODES.find((mode) => mode.threshold === 1 && mode.total === 1) ?? THRESHOLD_MODES[0]).id;
 var PACKAGED_AGENT_BIN2 = fileURLToPath3(new URL("./fz-agent.js", import.meta.url));
@@ -17844,7 +17951,7 @@ async function api(options, path, init) {
   return { status: response.status, body };
 }
 function sleep(ms) {
-  return new Promise((resolve12) => setTimeout(resolve12, ms));
+  return new Promise((resolve13) => setTimeout(resolve13, ms));
 }
 function browserCommand(url) {
   if (process.platform === "darwin")
@@ -17943,7 +18050,7 @@ function readOwnerOnlySecret(path, label) {
   if (uid !== undefined && uid !== 0 && metadata.uid !== uid) {
     throw new Error(`The ${label} file ${path} is not owned by the current user.`);
   }
-  const value = readFileSync15(path, "utf8").trim();
+  const value = readFileSync16(path, "utf8").trim();
   if (!value)
     throw new Error(`The ${label} file ${path} is empty.`);
   return value;
@@ -18124,7 +18231,7 @@ async function cmdApi(options, args) {
     let body = undefined;
     if (options.data !== undefined && options.dataFile)
       throw new Error("Use only one of --data or --data-file.");
-    const encoded = options.data === "-" ? await Bun.stdin.text() : options.dataFile ? readFileSync15(options.dataFile, "utf8") : options.data;
+    const encoded = options.data === "-" ? await Bun.stdin.text() : options.dataFile ? readFileSync16(options.dataFile, "utf8") : options.data;
     if (encoded !== undefined)
       body = JSON.parse(encoded);
     const result = await api(options, `${url.pathname}${url.search}`, { method, body });
@@ -18303,7 +18410,7 @@ async function cmdAgent(options, args) {
       out.line();
       out.line("  Compatibility SSH deploy public key:");
       out.line();
-      out.line(`  ${readFileSync15(gitIdentity.gitPublicKeyPath, "utf8").trim()}`);
+      out.line(`  ${readFileSync16(gitIdentity.gitPublicKeyPath, "utf8").trim()}`);
       out.line();
     }
     return 0;
@@ -18413,7 +18520,7 @@ function interactiveMetalBootstrap() {
   });
 }
 function writeBootstrapConfig(path, config) {
-  if (!isAbsolute7(path) || resolve11(path) !== path)
+  if (!isAbsolute7(path) || resolve12(path) !== path)
     throw new Error("--output must be a canonical absolute path");
   mkdirSync13(dirname14(path), { recursive: true, mode: 448 });
   writeFileSync13(path, `${JSON.stringify(config, null, 2)}
@@ -18477,7 +18584,7 @@ async function interactiveCloudflareBootstrap() {
   });
 }
 function genesisOutputDirectory(path) {
-  if (!isAbsolute7(path) || resolve11(path) !== path)
+  if (!isAbsolute7(path) || resolve12(path) !== path)
     throw new Error("--output must be a canonical absolute directory");
   if (!existsSync12(path))
     mkdirSync13(path, { recursive: true, mode: 448 });
@@ -18642,7 +18749,7 @@ function interactiveBootstrap(kind, genesisGuests, genesisCloudflareCheckpoint)
   const collectorUnit = FORGEZERO_OTEL_COLLECTOR_UNIT;
   const replicationFactor = Number(bootstrapAnswer("Database replication factor", "3"));
   const writeConcern = Number(bootstrapAnswer("Database write concern", "2"));
-  const seedPeers = genesis ? fleet.slice(1).map((peer) => `ws://${peer.address}:3001/internal/seed`) : bootstrapAnswer("Seed WebSocket peers (comma-separated)").split(",").map((item) => item.trim()).filter(Boolean);
+  const seedPeers = genesis ? fleet.slice(1).flatMap((peer) => [3001, 3002].map((port) => `ws://${peer.address}:${port}/_internal/forgezero/seed-mesh/v2`)) : bootstrapAnswer("Seed WebSocket peers (comma-separated)").split(",").map((item) => item.trim()).filter(Boolean);
   const emailProvider = bootstrapAnswer("Bootstrap email provider (smtp/jetemail)", "smtp");
   if (!["smtp", "jetemail"].includes(emailProvider))
     throw new Error("Bootstrap email provider must be smtp or jetemail");
@@ -18698,7 +18805,7 @@ function interactiveBootstrap(kind, genesisGuests, genesisCloudflareCheckpoint)
         publicApiPort: Number(bootstrapAnswer("Loopback public API port", "3000")),
         sharedDirectory: "/opt/forgezero/shared",
         seedSyncPeers: seedPeers,
-        seedSyncMembers: Number(bootstrapAnswer("Seed quorum members", "3")),
+        seedSyncMembers: bootstrapList("Seed member hostnames (comma-separated)"),
         seedSyncEpoch: bootstrapAnswer("Seed epoch"),
         concurrencyLimit: Number(bootstrapAnswer("Initial concurrency limit", "128")),
         drainDeadlineMs: Number(bootstrapAnswer("Drain deadline milliseconds", "30000")),
@@ -19069,7 +19176,7 @@ async function cmdUnlock(options) {
     if (options.key || options.userExplicit) {
       throw new Error("SSH/user unlock coordinates are not accepted. SSH keys cannot open a WebAuthn-PRF custody envelope; use --phrase-file or --phrase-stdin.");
     }
-    const phraseText = options.phraseFile ? readOwnerOnlySecret(options.phraseFile, "recovery phrase") : options.phraseStdin ? readFileSync15(0, "utf8").trim() : "";
+    const phraseText = options.phraseFile ? readOwnerOnlySecret(options.phraseFile, "recovery phrase") : options.phraseStdin ? readFileSync16(0, "utf8").trim() : "";
     const phrase = phraseText ? phraseText.split(/\s+/) : [];
     if (phrase.length !== 24) {
       throw new Error(`Recovery phrase must contain exactly 24 words; received ${phrase.length}. Use --phrase-file or --phrase-stdin.`);
@@ -19166,6 +19273,23 @@ function cmdProject(options, args) {
     return 1;
   }
 }
+async function cmdApp(options, args) {
+  if ((args[0] ?? "") !== "build" || args.length !== 1) {
+    out.fail("Usage: fz app build [--root <app>] [--profile local|development|production | --api <origin>]");
+    return 2;
+  }
+  try {
+    const plan = planAppBuild({
+      root: options.projectRoot,
+      ...options.deployProfile !== "app" ? { profile: options.deployProfile } : {},
+      ...options.apiExplicit ? { api: options.api } : {}
+    });
+    return await spawnWith(plan.command, Object.fromEntries(Object.entries(process.env).filter((entry) => entry[1] !== undefined)), (line) => out.line(line), { cwd: plan.cwd });
+  } catch (cause) {
+    out.fail(cause instanceof Error ? cause.message : String(cause));
+    return 1;
+  }
+}
 function repositoryOperationArguments(options, args) {
   const unsupported = unsupportedRepositoryCliOption(process.argv.slice(2));
   if (unsupported === "--root")
@@ -19285,7 +19409,7 @@ function projectFromCheckout(options) {
   try {
     return loadConfig({
       cwd: options.projectRoot,
-      readFile: (path) => existsSync12(path) ? readFileSync15(path, "utf8") : undefined
+      readFile: (path) => existsSync12(path) ? readFileSync16(path, "utf8") : undefined
     }).config.project;
   } catch (cause) {
     throw new Error(`No --project was given and the checkout has no usable .fz/config.json: ${cause instanceof Error ? cause.message : String(cause)}`);
@@ -19348,7 +19472,7 @@ async function cmdDeploy(options, args) {
           out.ok(`Initialized legacy .fz/deploy.json (${created.summary.digest}).`);
         return 0;
       }
-      initializeTypeScriptDeployment(options.projectRoot, { name: options.projectName ?? basename3(resolve11(options.projectRoot)), force: options.force });
+      initializeTypeScriptDeployment(options.projectRoot, { name: options.projectName ?? basename3(resolve12(options.projectRoot)), force: options.force });
       const compiled = await compileDeploymentProject(options.projectRoot);
       if (options.json)
         out.line(JSON.stringify({ source: compiled.source, output: compiled.output, digest: compiled.digest }, null, 2));
@@ -19373,7 +19497,7 @@ async function cmdDeploy(options, args) {
       return problems.length === 0 ? 0 : 1;
     }
     if (operation === "check" || operation === "sync") {
-      if (existsSync12(resolve11(options.projectRoot, DEPLOY_SOURCE_FILE))) {
+      if (existsSync12(resolve12(options.projectRoot, DEPLOY_SOURCE_FILE))) {
         const expected = await compileDeploymentProject(options.projectRoot, { write: false });
         const actual = inspectCompiledDeployment(options.projectRoot);
         const current2 = canonicalJson(expected.plan) === canonicalJson(actual.plan);
@@ -19449,7 +19573,7 @@ async function cmdDeploy(options, args) {
         branch: options.branch,
         cloneUrl: required(options.cloneUrl, "--clone-url"),
         sourceAuth,
-        ...options.knownHostsFile ? { knownHosts: readFileSync15(options.knownHostsFile, "utf8") } : {},
+        ...options.knownHostsFile ? { knownHosts: readFileSync16(options.knownHostsFile, "utf8") } : {},
         projectKey
       } });
       const pipelineKey2 = String(created.pipelineKey);
@@ -19597,7 +19721,9 @@ function usage() {
 	 fz bootstrap repair     Reapply an explicitly supplied reviewed config
     fz project init         Create vendor-neutral, Git-persisted AI context
     fz project sync         Regenerate Claude/Codex/Gemini/Copilot/Cursor adapters
-    fz project check        Fail when truth sources or generated adapters drift
+	 fz project check        Fail when truth sources or generated adapters drift
+	 fz app build            Build the static App for a numbered local/development/
+	                         production choice, --profile, or an explicit --api origin
     fz deploy init          Create forgezero.deploy.ts and its fail-safe canonical plan
     fz deploy compile       Compile TypeScript into .fz/deploy.plan.json
     fz deploy check         Validate source, plan, actions, providers and topology
@@ -19747,6 +19873,9 @@ async function runCli() {
     case "project":
       code = cmdProject(options, args);
       break;
+    case "app":
+      code = await cmdApp(options, args);
+      break;
     case "deploy":
       code = await cmdDeploy(options, args);
       break;

package/dist/index.d.ts

@@ -14,6 +14,7 @@ export type { AgentCredentialLocation, DeploymentCredentialBinding, DeploymentCr
 export { createDeploymentManager, DeploymentError } from './deployment';
 export type { DeploymentManager, DeploymentOptions, DeploymentRequest, DeploymentResult } from './deployment';
 export { DeploymentInputError, resolveDeploymentInputs, resolveDeploymentTargets } from './deployment-targets';
+export { DeploymentTopologyError, planDeploymentTopology, type DeploymentTopologyAssignment, type DeploymentTopologyPlacement, type DeploymentTopologyRole, type DeploymentTopologyTransport } from './deployment-topology';
 export { DEFAULT_CONTROL_SOCKET, requestControl, startControlServer } from './control';
 export { pullDeploymentOnce, startDeploymentPull } from './deployment-pull';
 export type { DeploymentPullOptions, RemoteDeploymentClaim, PullResult } from './deployment-pull';

package/dist/metal-bootstrap.js

@@ -118,6 +118,17 @@ function membersOfLinuxList(value, label) {
     throw new MetalProvisionError(`${label} list overlaps itself`);
   return members;
 }
+function physicalCoreGroups(pool) {
+  const cpus = membersOfLinuxList(pool.cpus, "CPU");
+  if (cpus.length % pool.physicalCores !== 0) {
+    throw new MetalProvisionError("CPU pool threads must divide evenly across physical cores");
+  }
+  const threadsPerCore = cpus.length / pool.physicalCores;
+  if (!Number.isInteger(threadsPerCore) || threadsPerCore < 1 || threadsPerCore > 8) {
+    throw new MetalProvisionError("invalid CPU pool threads-per-core topology");
+  }
+  return Array.from({ length: pool.physicalCores }, (_, core) => Array.from({ length: threadsPerCore }, (_2, thread) => cpus[core + thread * pool.physicalCores]));
+}
 function validateMetalProfile(profile) {
   if (!SAFE_NAME.test(profile.volumeGroup))
     throw new MetalProvisionError("invalid volume group");
@@ -166,6 +177,7 @@ function validateMetalProfile(profile) {
     if (!Number.isInteger(pool.physicalCores) || pool.physicalCores < 1 || pool.physicalCores > cpus.length) {
       throw new MetalProvisionError("invalid CPU pool physical-core count");
     }
+    physicalCoreGroups(pool);
     for (const cpu of cpus) {
       if (assigned.has(cpu))
         throw new MetalProvisionError("CPU pools overlap");
@@ -354,7 +366,7 @@ function systemdAgentEgressDirectives(loopbackTcpPorts = []) {
 }
 
 // src/version.ts
-var VERSION = "0.1.79";
+var VERSION = "0.1.81";
 
 // src/otel-collector.ts
 var FORGEZERO_OTEL_COLLECTOR_UNIT = "forgezero-otel-collector.service";

package/dist/metal-helper-socket.js

@@ -748,6 +748,32 @@ function membersOfLinuxList(value, label) {
     throw new MetalProvisionError(`${label} list overlaps itself`);
   return members;
 }
+function linuxList(members) {
+  const sorted = [...new Set(members)].sort((left, right) => left - right);
+  const ranges = [];
+  for (let index = 0;index < sorted.length; ) {
+    const start = sorted[index];
+    let end = start;
+    while (index + 1 < sorted.length && sorted[index + 1] === end + 1) {
+      index += 1;
+      end = sorted[index];
+    }
+    ranges.push(start === end ? String(start) : `${start}-${end}`);
+    index += 1;
+  }
+  return ranges.join(",");
+}
+function physicalCoreGroups(pool) {
+  const cpus = membersOfLinuxList(pool.cpus, "CPU");
+  if (cpus.length % pool.physicalCores !== 0) {
+    throw new MetalProvisionError("CPU pool threads must divide evenly across physical cores");
+  }
+  const threadsPerCore = cpus.length / pool.physicalCores;
+  if (!Number.isInteger(threadsPerCore) || threadsPerCore < 1 || threadsPerCore > 8) {
+    throw new MetalProvisionError("invalid CPU pool threads-per-core topology");
+  }
+  return Array.from({ length: pool.physicalCores }, (_, core) => Array.from({ length: threadsPerCore }, (_2, thread) => cpus[core + thread * pool.physicalCores]));
+}
 var guestNameFor = (computeKey) => `fzg-${createHash2("sha256").update(computeKey).digest("hex").slice(0, 16)}`;
 var tapNameFor = (computeKey) => `fzt${createHash2("sha256").update(computeKey).digest("hex").slice(0, 12)}`;
 var macForAddress = (address) => {
@@ -805,6 +831,7 @@ function validateMetalProfile(profile) {
     if (!Number.isInteger(pool.physicalCores) || pool.physicalCores < 1 || pool.physicalCores > cpus.length) {
       throw new MetalProvisionError("invalid CPU pool physical-core count");
     }
+    physicalCoreGroups(pool);
     for (const cpu of cpus) {
       if (assigned.has(cpu))
         throw new MetalProvisionError("CPU pools overlap");
@@ -874,26 +901,38 @@ 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) {
+    const groups2 = retained ? physicalCoreGroups(retained) : [];
+    const retainedCpus = new Set(membersOfLinuxList(prior.allowedCpus, "persisted guest CPU"));
+    const matchedGroups = groups2.filter((group) => group.every((cpu) => retainedCpus.has(cpu)));
+    if (!retained || retained.memoryNodes !== prior.allowedMemoryNodes || matchedGroups.length !== claim.spec.physicalCores || matchedGroups.flat().length !== retainedCpus.size || retainedCpus.size < claim.spec.vcpu || claim.spec.cpuPoolKey !== undefined && claim.spec.cpuPoolKey !== retained.key) {
       throw new MetalProvisionError("persisted guest CPU pool no longer matches the host profile");
     }
-    return retained;
+    return {
+      key: retained.key,
+      cpus: prior.allowedCpus,
+      physicalCores: matchedGroups.length,
+      memoryNodes: prior.allowedMemoryNodes
+    };
   }
-  const used = new Set(rows.map((row) => row.cpuPoolKey));
-  if (claim.spec.cpuPoolKey) {
-    const requested = profile.cpuPools.find((pool) => pool.key === claim.spec.cpuPoolKey);
-    if (!requested || used.has(requested.key)) {
-      throw new MetalProvisionError("requested CPU pool is unavailable");
-    }
-    if (requested.physicalCores < claim.spec.physicalCores || membersOfLinuxList(requested.cpus, "CPU").length < claim.spec.vcpu)
-      throw new MetalProvisionError("requested CPU pool cannot satisfy this guest");
-    return requested;
-  }
-  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 usedCpus = new Set(rows.flatMap((row) => membersOfLinuxList(row.allowedCpus, "persisted guest CPU")));
+  const candidates = profile.cpuPools.filter((pool) => !claim.spec.cpuPoolKey || pool.key === claim.spec.cpuPoolKey).map((pool) => ({
+    pool,
+    available: physicalCoreGroups(pool).filter((group) => group.every((cpu) => !usedCpus.has(cpu)))
+  })).filter(({ available }) => {
+    const selected2 = available.slice(0, claim.spec.physicalCores);
+    return selected2.length === claim.spec.physicalCores && selected2.flat().length >= claim.spec.vcpu;
+  }).sort((left, right) => left.available.length - right.available.length || left.pool.key.localeCompare(right.pool.key));
   const selected = candidates[0];
-  if (!selected)
-    throw new MetalProvisionError("no exclusive CPU pool can satisfy this guest");
-  return selected;
+  if (!selected) {
+    throw new MetalProvisionError(claim.spec.cpuPoolKey ? "requested CPU pool cannot satisfy this guest" : "no exclusive CPU capacity can satisfy this guest");
+  }
+  const groups = selected.available.slice(0, claim.spec.physicalCores);
+  return {
+    key: selected.pool.key,
+    cpus: linuxList(groups.flat()),
+    physicalCores: groups.length,
+    memoryNodes: selected.pool.memoryNodes
+  };
 }
 var base64 = (value) => Buffer.from(value).toString("base64");
 var yamlFile = (path2, content, permissions) => `  - path: ${JSON.stringify(path2)}

package/dist/metal-provision.d.ts

@@ -3,7 +3,7 @@ export interface MetalImage {
     path: string;
     sha256: string;
 }
-/** One non-overlapping physical isolation boundary available to one guest. */
+/** One non-overlapping NUMA-local CPU capacity pool that may serve several guests. */
 export interface MetalCpuPool {
     key: string;
     /** Linux CPU-list syntax, including every SMT sibling in this pool. */
@@ -13,6 +13,9 @@ export interface MetalCpuPool {
     /** Linux NUMA node-list syntax. Optional on a non-NUMA machine. */
     memoryNodes?: string;
 }
+/** Exact non-overlapping physical-core slice reserved for one guest. */
+export interface MetalCpuAllocation extends MetalCpuPool {
+}
 export interface MetalProvisionProfile {
     volumeGroup: string;
     bridge: string;
@@ -70,8 +73,8 @@ export declare const tapNameFor: (computeKey: string) => string;
 export declare const macForAddress: (address: string) => string;
 export declare function validateMetalProfile(profile: MetalProvisionProfile): void;
 export declare function allocateAddress(profile: MetalProvisionProfile, computeKey: string, rows: GuestManifest[]): string;
-/** Stable tight-fit allocation of one exclusive CPU/NUMA pool. */
-export declare function allocateCpuPool(profile: MetalProvisionProfile, claim: Pick<RemoteProvisionClaim, 'computeKey' | 'spec'>, rows: GuestManifest[]): MetalCpuPool;
+/** Stable tight-fit allocation of exact physical cores inside one NUMA-local pool. */
+export declare function allocateCpuPool(profile: MetalProvisionProfile, claim: Pick<RemoteProvisionClaim, 'computeKey' | 'spec'>, rows: GuestManifest[]): MetalCpuAllocation;
 export declare function guestBootstrapOperations(profile: MetalProvisionProfile, attested?: boolean, hasEnrolment?: boolean, nodeLabel?: string): readonly (readonly string[])[];
 export declare function cloudInit(profile: MetalProvisionProfile, claim: CreateRemoteProvisionClaim, manifest: GuestManifest): {
     userData: string;