@forgezero/agent 0.1.81 → 0.1.83

package/README.md

@@ -85,6 +85,8 @@ Every row links to the detailed explanation and named-import/example area below.
 
 bun add -g @forgezero/agent — Install the version-matched fz operator CLI and fz-agent daemon.
 fz deploy init — Create a typed forgezero.deploy.ts and its canonical inert execution plan.
+fz deploy init --runtime containerd --os ubuntu-24.04 --replicas 1 --cpu-cores 2 --memory-mib 2048 --storage-gib 20 --reuse require — Create one ordinary containerd/runc compute definition with exact reserved resources; existing eligible project capacity is required.
+fz deploy init --runtime kata-snp --os ubuntu-26.04 --replicas 1 --cpu-cores 2 --memory-mib 4096 --storage-gib 40 --reuse prefer — Create one Kata QEMU SEV-SNP definition; reuse eligible capacity first, then provisioning still requires an explicit approved plan and spend ceiling.
 fz deploy compile — Compile and validate TypeScript deployment intent into .fz/deploy.plan.json.
 fz deploy check — Refuse stale plans, unsafe provider/action coordinates and unresolved deployment blockers.
 fz bootstrap platform bundle --root /absolute/api --branch dev --output /secure/forgezero/development/api.bundle — Build one verified release-generation-one source bundle without a Git credential.
@@ -97,6 +99,8 @@ fz status — Read installed service and bootstrap evidence.
 ```text
 bun add -g @forgezero/agent
 fz deploy init
+fz deploy init --runtime containerd --os ubuntu-24.04 --replicas 1 --cpu-cores 2 --memory-mib 2048 --storage-gib 20 --reuse require
+fz deploy init --runtime kata-snp --os ubuntu-26.04 --replicas 1 --cpu-cores 2 --memory-mib 4096 --storage-gib 40 --reuse prefer
 fz deploy compile
 fz deploy check
 fz bootstrap platform bundle --root /absolute/api --branch dev --output /secure/forgezero/development/api.bundle
@@ -1402,7 +1406,7 @@ await runDeploymentPlan({
 <a id="forgezero-agent-deploy-compiler"></a>
 ## @forgezero/agent/deploy-compiler
 
-Explicit developer/CI compiler from forgezero.deploy.ts to canonical .fz/deploy.plan.json; never used to execute project TypeScript in production. This entry exposes 7 named value exports and 1 named type export. The generated import block lists one name per line for scanning and copying; keep only the names used by your file.
+Explicit developer/CI compiler from forgezero.deploy.ts to canonical .fz/deploy.plan.json; never used to execute project TypeScript in production. This entry exposes 7 named value exports and 3 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 {
@@ -1417,6 +1421,8 @@ import {
 
 import type {
   DeploymentCompilation,
+  DeploymentInitOptions,
+  DeploymentInitRuntime,
 } from '@forgezero/agent/deploy-compiler';
 ```
 

package/dist/agent-heartbeat.js

@@ -750,7 +750,7 @@ async function postSignedNode(options, path, body) {
 }
 
 // src/version.ts
-var VERSION3 = "0.1.81";
+var VERSION3 = "0.1.83";
 
 // 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.81";
+var VERSION = "0.1.83";
 
 // 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/deploy-compiler.d.ts

@@ -8,11 +8,24 @@ export interface DeploymentCompilation {
     digest: `sha256:${string}`;
     changed: boolean;
 }
-export declare function defaultTypeScriptDeployment(name: string): string;
+export type DeploymentInitRuntime = 'native' | 'containerd' | 'kata-snp';
+export interface DeploymentInitOptions {
+    runtime?: DeploymentInitRuntime;
+    operatingSystem?: 'ubuntu-24.04' | 'ubuntu-26.04';
+    isolation?: 'standard' | 'sev-snp';
+    replicas?: number;
+    cpuCores?: number;
+    memoryMiB?: number;
+    storageGiB?: number;
+    sharing?: 'exclusive' | 'shared';
+    reuse?: 'require' | 'prefer';
+    profile?: string;
+}
+export declare function defaultTypeScriptDeployment(name: string, options?: DeploymentInitOptions): string;
 export declare function initializeTypeScriptDeployment(rootValue: string, options: {
     name: string;
     force?: boolean;
-}): string;
+} & DeploymentInitOptions): string;
 export declare function loadDeploymentSource(root: string, sourceFile?: string): Promise<unknown>;
 export declare function compileDeploymentProject(rootValue: string, options?: {
     sourceFile?: string;

package/dist/deploy-compiler.js

@@ -1142,46 +1142,82 @@ function parseDeploymentPlan(value) {
 }
 
 // src/deploy-compiler.ts
-import { existsSync, lstatSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "fs";
-import { dirname, isAbsolute, relative, resolve, sep } from "path";
-import { pathToFileURL } from "url";
+import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "path";
+import { fileURLToPath, pathToFileURL } from "url";
 var DEPLOY_SOURCE_FILE = "forgezero.deploy.ts";
 var DEPLOY_PLAN_FILE = ".fz/deploy.plan.json";
 function safeName(value) {
   const result = value.toLowerCase().replace(/^@[^/]+\//, "").replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 63);
   return /^[a-z]/.test(result) ? result : `app-${result || "service"}`;
 }
-function defaultTypeScriptDeployment(name) {
-  return `import { actions, application, defineDeployment, input, providers, stage, target, workflow } from '@forgezero/agent/deploy';
-
-export default defineDeployment({
-	apiVersion: 'deploy.forgezero.net/v1',
-	kind: 'Deployment',
-	metadata: { name: '${safeName(name)}' },
-	spec: {
-		security: { attestation: 'preferred' },
-		inputs: { replicas: input.integer({ minimum: 1, maximum: 32, default: 1 }) },
-		targets: {
-			app: target.compute({
-				profiles: ['app'],
-				replicas: { minimum: 1, desired: input.ref('replicas'), maximum: 32 },
-				resources: { cpuCores: 1, memoryMiB: 512, storageGiB: 8 },
-				os: 'ubuntu-24.04', runtime: 'native', isolation: 'standard', reuse: 'require'
-			})
-		},
-		requirements: { bun: providers.bun.require() },
-		components: {
+function initCoordinates(options) {
+  const runtime = options.runtime ?? "native";
+  const isolation = options.isolation ?? (runtime === "kata-snp" ? "sev-snp" : "standard");
+  const operatingSystem = options.operatingSystem ?? (isolation === "sev-snp" ? "ubuntu-26.04" : "ubuntu-24.04");
+  const result = {
+    runtime,
+    isolation,
+    operatingSystem,
+    replicas: options.replicas ?? 1,
+    cpuCores: options.cpuCores ?? 1,
+    memoryMiB: options.memoryMiB ?? 512,
+    storageGiB: options.storageGiB ?? 8,
+    sharing: options.sharing ?? "exclusive",
+    reuse: options.reuse ?? "require",
+    profile: options.profile ?? "app"
+  };
+  if (!/^[a-z][a-z0-9-]{0,62}$/.test(result.profile))
+    throw new Error("deployment profile must be a lowercase typed name");
+  if (!Number.isSafeInteger(result.replicas) || result.replicas < 1 || result.replicas > 1024)
+    throw new Error("deployment replicas must be an integer from 1 to 1024");
+  if (!Number.isSafeInteger(result.cpuCores) || result.cpuCores < 1 || result.cpuCores > 1024)
+    throw new Error("deployment CPU cores must be an integer from 1 to 1024");
+  if (!Number.isSafeInteger(result.memoryMiB) || result.memoryMiB < 128 || result.memoryMiB > 4194304)
+    throw new Error("deployment memory must be an integer from 128 to 4194304 MiB");
+  if (!Number.isSafeInteger(result.storageGiB) || result.storageGiB < 1 || result.storageGiB > 1048576)
+    throw new Error("deployment storage must be an integer from 1 to 1048576 GiB");
+  if (runtime === "kata-snp" && isolation !== "sev-snp")
+    throw new Error("kata-snp requires sev-snp isolation");
+  if (runtime === "containerd" && isolation === "sev-snp")
+    throw new Error("containerd runc cannot provide sev-snp; use kata-snp");
+  if (isolation === "sev-snp" && operatingSystem !== "ubuntu-26.04")
+    throw new Error("sev-snp requires ubuntu-26.04");
+  if (runtime === "native" && result.sharing !== "exclusive")
+    throw new Error("native deployments require exclusive compute");
+  return result;
+}
+function defaultTypeScriptDeployment(name, options = {}) {
+  const selected = initCoordinates(options);
+  const execution = selected.runtime === "native" ? "native" : selected.runtime === "containerd" ? "oci-runc" : "oci-kata-qemu-snp";
+  const hostPackageVersion = selected.operatingSystem === "ubuntu-24.04" ? "ubuntu-24.04" : "ubuntu-26.04";
+  const requirementBlock = selected.runtime === "native" ? `bun: providers.bun.require()` : selected.runtime === "containerd" ? `containerd: providers.containerd.require({ version: '${hostPackageVersion}' }),
+			nginx: providers.nginx.require({ version: '${hostPackageVersion}' })` : `containerd: providers.containerd.require(),
+			kata: providers.kata.require(),
+			nginx: providers.nginx.require()`;
+  const componentBlock = selected.runtime === "native" ? `
 			app: application({
 				target: 'app',
 				runtime: { kind: 'native', provider: 'forgezero.bun', requirement: 'bun', argv: ['/usr/local/bin/bun', 'run', 'start'] },
 				service: { protocol: 'http', port: 3000, health: { protocol: 'http', method: 'GET', path: '/health', expectedStatus: [200], timeoutMs: 5_000 } },
 				resources: {},
 				rollout: { strategy: 'direct' }
-			})
-		},
-		workflows: {
-			deploy: workflow({
-				stages: {
+			})` : `
+			app: application({
+				target: 'app',
+				runtime: {
+					kind: 'container', provider: '${selected.runtime === "containerd" ? "forgezero.containerd" : "forgezero.kata"}', requirement: '${selected.runtime === "containerd" ? "containerd" : "kata"}', runtimeClass: '${selected.runtime === "containerd" ? "runc" : "kata-qemu-snp"}',
+					image: { source: { kind: 'build', context: '.', dockerfile: 'Dockerfile' } },
+					security: { privileged: false, noNewPrivileges: true, root: 'read-only', dropCapabilities: ['ALL'] }
+				},
+				service: { protocol: 'http', port: 3000, health: { protocol: 'http', method: 'GET', path: '/health', expectedStatus: [200], timeoutMs: 5_000 } },
+				resources: { cpu: { limit: ${selected.cpuCores} }, memory: { limitMiB: ${selected.memoryMiB}, swap: 'disabled' }, pids: { limit: 256 } },
+				storage: [{ class: 'ephemeral', path: '/tmp', type: 'tmpfs', sizeMiB: ${Math.min(128, Math.max(16, Math.floor(selected.memoryMiB / 4)))} }],
+				network: { ingress: { exposure: 'loopback', stablePort: 3000 }, container: { mode: 'bridge', network: 'app' } },
+				rollout: { strategy: 'blue-green', proxy: 'nginx', drainMs: 30_000, automaticRollback: true }
+			})`;
+  const workflowBlock = selected.runtime === "native" ? `
 					build: stage({ strategy: { mode: 'sequential' }, steps: {
 						build: actions.exec.argv(
 							{ component: 'app', argv: ['/usr/local/bin/fz-agent', 'pipeline-todo', 'replace with the project build argv'] },
@@ -1196,7 +1232,42 @@ export default defineDeployment({
 					} }),
 					verify: stage({ dependsOn: ['release'], strategy: { mode: 'parallel' }, steps: {
 						health: actions.service.health({ component: 'app' }, { scope: { kind: 'each-target', target: 'app' }, timeoutMs: 30_000 })
-					} })
+					} })` : `
+					prepare: stage({ strategy: { mode: 'sequential' }, steps: {
+						software: actions.software.ensure({ requirements: [${selected.runtime === "containerd" ? "'containerd', 'nginx'" : "'containerd', 'kata', 'nginx'"}] }, { scope: { kind: 'each-target', target: 'app' }, timeoutMs: 900_000 }),
+						review: actions.exec.argv({ component: 'app', argv: ['/usr/local/bin/fz-agent', 'pipeline-todo', 'review the Dockerfile and container entrypoint'] }, { scope: { kind: 'release-executor' } })
+					} }),
+					build: stage({ dependsOn: ['prepare'], strategy: { mode: 'sequential' }, steps: {
+						image: actions.container.build({ component: 'app' }, { scope: { kind: 'release-executor' }, timeoutMs: 900_000 })
+					} }),
+					release: stage({ dependsOn: ['build'], strategy: { mode: 'blue-green', maximumConcurrency: 1, minimumHealthy: 1 }, steps: {
+						promote: actions.service.promote({ component: 'app', imageDigest: { $ref: 'steps.image.outputs.digest' } }, { scope: { kind: 'each-target', target: 'app' }, timeoutMs: 180_000 })
+					} }),
+					verify: stage({ dependsOn: ['release'], strategy: { mode: 'parallel' }, steps: {
+						health: actions.service.health({ component: 'app' }, { scope: { kind: 'each-target', target: 'app' }, timeoutMs: 30_000 })
+					} })`;
+  return `import { actions, application, defineDeployment, providers, stage, target, workflow } from '@forgezero/agent/deploy';
+
+export default defineDeployment({
+	apiVersion: 'deploy.forgezero.net/v1',
+	kind: 'Deployment',
+	metadata: { name: '${safeName(name)}' },
+	spec: {
+		security: { attestation: '${selected.isolation === "sev-snp" ? "required" : "preferred"}' },
+		targets: {
+			app: target.compute({
+				profiles: ['${selected.profile}'], replicas: ${selected.replicas},
+				resources: { cpuCores: ${selected.cpuCores}, memoryMiB: ${selected.memoryMiB}, storageGiB: ${selected.storageGiB} },
+				os: '${selected.operatingSystem}', runtime: '${execution}', isolation: '${selected.isolation}',
+				sharing: '${selected.sharing}', reuse: '${selected.reuse}'
+			})
+		},
+		requirements: { ${requirementBlock} },
+		components: {${componentBlock}
+		},
+		workflows: {
+			deploy: workflow({
+				stages: {${workflowBlock}
 				}
 			})
 		}
@@ -1208,7 +1279,7 @@ function initializeTypeScriptDeployment(rootValue, options) {
   const path = localPath(rootValue, DEPLOY_SOURCE_FILE, "deployment source");
   if (existsSync(path) && !options.force)
     throw new Error(`${DEPLOY_SOURCE_FILE} already exists; use --force only when replacing it deliberately`);
-  writeFileSync(path, defaultTypeScriptDeployment(options.name), { mode: 420, flag: options.force ? "w" : "wx" });
+  writeFileSync(path, defaultTypeScriptDeployment(options.name, options), { mode: 420, flag: options.force ? "w" : "wx" });
   return path;
 }
 function inside(root, path) {
@@ -1229,10 +1300,35 @@ async function loadDeploymentSource(root, sourceFile = DEPLOY_SOURCE_FILE) {
   const status = lstatSync(source);
   if (!status.isFile() || status.isSymbolicLink() || status.size > 2 * 1024 * 1024)
     throw new Error("deployment source must be one bounded regular file");
-  const module = await import(`${pathToFileURL(source).href}?forgezero=${status.mtimeMs}`);
-  if (module.default === undefined)
-    throw new Error(`${sourceFile} must export one default deployment definition`);
-  return module.default;
+  const builtDeploy = new URL("./deploy.js", import.meta.url);
+  const sourceDeploy = new URL("./deploy.ts", import.meta.url);
+  const deployModule = existsSync(fileURLToPath(builtDeploy)) ? builtDeploy.href : sourceDeploy.href;
+  const result = await Bun.build({
+    entrypoints: [source],
+    target: "bun",
+    format: "esm",
+    minify: false,
+    plugins: [{
+      name: "forgezero-deploy-authoring",
+      setup(builder) {
+        builder.onResolve({ filter: /^@forgezero\/agent\/deploy$/ }, () => ({ path: fileURLToPath(deployModule) }));
+      }
+    }]
+  });
+  if (!result.success || result.outputs.length !== 1) {
+    throw new Error(`deployment source compilation failed: ${result.logs.map((entry) => entry.message).join("; ")}`);
+  }
+  const directory = mkdtempSync(join(tmpdir(), "forgezero-deploy-compile-"));
+  const compiled = join(directory, "deployment.mjs");
+  try {
+    writeFileSync(compiled, Buffer.from(await result.outputs[0].arrayBuffer()), { mode: 384, flag: "wx" });
+    const module = await import(`${pathToFileURL(compiled).href}?forgezero=${status.mtimeMs}`);
+    if (module.default === undefined)
+      throw new Error(`${sourceFile} must export one default deployment definition`);
+    return module.default;
+  } finally {
+    rmSync(directory, { recursive: true, force: true });
+  }
 }
 async function compileDeploymentProject(rootValue, options = {}) {
   const root = resolve(rootValue);

package/dist/fz-agent.js

@@ -9331,7 +9331,7 @@ async function writeAndCloseProcessInput(input, value) {
 }
 
 // src/version.ts
-var VERSION2 = "0.1.81";
+var VERSION2 = "0.1.83";
 
 // src/ssh-bootstrap.ts
 class SshBootstrapError extends Error {