@forgezero/agent 0.1.80 → 0.1.82

package/README.md

@@ -1511,7 +1511,7 @@ export const selectedCapability = METAL_BOOTSTRAP_STATE_PATH;
 <a id="forgezero-agent-metal-provision"></a>
 ## @forgezero/agent/metal-provision
 
-The single constrained compute materializer for platform genesis, platform scaling and tenant compute. It executes caller-supplied OS, CPU, memory, disk, bandwidth, network and confidentiality coordinates after capacity and image validation; it owns no environment or product-tier shape. This entry exposes 11 named value exports and 6 named type exports. The generated import block lists one name per line for scanning and copying; keep only the names used by your file.
+The single constrained compute materializer for platform genesis, platform scaling and tenant compute. It executes caller-supplied OS, CPU, memory, disk, bandwidth, network and confidentiality coordinates after capacity and image validation; it owns no environment or product-tier shape. This entry exposes 11 named value exports and 7 named type exports. The generated import block lists one name per line for scanning and copying; keep only the names used by your file.
 
 ```text
 import {
@@ -1531,6 +1531,7 @@ import {
 import type {
   GuestManifest,
   MetalCommandResult,
+  MetalCpuAllocation,
   MetalCpuPool,
   MetalExec,
   MetalImage,

package/dist/agent-heartbeat.js

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

package/dist/bootstrap.js

@@ -1416,7 +1416,7 @@ var UPDATE_RETRY_BASE_MS = 5 * 60000;
 var UPDATE_RETRY_MAX_MS = 24 * 60 * 60000;
 
 // src/version.ts
-var VERSION = "0.1.80";
+var VERSION = "0.1.82";
 
 // src/software.ts
 var PINNED_BUN_VERSION = "1.3.14";
@@ -2879,7 +2879,6 @@ function validatePlatformGenesisGuests(guests, expectedCount = 3) {
   }
   const names = new Set;
   const addresses = new Set;
-  const pools = new Set;
   return guests.map((input) => {
     if (!input || typeof input !== "object" || !SAFE_NAME.test(input.name)) {
       throw new Error("platform genesis guest name is malformed");
@@ -2892,13 +2891,11 @@ function validatePlatformGenesisGuests(guests, expectedCount = 3) {
     if (input.cpuPoolKey !== undefined && !SAFE_POOL.test(input.cpuPoolKey)) {
       throw new Error("platform genesis CPU pool key is malformed");
     }
-    if (names.has(input.name) || addresses.has(input.address) || input.cpuPoolKey !== undefined && pools.has(input.cpuPoolKey)) {
-      throw new Error("platform genesis guest names, addresses and explicit CPU pools must be unique");
+    if (names.has(input.name) || addresses.has(input.address)) {
+      throw new Error("platform genesis guest names and addresses must be unique");
     }
     names.add(input.name);
     addresses.add(input.address);
-    if (input.cpuPoolKey !== undefined)
-      pools.add(input.cpuPoolKey);
     const physicalCores = integer(input.physicalCores, 1, 256, "physical core count");
     const vcpu = integer(input.vcpu, 1, 512, "vCPU count");
     if (vcpu < physicalCores)

package/dist/cli/app-build.d.ts

@@ -0,0 +1,10 @@
+export interface AppBuildPlan {
+    cwd: string;
+    command: readonly string[];
+}
+/** Resolve a checkout without teaching the globally installed CLI any App internals. */
+export declare function planAppBuild(input: {
+    root: string;
+    profile?: string;
+    api?: string;
+}): AppBuildPlan;

package/dist/fz-agent.js

@@ -9331,7 +9331,7 @@ async function writeAndCloseProcessInput(input, value) {
 }
 
 // src/version.ts
-var VERSION2 = "0.1.80";
+var VERSION2 = "0.1.82";
 
 // src/ssh-bootstrap.ts
 class SshBootstrapError extends Error {
@@ -10208,6 +10208,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-${createHash7("sha256").update(computeKey).digest("hex").slice(0, 16)}`;
 var tapNameFor = (computeKey) => `fzt${createHash7("sha256").update(computeKey).digest("hex").slice(0, 12)}`;
 var macForAddress = (address) => {
@@ -10265,6 +10291,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");
@@ -10334,26 +10361,38 @@ function allocateCpuPool(profile, claim, rows) {
   const prior = rows.find((row2) => row2.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;
-  }
-  const used = new Set(rows.map((row2) => row2.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;
+    return {
+      key: retained.key,
+      cpus: prior.allowedCpus,
+      physicalCores: matchedGroups.length,
+      memoryNodes: prior.allowedMemoryNodes
+    };
   }
-  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((row2) => membersOfLinuxList(row2.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/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.80";
+var VERSION2 = "0.1.82";
 
 // src/software.ts
 var PINNED_BUN_VERSION = "1.3.14";
@@ -11896,7 +11896,6 @@ function validatePlatformGenesisGuests(guests, expectedCount = 3) {
   }
   const names = new Set;
   const addresses = new Set;
-  const pools = new Set;
   return guests.map((input) => {
     if (!input || typeof input !== "object" || !SAFE_NAME.test(input.name)) {
       throw new Error("platform genesis guest name is malformed");
@@ -11909,13 +11908,11 @@ function validatePlatformGenesisGuests(guests, expectedCount = 3) {
     if (input.cpuPoolKey !== undefined && !SAFE_POOL.test(input.cpuPoolKey)) {
       throw new Error("platform genesis CPU pool key is malformed");
     }
-    if (names.has(input.name) || addresses.has(input.address) || input.cpuPoolKey !== undefined && pools.has(input.cpuPoolKey)) {
-      throw new Error("platform genesis guest names, addresses and explicit CPU pools must be unique");
+    if (names.has(input.name) || addresses.has(input.address)) {
+      throw new Error("platform genesis guest names and addresses must be unique");
     }
     names.add(input.name);
     addresses.add(input.address);
-    if (input.cpuPoolKey !== undefined)
-      pools.add(input.cpuPoolKey);
     const physicalCores = integer2(input.physicalCores, 1, 256, "physical core count");
     const vcpu = integer2(input.vcpu, 1, 512, "vCPU count");
     if (vcpu < physicalCores)
@@ -15550,6 +15547,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");
@@ -15598,6 +15606,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");
@@ -17678,6 +17687,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));
@@ -17907,7 +17948,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")
@@ -18006,7 +18047,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;
@@ -18187,7 +18228,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 });
@@ -18366,7 +18407,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;
@@ -18476,7 +18517,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)}
@@ -18540,7 +18581,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 });
@@ -18570,7 +18611,7 @@ function interactiveGenesisGuests() {
     name: bootstrapAnswer(`Guest ${index} name`),
     address: bootstrapAnswer(`Guest ${index} private IPv4`),
     imageKey: bootstrapAnswer(`Guest ${index} OS image key`, SUPPORTED_GUEST_IMAGE.key),
-    cpuPoolKey: bootstrapAnswer(`Guest ${index} exclusive CPU pool key`),
+    cpuPoolKey: bootstrapAnswer(`Guest ${index} preferred NUMA CPU pool key (capacity is sliced by request)`),
     physicalCores: bootstrapNumber(`Guest ${index} physical cores`),
     vcpu: bootstrapNumber(`Guest ${index} vCPUs`),
     memoryGib: bootstrapNumber(`Guest ${index} memory GiB`),
@@ -19132,7 +19173,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.`);
@@ -19229,6 +19270,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")
@@ -19348,7 +19406,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)}`);
@@ -19411,7 +19469,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));
@@ -19436,7 +19494,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);
@@ -19512,7 +19570,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);
@@ -19660,7 +19718,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
@@ -19810,6 +19870,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/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.80";
+var VERSION = "0.1.82";
 
 // 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;

package/dist/metal-provision.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/operator-bootstrap.js

@@ -1416,7 +1416,7 @@ var UPDATE_RETRY_BASE_MS = 5 * 60000;
 var UPDATE_RETRY_MAX_MS = 24 * 60 * 60000;
 
 // src/version.ts
-var VERSION = "0.1.80";
+var VERSION = "0.1.82";
 
 // src/software.ts
 var PINNED_BUN_VERSION = "1.3.14";
@@ -2879,7 +2879,6 @@ function validatePlatformGenesisGuests(guests, expectedCount = 3) {
   }
   const names = new Set;
   const addresses = new Set;
-  const pools = new Set;
   return guests.map((input) => {
     if (!input || typeof input !== "object" || !SAFE_NAME.test(input.name)) {
       throw new Error("platform genesis guest name is malformed");
@@ -2892,13 +2891,11 @@ function validatePlatformGenesisGuests(guests, expectedCount = 3) {
     if (input.cpuPoolKey !== undefined && !SAFE_POOL.test(input.cpuPoolKey)) {
       throw new Error("platform genesis CPU pool key is malformed");
     }
-    if (names.has(input.name) || addresses.has(input.address) || input.cpuPoolKey !== undefined && pools.has(input.cpuPoolKey)) {
-      throw new Error("platform genesis guest names, addresses and explicit CPU pools must be unique");
+    if (names.has(input.name) || addresses.has(input.address)) {
+      throw new Error("platform genesis guest names and addresses must be unique");
     }
     names.add(input.name);
     addresses.add(input.address);
-    if (input.cpuPoolKey !== undefined)
-      pools.add(input.cpuPoolKey);
     const physicalCores = integer(input.physicalCores, 1, 256, "physical core count");
     const vcpu = integer(input.vcpu, 1, 512, "vCPU count");
     if (vcpu < physicalCores)
@@ -5027,6 +5024,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");
@@ -5075,6 +5083,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");

package/dist/platform-bootstrap-runtime.js

@@ -584,7 +584,6 @@ function validatePlatformGenesisGuests(guests, expectedCount = 3) {
   }
   const names = new Set;
   const addresses = new Set;
-  const pools = new Set;
   return guests.map((input) => {
     if (!input || typeof input !== "object" || !SAFE_NAME.test(input.name)) {
       throw new Error("platform genesis guest name is malformed");
@@ -597,13 +596,11 @@ function validatePlatformGenesisGuests(guests, expectedCount = 3) {
     if (input.cpuPoolKey !== undefined && !SAFE_POOL.test(input.cpuPoolKey)) {
       throw new Error("platform genesis CPU pool key is malformed");
     }
-    if (names.has(input.name) || addresses.has(input.address) || input.cpuPoolKey !== undefined && pools.has(input.cpuPoolKey)) {
-      throw new Error("platform genesis guest names, addresses and explicit CPU pools must be unique");
+    if (names.has(input.name) || addresses.has(input.address)) {
+      throw new Error("platform genesis guest names and addresses must be unique");
     }
     names.add(input.name);
     addresses.add(input.address);
-    if (input.cpuPoolKey !== undefined)
-      pools.add(input.cpuPoolKey);
     const physicalCores = integer(input.physicalCores, 1, 256, "physical core count");
     const vcpu = integer(input.vcpu, 1, 512, "vCPU count");
     if (vcpu < physicalCores)

package/dist/platform-fleet-verification.js

@@ -2647,7 +2647,7 @@ function requestSoftware(requirements, socketPath = DEFAULT_SOFTWARE_HELPER_SOCK
 }
 
 // src/version.ts
-var VERSION3 = "0.1.80";
+var VERSION3 = "0.1.82";
 
 // src/egress-policy.ts
 import { realpathSync as realpathSync3 } from "node:fs";
@@ -3680,7 +3680,6 @@ function validatePlatformGenesisGuests(guests, expectedCount = 3) {
   }
   const names = new Set;
   const addresses = new Set;
-  const pools = new Set;
   return guests.map((input) => {
     if (!input || typeof input !== "object" || !SAFE_NAME.test(input.name)) {
       throw new Error("platform genesis guest name is malformed");
@@ -3693,13 +3692,11 @@ function validatePlatformGenesisGuests(guests, expectedCount = 3) {
     if (input.cpuPoolKey !== undefined && !SAFE_POOL.test(input.cpuPoolKey)) {
       throw new Error("platform genesis CPU pool key is malformed");
     }
-    if (names.has(input.name) || addresses.has(input.address) || input.cpuPoolKey !== undefined && pools.has(input.cpuPoolKey)) {
-      throw new Error("platform genesis guest names, addresses and explicit CPU pools must be unique");
+    if (names.has(input.name) || addresses.has(input.address)) {
+      throw new Error("platform genesis guest names and addresses must be unique");
     }
     names.add(input.name);
     addresses.add(input.address);
-    if (input.cpuPoolKey !== undefined)
-      pools.add(input.cpuPoolKey);
     const physicalCores = integer(input.physicalCores, 1, 256, "physical core count");
     const vcpu = integer(input.vcpu, 1, 512, "vCPU count");
     if (vcpu < physicalCores)

package/dist/platform-genesis.js

@@ -584,7 +584,6 @@ function validatePlatformGenesisGuests(guests, expectedCount = 3) {
   }
   const names = new Set;
   const addresses = new Set;
-  const pools = new Set;
   return guests.map((input) => {
     if (!input || typeof input !== "object" || !SAFE_NAME.test(input.name)) {
       throw new Error("platform genesis guest name is malformed");
@@ -597,13 +596,11 @@ function validatePlatformGenesisGuests(guests, expectedCount = 3) {
     if (input.cpuPoolKey !== undefined && !SAFE_POOL.test(input.cpuPoolKey)) {
       throw new Error("platform genesis CPU pool key is malformed");
     }
-    if (names.has(input.name) || addresses.has(input.address) || input.cpuPoolKey !== undefined && pools.has(input.cpuPoolKey)) {
-      throw new Error("platform genesis guest names, addresses and explicit CPU pools must be unique");
+    if (names.has(input.name) || addresses.has(input.address)) {
+      throw new Error("platform genesis guest names and addresses must be unique");
     }
     names.add(input.name);
     addresses.add(input.address);
-    if (input.cpuPoolKey !== undefined)
-      pools.add(input.cpuPoolKey);
     const physicalCores = integer(input.physicalCores, 1, 256, "physical core count");
     const vcpu = integer(input.vcpu, 1, 512, "vCPU count");
     if (vcpu < physicalCores)

package/dist/provision.js

@@ -2647,7 +2647,7 @@ function requestSoftware(requirements, socketPath = DEFAULT_SOFTWARE_HELPER_SOCK
 }
 
 // src/version.ts
-var VERSION3 = "0.1.80";
+var VERSION3 = "0.1.82";
 
 // src/egress-policy.ts
 import { realpathSync as realpathSync3 } from "node:fs";

package/dist/version.d.ts

@@ -1,2 +1,2 @@
 /** One package version shared by both public binaries. Pinned to package.json by tests. */
-export declare const VERSION = "0.1.80";
+export declare const VERSION = "0.1.82";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgezero/agent",
-  "version": "0.1.80",
+  "version": "0.1.82",
   "type": "module",
   "scripts": {
     "check": "tsc --noEmit",