@forgezero/agent 0.1.113 → 0.1.115

package/dist/agent-heartbeat.js

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

package/dist/bootstrap.js

@@ -1460,7 +1460,7 @@ var UPDATE_RETRY_BASE_MS = 5 * 60000;
 var UPDATE_RETRY_MAX_MS = 24 * 60 * 60000;
 
 // src/version.ts
-var VERSION = "0.1.113";
+var VERSION = "0.1.115";
 
 // src/software.ts
 var PINNED_BUN_VERSION = "1.3.14";
@@ -1504,6 +1504,44 @@ var DOCKER_DAEMON_CONFIG = `${JSON.stringify({
 import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync2, readdirSync, realpathSync, renameSync as renameSync2, rmSync as rmSync2, writeFileSync as writeFileSync2 } from "fs";
 import { dirname as dirname3, join as join2, resolve as resolve3, sep } from "path";
 
+// src/capacity-calibration.ts
+function localCalibrationEndpoint(value) {
+  const endpoint2 = new URL(value);
+  if (endpoint2.protocol !== "http:" || !["localhost", "127.0.0.1", "[::1]"].includes(endpoint2.hostname) || !endpoint2.port || endpoint2.username || endpoint2.password || endpoint2.hash) {
+    throw new Error("Capacity calibration requires an explicit loopback HTTP endpoint and port.");
+  }
+  return endpoint2;
+}
+function validateCapacityCalibrationOptions(options) {
+  const endpoint2 = localCalibrationEndpoint(options.endpoint);
+  const maxConcurrency = options.maxConcurrency ?? 256;
+  const requestsPerWorker = options.requestsPerWorker ?? 8;
+  const maximumRequestsPerWorker = options.maximumRequestsPerWorker ?? 100;
+  const maxP95Ms = options.maxP95Ms ?? 250;
+  const maxErrorRate = options.maxErrorRate ?? 0.01;
+  const safetyRatio = options.safetyRatio ?? 0.8;
+  const requestTimeoutMs = options.requestTimeoutMs ?? 5000;
+  const minimumStageDurationMs = options.minimumStageDurationMs ?? 5000;
+  const maxCpuUtilizationPercent = options.maxCpuUtilizationPercent ?? 90;
+  const maxMemoryUtilizationPercent = options.maxMemoryUtilizationPercent ?? 90;
+  if (!Number.isSafeInteger(maxConcurrency) || maxConcurrency < 1 || maxConcurrency > 4096 || !Number.isSafeInteger(requestsPerWorker) || requestsPerWorker < 2 || requestsPerWorker > 100 || !Number.isSafeInteger(maximumRequestsPerWorker) || maximumRequestsPerWorker < requestsPerWorker || maximumRequestsPerWorker > 100 || !Number.isFinite(maxP95Ms) || maxP95Ms < 1 || !Number.isFinite(maxErrorRate) || maxErrorRate < 0 || maxErrorRate > 0.2 || !Number.isFinite(safetyRatio) || safetyRatio < 0.25 || safetyRatio > 0.95 || !Number.isSafeInteger(requestTimeoutMs) || requestTimeoutMs < 100 || requestTimeoutMs > 30000 || !Number.isSafeInteger(minimumStageDurationMs) || minimumStageDurationMs < 100 || minimumStageDurationMs > 60000 || !Number.isFinite(maxCpuUtilizationPercent) || maxCpuUtilizationPercent < 25 || maxCpuUtilizationPercent > 100 || !Number.isFinite(maxMemoryUtilizationPercent) || maxMemoryUtilizationPercent < 25 || maxMemoryUtilizationPercent > 100) {
+    throw new Error("Capacity calibration bounds are invalid.");
+  }
+  return {
+    endpoint: endpoint2,
+    maxConcurrency,
+    requestsPerWorker,
+    maximumRequestsPerWorker,
+    maxP95Ms,
+    maxErrorRate,
+    safetyRatio,
+    requestTimeoutMs,
+    minimumStageDurationMs,
+    maxCpuUtilizationPercent,
+    maxMemoryUtilizationPercent
+  };
+}
+
 // src/definition.ts
 var RESERVED_STEP_ENV = new Set([
   "PATH",

package/dist/capacity-calibration.d.ts

@@ -39,7 +39,10 @@ export interface CapacityCalibration {
 export interface CapacityCalibrationOptions {
     endpoint: string;
     maxConcurrency?: number;
+    /** Minimum samples per worker before a stage may finish. */
     requestsPerWorker?: number;
+    /** Hard request budget per worker. Defaults to 100 and can never exceed 100. */
+    maximumRequestsPerWorker?: number;
     maxP95Ms?: number;
     maxErrorRate?: number;
     /** Defaults to 0.8: use at most 80% of measured sustainable RPS. */
@@ -53,6 +56,7 @@ export interface ValidatedCapacityCalibrationOptions {
     endpoint: URL;
     maxConcurrency: number;
     requestsPerWorker: number;
+    maximumRequestsPerWorker: number;
     maxP95Ms: number;
     maxErrorRate: number;
     safetyRatio: number;

package/dist/capacity-calibration.js

@@ -27,6 +27,7 @@ function validateCapacityCalibrationOptions(options) {
   const endpoint = localCalibrationEndpoint(options.endpoint);
   const maxConcurrency = options.maxConcurrency ?? 256;
   const requestsPerWorker = options.requestsPerWorker ?? 8;
+  const maximumRequestsPerWorker = options.maximumRequestsPerWorker ?? 100;
   const maxP95Ms = options.maxP95Ms ?? 250;
   const maxErrorRate = options.maxErrorRate ?? 0.01;
   const safetyRatio = options.safetyRatio ?? 0.8;
@@ -34,13 +35,14 @@ function validateCapacityCalibrationOptions(options) {
   const minimumStageDurationMs = options.minimumStageDurationMs ?? 5000;
   const maxCpuUtilizationPercent = options.maxCpuUtilizationPercent ?? 90;
   const maxMemoryUtilizationPercent = options.maxMemoryUtilizationPercent ?? 90;
-  if (!Number.isSafeInteger(maxConcurrency) || maxConcurrency < 1 || maxConcurrency > 4096 || !Number.isSafeInteger(requestsPerWorker) || requestsPerWorker < 2 || requestsPerWorker > 100 || !Number.isFinite(maxP95Ms) || maxP95Ms < 1 || !Number.isFinite(maxErrorRate) || maxErrorRate < 0 || maxErrorRate > 0.2 || !Number.isFinite(safetyRatio) || safetyRatio < 0.25 || safetyRatio > 0.95 || !Number.isSafeInteger(requestTimeoutMs) || requestTimeoutMs < 100 || requestTimeoutMs > 30000 || !Number.isSafeInteger(minimumStageDurationMs) || minimumStageDurationMs < 100 || minimumStageDurationMs > 60000 || !Number.isFinite(maxCpuUtilizationPercent) || maxCpuUtilizationPercent < 25 || maxCpuUtilizationPercent > 100 || !Number.isFinite(maxMemoryUtilizationPercent) || maxMemoryUtilizationPercent < 25 || maxMemoryUtilizationPercent > 100) {
+  if (!Number.isSafeInteger(maxConcurrency) || maxConcurrency < 1 || maxConcurrency > 4096 || !Number.isSafeInteger(requestsPerWorker) || requestsPerWorker < 2 || requestsPerWorker > 100 || !Number.isSafeInteger(maximumRequestsPerWorker) || maximumRequestsPerWorker < requestsPerWorker || maximumRequestsPerWorker > 100 || !Number.isFinite(maxP95Ms) || maxP95Ms < 1 || !Number.isFinite(maxErrorRate) || maxErrorRate < 0 || maxErrorRate > 0.2 || !Number.isFinite(safetyRatio) || safetyRatio < 0.25 || safetyRatio > 0.95 || !Number.isSafeInteger(requestTimeoutMs) || requestTimeoutMs < 100 || requestTimeoutMs > 30000 || !Number.isSafeInteger(minimumStageDurationMs) || minimumStageDurationMs < 100 || minimumStageDurationMs > 60000 || !Number.isFinite(maxCpuUtilizationPercent) || maxCpuUtilizationPercent < 25 || maxCpuUtilizationPercent > 100 || !Number.isFinite(maxMemoryUtilizationPercent) || maxMemoryUtilizationPercent < 25 || maxMemoryUtilizationPercent > 100) {
     throw new Error("Capacity calibration bounds are invalid.");
   }
   return {
     endpoint,
     maxConcurrency,
     requestsPerWorker,
+    maximumRequestsPerWorker,
     maxP95Ms,
     maxErrorRate,
     safetyRatio,
@@ -50,7 +52,7 @@ function validateCapacityCalibrationOptions(options) {
     maxMemoryUtilizationPercent
   };
 }
-async function stage(endpoint, concurrency, requestsPerWorker, timeoutMs, minimumDurationMs, fetcher, sampler) {
+async function stage(endpoint, concurrency, requestsPerWorker, maximumRequestsPerWorker, timeoutMs, minimumDurationMs, fetcher, sampler) {
   const latencies = [];
   let succeeded = 0;
   let failed = 0;
@@ -59,7 +61,7 @@ async function stage(endpoint, concurrency, requestsPerWorker, timeoutMs, minimu
   const started = performance.now();
   await Promise.all(Array.from({ length: concurrency }, async () => {
     let request = 0;
-    while (request < requestsPerWorker || performance.now() - started < minimumDurationMs) {
+    while (request < maximumRequestsPerWorker && (request < requestsPerWorker || performance.now() - started < minimumDurationMs)) {
       request += 1;
       const requestStarted = performance.now();
       try {
@@ -118,6 +120,7 @@ async function calibrateHttpConcurrency(options, fetcher = fetch, sampler = host
     safetyRatio,
     requestTimeoutMs: timeoutMs,
     minimumStageDurationMs,
+    maximumRequestsPerWorker,
     maxCpuUtilizationPercent,
     maxMemoryUtilizationPercent
   } = validateCapacityCalibrationOptions(options);
@@ -125,7 +128,7 @@ async function calibrateHttpConcurrency(options, fetcher = fetch, sampler = host
   let lastSafe;
   let stopReason = "maximum-tested";
   for (let concurrency = 1;; concurrency = Math.min(maxConcurrency, concurrency * 2)) {
-    const measured = await stage(endpoint, concurrency, requestsPerWorker, timeoutMs, minimumStageDurationMs, fetcher, sampler);
+    const measured = await stage(endpoint, concurrency, requestsPerWorker, maximumRequestsPerWorker, timeoutMs, minimumStageDurationMs, fetcher, sampler);
     stages.push(measured);
     const previous = stages.at(-2);
     const throughputRegressed = Boolean(previous && concurrency > 1 && measured.successfulRequestsPerSecond < previous.successfulRequestsPerSecond * 0.9);

package/dist/definition.js

@@ -572,6 +572,7 @@ function validateCapacityCalibrationOptions(options) {
   const endpoint = localCalibrationEndpoint(options.endpoint);
   const maxConcurrency = options.maxConcurrency ?? 256;
   const requestsPerWorker = options.requestsPerWorker ?? 8;
+  const maximumRequestsPerWorker = options.maximumRequestsPerWorker ?? 100;
   const maxP95Ms = options.maxP95Ms ?? 250;
   const maxErrorRate = options.maxErrorRate ?? 0.01;
   const safetyRatio = options.safetyRatio ?? 0.8;
@@ -579,13 +580,14 @@ function validateCapacityCalibrationOptions(options) {
   const minimumStageDurationMs = options.minimumStageDurationMs ?? 5000;
   const maxCpuUtilizationPercent = options.maxCpuUtilizationPercent ?? 90;
   const maxMemoryUtilizationPercent = options.maxMemoryUtilizationPercent ?? 90;
-  if (!Number.isSafeInteger(maxConcurrency) || maxConcurrency < 1 || maxConcurrency > 4096 || !Number.isSafeInteger(requestsPerWorker) || requestsPerWorker < 2 || requestsPerWorker > 100 || !Number.isFinite(maxP95Ms) || maxP95Ms < 1 || !Number.isFinite(maxErrorRate) || maxErrorRate < 0 || maxErrorRate > 0.2 || !Number.isFinite(safetyRatio) || safetyRatio < 0.25 || safetyRatio > 0.95 || !Number.isSafeInteger(requestTimeoutMs) || requestTimeoutMs < 100 || requestTimeoutMs > 30000 || !Number.isSafeInteger(minimumStageDurationMs) || minimumStageDurationMs < 100 || minimumStageDurationMs > 60000 || !Number.isFinite(maxCpuUtilizationPercent) || maxCpuUtilizationPercent < 25 || maxCpuUtilizationPercent > 100 || !Number.isFinite(maxMemoryUtilizationPercent) || maxMemoryUtilizationPercent < 25 || maxMemoryUtilizationPercent > 100) {
+  if (!Number.isSafeInteger(maxConcurrency) || maxConcurrency < 1 || maxConcurrency > 4096 || !Number.isSafeInteger(requestsPerWorker) || requestsPerWorker < 2 || requestsPerWorker > 100 || !Number.isSafeInteger(maximumRequestsPerWorker) || maximumRequestsPerWorker < requestsPerWorker || maximumRequestsPerWorker > 100 || !Number.isFinite(maxP95Ms) || maxP95Ms < 1 || !Number.isFinite(maxErrorRate) || maxErrorRate < 0 || maxErrorRate > 0.2 || !Number.isFinite(safetyRatio) || safetyRatio < 0.25 || safetyRatio > 0.95 || !Number.isSafeInteger(requestTimeoutMs) || requestTimeoutMs < 100 || requestTimeoutMs > 30000 || !Number.isSafeInteger(minimumStageDurationMs) || minimumStageDurationMs < 100 || minimumStageDurationMs > 60000 || !Number.isFinite(maxCpuUtilizationPercent) || maxCpuUtilizationPercent < 25 || maxCpuUtilizationPercent > 100 || !Number.isFinite(maxMemoryUtilizationPercent) || maxMemoryUtilizationPercent < 25 || maxMemoryUtilizationPercent > 100) {
     throw new Error("Capacity calibration bounds are invalid.");
   }
   return {
     endpoint,
     maxConcurrency,
     requestsPerWorker,
+    maximumRequestsPerWorker,
     maxP95Ms,
     maxErrorRate,
     safetyRatio,
@@ -595,7 +597,7 @@ function validateCapacityCalibrationOptions(options) {
     maxMemoryUtilizationPercent
   };
 }
-async function stage(endpoint, concurrency, requestsPerWorker, timeoutMs, minimumDurationMs, fetcher, sampler) {
+async function stage(endpoint, concurrency, requestsPerWorker, maximumRequestsPerWorker, timeoutMs, minimumDurationMs, fetcher, sampler) {
   const latencies = [];
   let succeeded = 0;
   let failed = 0;
@@ -604,7 +606,7 @@ async function stage(endpoint, concurrency, requestsPerWorker, timeoutMs, minimu
   const started = performance.now();
   await Promise.all(Array.from({ length: concurrency }, async () => {
     let request = 0;
-    while (request < requestsPerWorker || performance.now() - started < minimumDurationMs) {
+    while (request < maximumRequestsPerWorker && (request < requestsPerWorker || performance.now() - started < minimumDurationMs)) {
       request += 1;
       const requestStarted = performance.now();
       try {
@@ -663,6 +665,7 @@ async function calibrateHttpConcurrency(options, fetcher = fetch, sampler = host
     safetyRatio,
     requestTimeoutMs: timeoutMs,
     minimumStageDurationMs,
+    maximumRequestsPerWorker,
     maxCpuUtilizationPercent,
     maxMemoryUtilizationPercent
   } = validateCapacityCalibrationOptions(options);
@@ -670,7 +673,7 @@ async function calibrateHttpConcurrency(options, fetcher = fetch, sampler = host
   let lastSafe;
   let stopReason = "maximum-tested";
   for (let concurrency = 1;; concurrency = Math.min(maxConcurrency, concurrency * 2)) {
-    const measured = await stage(endpoint, concurrency, requestsPerWorker, timeoutMs, minimumStageDurationMs, fetcher, sampler);
+    const measured = await stage(endpoint, concurrency, requestsPerWorker, maximumRequestsPerWorker, timeoutMs, minimumStageDurationMs, fetcher, sampler);
     stages.push(measured);
     const previous = stages.at(-2);
     const throughputRegressed = Boolean(previous && concurrency > 1 && measured.successfulRequestsPerSecond < previous.successfulRequestsPerSecond * 0.9);
@@ -771,6 +774,7 @@ function capacityCalibration(value, where) {
     "endpoint",
     "maxConcurrency",
     "requestsPerWorker",
+    "maximumRequestsPerWorker",
     "maxP95Ms",
     "maxErrorRate",
     "safetyRatio",
@@ -799,6 +803,7 @@ function capacityCalibration(value, where) {
     ...Object.fromEntries([
       "maxConcurrency",
       "requestsPerWorker",
+      "maximumRequestsPerWorker",
       "maxP95Ms",
       "maxErrorRate",
       "safetyRatio",

package/dist/deploy-compiler.js

@@ -132,6 +132,44 @@ function validateBuiltInProvider(requirement2, where) {
     throw new Error(`${where} ArangoDB config is invalid`);
 }
 
+// src/capacity-calibration.ts
+function localCalibrationEndpoint(value) {
+  const endpoint = new URL(value);
+  if (endpoint.protocol !== "http:" || !["localhost", "127.0.0.1", "[::1]"].includes(endpoint.hostname) || !endpoint.port || endpoint.username || endpoint.password || endpoint.hash) {
+    throw new Error("Capacity calibration requires an explicit loopback HTTP endpoint and port.");
+  }
+  return endpoint;
+}
+function validateCapacityCalibrationOptions(options) {
+  const endpoint = localCalibrationEndpoint(options.endpoint);
+  const maxConcurrency = options.maxConcurrency ?? 256;
+  const requestsPerWorker = options.requestsPerWorker ?? 8;
+  const maximumRequestsPerWorker = options.maximumRequestsPerWorker ?? 100;
+  const maxP95Ms = options.maxP95Ms ?? 250;
+  const maxErrorRate = options.maxErrorRate ?? 0.01;
+  const safetyRatio = options.safetyRatio ?? 0.8;
+  const requestTimeoutMs = options.requestTimeoutMs ?? 5000;
+  const minimumStageDurationMs = options.minimumStageDurationMs ?? 5000;
+  const maxCpuUtilizationPercent = options.maxCpuUtilizationPercent ?? 90;
+  const maxMemoryUtilizationPercent = options.maxMemoryUtilizationPercent ?? 90;
+  if (!Number.isSafeInteger(maxConcurrency) || maxConcurrency < 1 || maxConcurrency > 4096 || !Number.isSafeInteger(requestsPerWorker) || requestsPerWorker < 2 || requestsPerWorker > 100 || !Number.isSafeInteger(maximumRequestsPerWorker) || maximumRequestsPerWorker < requestsPerWorker || maximumRequestsPerWorker > 100 || !Number.isFinite(maxP95Ms) || maxP95Ms < 1 || !Number.isFinite(maxErrorRate) || maxErrorRate < 0 || maxErrorRate > 0.2 || !Number.isFinite(safetyRatio) || safetyRatio < 0.25 || safetyRatio > 0.95 || !Number.isSafeInteger(requestTimeoutMs) || requestTimeoutMs < 100 || requestTimeoutMs > 30000 || !Number.isSafeInteger(minimumStageDurationMs) || minimumStageDurationMs < 100 || minimumStageDurationMs > 60000 || !Number.isFinite(maxCpuUtilizationPercent) || maxCpuUtilizationPercent < 25 || maxCpuUtilizationPercent > 100 || !Number.isFinite(maxMemoryUtilizationPercent) || maxMemoryUtilizationPercent < 25 || maxMemoryUtilizationPercent > 100) {
+    throw new Error("Capacity calibration bounds are invalid.");
+  }
+  return {
+    endpoint,
+    maxConcurrency,
+    requestsPerWorker,
+    maximumRequestsPerWorker,
+    maxP95Ms,
+    maxErrorRate,
+    safetyRatio,
+    requestTimeoutMs,
+    minimumStageDurationMs,
+    maxCpuUtilizationPercent,
+    maxMemoryUtilizationPercent
+  };
+}
+
 // src/deploy-plan.ts
 var DEPLOY_PLAN_FORMAT = "forgezero-deployment-plan";
 var DEPLOY_PLAN_VERSION = 1;
@@ -447,7 +485,7 @@ function validateComponent(value, where, targets, requirements) {
   const row2 = object(value, where);
   const selectedTarget = targets.get(String(row2.target)) ?? fail(`${where}.target`, "must name an existing target.");
   if (row2.kind === "application") {
-    exact3(row2, ["kind", "target", "runtime", "service", "resources", "storage", "network", "rollout"], where);
+    exact3(row2, ["kind", "target", "runtime", "service", "capacityCalibration", "resources", "storage", "network", "rollout"], where);
     const runtime = object(row2.runtime, `${where}.runtime`);
     const runtimeRequirement = requirements.get(String(runtime.requirement));
     if (!runtimeRequirement)
@@ -529,6 +567,33 @@ function validateComponent(value, where, targets, requirements) {
       fail(`${where}.service.websocket`, "must be a boolean.");
     if (service.maximumConnections !== undefined)
       integer(service.maximumConnections, `${where}.service.maximumConnections`, 1, 1e7);
+    if (row2.capacityCalibration !== undefined) {
+      const calibration = object(row2.capacityCalibration, `${where}.capacityCalibration`);
+      exact3(calibration, [
+        "path",
+        "maxConcurrency",
+        "requestsPerWorker",
+        "maximumRequestsPerWorker",
+        "maxP95Ms",
+        "maxErrorRate",
+        "safetyRatio",
+        "requestTimeoutMs",
+        "minimumStageDurationMs",
+        "maxCpuUtilizationPercent",
+        "maxMemoryUtilizationPercent"
+      ], `${where}.capacityCalibration`);
+      if (typeof calibration.path !== "string" || !HEALTH_PATH.test(calibration.path) || calibration.path.includes("..") || calibration.path.includes("//")) {
+        fail(`${where}.capacityCalibration.path`, "must be one bounded absolute loopback path.");
+      }
+      try {
+        validateCapacityCalibrationOptions({
+          ...calibration,
+          endpoint: `http://127.0.0.1:${String(service.port)}${calibration.path}`
+        });
+      } catch {
+        fail(`${where}.capacityCalibration`, "contains invalid bounds.");
+      }
+    }
     validateResources(row2.resources, `${where}.resources`);
     if (runtime.kind === "container") {
       const resources = object(row2.resources, `${where}.resources`);
@@ -991,6 +1056,15 @@ function compileDeployment(sourceValue) {
     named(componentName, "deployment.spec.components key");
     validateComponent(value, `deployment.spec.components.${componentName}`, targetDefinitions, requirementDefinitions);
   }
+  for (const targetName of targetNames) {
+    const calibrated = componentEntries.filter(([, component2]) => {
+      const candidate = component2;
+      return candidate.kind === "application" && candidate.target === targetName && candidate.capacityCalibration !== undefined;
+    });
+    if (calibrated.length > 1) {
+      fail(`deployment.spec.components`, `may calibrate at most one application on target ${targetName}.`);
+    }
+  }
   for (const [targetName, target] of targetDefinitions) {
     if (target.connectivity?.public?.mode !== "cloudflare-tunnel")
       continue;

package/dist/deploy-file.js

@@ -572,6 +572,7 @@ function validateCapacityCalibrationOptions(options) {
   const endpoint = localCalibrationEndpoint(options.endpoint);
   const maxConcurrency = options.maxConcurrency ?? 256;
   const requestsPerWorker = options.requestsPerWorker ?? 8;
+  const maximumRequestsPerWorker = options.maximumRequestsPerWorker ?? 100;
   const maxP95Ms = options.maxP95Ms ?? 250;
   const maxErrorRate = options.maxErrorRate ?? 0.01;
   const safetyRatio = options.safetyRatio ?? 0.8;
@@ -579,13 +580,14 @@ function validateCapacityCalibrationOptions(options) {
   const minimumStageDurationMs = options.minimumStageDurationMs ?? 5000;
   const maxCpuUtilizationPercent = options.maxCpuUtilizationPercent ?? 90;
   const maxMemoryUtilizationPercent = options.maxMemoryUtilizationPercent ?? 90;
-  if (!Number.isSafeInteger(maxConcurrency) || maxConcurrency < 1 || maxConcurrency > 4096 || !Number.isSafeInteger(requestsPerWorker) || requestsPerWorker < 2 || requestsPerWorker > 100 || !Number.isFinite(maxP95Ms) || maxP95Ms < 1 || !Number.isFinite(maxErrorRate) || maxErrorRate < 0 || maxErrorRate > 0.2 || !Number.isFinite(safetyRatio) || safetyRatio < 0.25 || safetyRatio > 0.95 || !Number.isSafeInteger(requestTimeoutMs) || requestTimeoutMs < 100 || requestTimeoutMs > 30000 || !Number.isSafeInteger(minimumStageDurationMs) || minimumStageDurationMs < 100 || minimumStageDurationMs > 60000 || !Number.isFinite(maxCpuUtilizationPercent) || maxCpuUtilizationPercent < 25 || maxCpuUtilizationPercent > 100 || !Number.isFinite(maxMemoryUtilizationPercent) || maxMemoryUtilizationPercent < 25 || maxMemoryUtilizationPercent > 100) {
+  if (!Number.isSafeInteger(maxConcurrency) || maxConcurrency < 1 || maxConcurrency > 4096 || !Number.isSafeInteger(requestsPerWorker) || requestsPerWorker < 2 || requestsPerWorker > 100 || !Number.isSafeInteger(maximumRequestsPerWorker) || maximumRequestsPerWorker < requestsPerWorker || maximumRequestsPerWorker > 100 || !Number.isFinite(maxP95Ms) || maxP95Ms < 1 || !Number.isFinite(maxErrorRate) || maxErrorRate < 0 || maxErrorRate > 0.2 || !Number.isFinite(safetyRatio) || safetyRatio < 0.25 || safetyRatio > 0.95 || !Number.isSafeInteger(requestTimeoutMs) || requestTimeoutMs < 100 || requestTimeoutMs > 30000 || !Number.isSafeInteger(minimumStageDurationMs) || minimumStageDurationMs < 100 || minimumStageDurationMs > 60000 || !Number.isFinite(maxCpuUtilizationPercent) || maxCpuUtilizationPercent < 25 || maxCpuUtilizationPercent > 100 || !Number.isFinite(maxMemoryUtilizationPercent) || maxMemoryUtilizationPercent < 25 || maxMemoryUtilizationPercent > 100) {
     throw new Error("Capacity calibration bounds are invalid.");
   }
   return {
     endpoint,
     maxConcurrency,
     requestsPerWorker,
+    maximumRequestsPerWorker,
     maxP95Ms,
     maxErrorRate,
     safetyRatio,
@@ -595,7 +597,7 @@ function validateCapacityCalibrationOptions(options) {
     maxMemoryUtilizationPercent
   };
 }
-async function stage(endpoint, concurrency, requestsPerWorker, timeoutMs, minimumDurationMs, fetcher, sampler) {
+async function stage(endpoint, concurrency, requestsPerWorker, maximumRequestsPerWorker, timeoutMs, minimumDurationMs, fetcher, sampler) {
   const latencies = [];
   let succeeded = 0;
   let failed = 0;
@@ -604,7 +606,7 @@ async function stage(endpoint, concurrency, requestsPerWorker, timeoutMs, minimu
   const started = performance.now();
   await Promise.all(Array.from({ length: concurrency }, async () => {
     let request = 0;
-    while (request < requestsPerWorker || performance.now() - started < minimumDurationMs) {
+    while (request < maximumRequestsPerWorker && (request < requestsPerWorker || performance.now() - started < minimumDurationMs)) {
       request += 1;
       const requestStarted = performance.now();
       try {
@@ -663,6 +665,7 @@ async function calibrateHttpConcurrency(options, fetcher = fetch, sampler = host
     safetyRatio,
     requestTimeoutMs: timeoutMs,
     minimumStageDurationMs,
+    maximumRequestsPerWorker,
     maxCpuUtilizationPercent,
     maxMemoryUtilizationPercent
   } = validateCapacityCalibrationOptions(options);
@@ -670,7 +673,7 @@ async function calibrateHttpConcurrency(options, fetcher = fetch, sampler = host
   let lastSafe;
   let stopReason = "maximum-tested";
   for (let concurrency = 1;; concurrency = Math.min(maxConcurrency, concurrency * 2)) {
-    const measured = await stage(endpoint, concurrency, requestsPerWorker, timeoutMs, minimumStageDurationMs, fetcher, sampler);
+    const measured = await stage(endpoint, concurrency, requestsPerWorker, maximumRequestsPerWorker, timeoutMs, minimumStageDurationMs, fetcher, sampler);
     stages.push(measured);
     const previous = stages.at(-2);
     const throughputRegressed = Boolean(previous && concurrency > 1 && measured.successfulRequestsPerSecond < previous.successfulRequestsPerSecond * 0.9);
@@ -771,6 +774,7 @@ function capacityCalibration(value, where) {
     "endpoint",
     "maxConcurrency",
     "requestsPerWorker",
+    "maximumRequestsPerWorker",
     "maxP95Ms",
     "maxErrorRate",
     "safetyRatio",
@@ -799,6 +803,7 @@ function capacityCalibration(value, where) {
     ...Object.fromEntries([
       "maxConcurrency",
       "requestsPerWorker",
+      "maximumRequestsPerWorker",
       "maxP95Ms",
       "maxErrorRate",
       "safetyRatio",

package/dist/deploy-plan-runner.js

@@ -132,6 +132,44 @@ function validateBuiltInProvider(requirement2, where) {
     throw new Error(`${where} ArangoDB config is invalid`);
 }
 
+// src/capacity-calibration.ts
+function localCalibrationEndpoint(value) {
+  const endpoint = new URL(value);
+  if (endpoint.protocol !== "http:" || !["localhost", "127.0.0.1", "[::1]"].includes(endpoint.hostname) || !endpoint.port || endpoint.username || endpoint.password || endpoint.hash) {
+    throw new Error("Capacity calibration requires an explicit loopback HTTP endpoint and port.");
+  }
+  return endpoint;
+}
+function validateCapacityCalibrationOptions(options) {
+  const endpoint = localCalibrationEndpoint(options.endpoint);
+  const maxConcurrency = options.maxConcurrency ?? 256;
+  const requestsPerWorker = options.requestsPerWorker ?? 8;
+  const maximumRequestsPerWorker = options.maximumRequestsPerWorker ?? 100;
+  const maxP95Ms = options.maxP95Ms ?? 250;
+  const maxErrorRate = options.maxErrorRate ?? 0.01;
+  const safetyRatio = options.safetyRatio ?? 0.8;
+  const requestTimeoutMs = options.requestTimeoutMs ?? 5000;
+  const minimumStageDurationMs = options.minimumStageDurationMs ?? 5000;
+  const maxCpuUtilizationPercent = options.maxCpuUtilizationPercent ?? 90;
+  const maxMemoryUtilizationPercent = options.maxMemoryUtilizationPercent ?? 90;
+  if (!Number.isSafeInteger(maxConcurrency) || maxConcurrency < 1 || maxConcurrency > 4096 || !Number.isSafeInteger(requestsPerWorker) || requestsPerWorker < 2 || requestsPerWorker > 100 || !Number.isSafeInteger(maximumRequestsPerWorker) || maximumRequestsPerWorker < requestsPerWorker || maximumRequestsPerWorker > 100 || !Number.isFinite(maxP95Ms) || maxP95Ms < 1 || !Number.isFinite(maxErrorRate) || maxErrorRate < 0 || maxErrorRate > 0.2 || !Number.isFinite(safetyRatio) || safetyRatio < 0.25 || safetyRatio > 0.95 || !Number.isSafeInteger(requestTimeoutMs) || requestTimeoutMs < 100 || requestTimeoutMs > 30000 || !Number.isSafeInteger(minimumStageDurationMs) || minimumStageDurationMs < 100 || minimumStageDurationMs > 60000 || !Number.isFinite(maxCpuUtilizationPercent) || maxCpuUtilizationPercent < 25 || maxCpuUtilizationPercent > 100 || !Number.isFinite(maxMemoryUtilizationPercent) || maxMemoryUtilizationPercent < 25 || maxMemoryUtilizationPercent > 100) {
+    throw new Error("Capacity calibration bounds are invalid.");
+  }
+  return {
+    endpoint,
+    maxConcurrency,
+    requestsPerWorker,
+    maximumRequestsPerWorker,
+    maxP95Ms,
+    maxErrorRate,
+    safetyRatio,
+    requestTimeoutMs,
+    minimumStageDurationMs,
+    maxCpuUtilizationPercent,
+    maxMemoryUtilizationPercent
+  };
+}
+
 // src/deploy-plan.ts
 var DEPLOY_PLAN_FORMAT = "forgezero-deployment-plan";
 var DEPLOY_PLAN_VERSION = 1;
@@ -447,7 +485,7 @@ function validateComponent(value, where, targets, requirements) {
   const row2 = object(value, where);
   const selectedTarget = targets.get(String(row2.target)) ?? fail(`${where}.target`, "must name an existing target.");
   if (row2.kind === "application") {
-    exact3(row2, ["kind", "target", "runtime", "service", "resources", "storage", "network", "rollout"], where);
+    exact3(row2, ["kind", "target", "runtime", "service", "capacityCalibration", "resources", "storage", "network", "rollout"], where);
     const runtime = object(row2.runtime, `${where}.runtime`);
     const runtimeRequirement = requirements.get(String(runtime.requirement));
     if (!runtimeRequirement)
@@ -529,6 +567,33 @@ function validateComponent(value, where, targets, requirements) {
       fail(`${where}.service.websocket`, "must be a boolean.");
     if (service.maximumConnections !== undefined)
       integer(service.maximumConnections, `${where}.service.maximumConnections`, 1, 1e7);
+    if (row2.capacityCalibration !== undefined) {
+      const calibration = object(row2.capacityCalibration, `${where}.capacityCalibration`);
+      exact3(calibration, [
+        "path",
+        "maxConcurrency",
+        "requestsPerWorker",
+        "maximumRequestsPerWorker",
+        "maxP95Ms",
+        "maxErrorRate",
+        "safetyRatio",
+        "requestTimeoutMs",
+        "minimumStageDurationMs",
+        "maxCpuUtilizationPercent",
+        "maxMemoryUtilizationPercent"
+      ], `${where}.capacityCalibration`);
+      if (typeof calibration.path !== "string" || !HEALTH_PATH.test(calibration.path) || calibration.path.includes("..") || calibration.path.includes("//")) {
+        fail(`${where}.capacityCalibration.path`, "must be one bounded absolute loopback path.");
+      }
+      try {
+        validateCapacityCalibrationOptions({
+          ...calibration,
+          endpoint: `http://127.0.0.1:${String(service.port)}${calibration.path}`
+        });
+      } catch {
+        fail(`${where}.capacityCalibration`, "contains invalid bounds.");
+      }
+    }
     validateResources(row2.resources, `${where}.resources`);
     if (runtime.kind === "container") {
       const resources = object(row2.resources, `${where}.resources`);
@@ -991,6 +1056,15 @@ function compileDeployment(sourceValue) {
     named(componentName, "deployment.spec.components key");
     validateComponent(value, `deployment.spec.components.${componentName}`, targetDefinitions, requirementDefinitions);
   }
+  for (const targetName of targetNames) {
+    const calibrated = componentEntries.filter(([, component2]) => {
+      const candidate = component2;
+      return candidate.kind === "application" && candidate.target === targetName && candidate.capacityCalibration !== undefined;
+    });
+    if (calibrated.length > 1) {
+      fail(`deployment.spec.components`, `may calibrate at most one application on target ${targetName}.`);
+    }
+  }
   for (const [targetName, target] of targetDefinitions) {
     if (target.connectivity?.public?.mode !== "cloudflare-tunnel")
       continue;

package/dist/deploy-plan.js

@@ -132,6 +132,44 @@ function validateBuiltInProvider(requirement2, where) {
     throw new Error(`${where} ArangoDB config is invalid`);
 }
 
+// src/capacity-calibration.ts
+function localCalibrationEndpoint(value) {
+  const endpoint = new URL(value);
+  if (endpoint.protocol !== "http:" || !["localhost", "127.0.0.1", "[::1]"].includes(endpoint.hostname) || !endpoint.port || endpoint.username || endpoint.password || endpoint.hash) {
+    throw new Error("Capacity calibration requires an explicit loopback HTTP endpoint and port.");
+  }
+  return endpoint;
+}
+function validateCapacityCalibrationOptions(options) {
+  const endpoint = localCalibrationEndpoint(options.endpoint);
+  const maxConcurrency = options.maxConcurrency ?? 256;
+  const requestsPerWorker = options.requestsPerWorker ?? 8;
+  const maximumRequestsPerWorker = options.maximumRequestsPerWorker ?? 100;
+  const maxP95Ms = options.maxP95Ms ?? 250;
+  const maxErrorRate = options.maxErrorRate ?? 0.01;
+  const safetyRatio = options.safetyRatio ?? 0.8;
+  const requestTimeoutMs = options.requestTimeoutMs ?? 5000;
+  const minimumStageDurationMs = options.minimumStageDurationMs ?? 5000;
+  const maxCpuUtilizationPercent = options.maxCpuUtilizationPercent ?? 90;
+  const maxMemoryUtilizationPercent = options.maxMemoryUtilizationPercent ?? 90;
+  if (!Number.isSafeInteger(maxConcurrency) || maxConcurrency < 1 || maxConcurrency > 4096 || !Number.isSafeInteger(requestsPerWorker) || requestsPerWorker < 2 || requestsPerWorker > 100 || !Number.isSafeInteger(maximumRequestsPerWorker) || maximumRequestsPerWorker < requestsPerWorker || maximumRequestsPerWorker > 100 || !Number.isFinite(maxP95Ms) || maxP95Ms < 1 || !Number.isFinite(maxErrorRate) || maxErrorRate < 0 || maxErrorRate > 0.2 || !Number.isFinite(safetyRatio) || safetyRatio < 0.25 || safetyRatio > 0.95 || !Number.isSafeInteger(requestTimeoutMs) || requestTimeoutMs < 100 || requestTimeoutMs > 30000 || !Number.isSafeInteger(minimumStageDurationMs) || minimumStageDurationMs < 100 || minimumStageDurationMs > 60000 || !Number.isFinite(maxCpuUtilizationPercent) || maxCpuUtilizationPercent < 25 || maxCpuUtilizationPercent > 100 || !Number.isFinite(maxMemoryUtilizationPercent) || maxMemoryUtilizationPercent < 25 || maxMemoryUtilizationPercent > 100) {
+    throw new Error("Capacity calibration bounds are invalid.");
+  }
+  return {
+    endpoint,
+    maxConcurrency,
+    requestsPerWorker,
+    maximumRequestsPerWorker,
+    maxP95Ms,
+    maxErrorRate,
+    safetyRatio,
+    requestTimeoutMs,
+    minimumStageDurationMs,
+    maxCpuUtilizationPercent,
+    maxMemoryUtilizationPercent
+  };
+}
+
 // src/deploy-plan.ts
 var DEPLOY_PLAN_FORMAT = "forgezero-deployment-plan";
 var DEPLOY_PLAN_VERSION = 1;
@@ -447,7 +485,7 @@ function validateComponent(value, where, targets, requirements) {
   const row2 = object(value, where);
   const selectedTarget = targets.get(String(row2.target)) ?? fail(`${where}.target`, "must name an existing target.");
   if (row2.kind === "application") {
-    exact3(row2, ["kind", "target", "runtime", "service", "resources", "storage", "network", "rollout"], where);
+    exact3(row2, ["kind", "target", "runtime", "service", "capacityCalibration", "resources", "storage", "network", "rollout"], where);
     const runtime = object(row2.runtime, `${where}.runtime`);
     const runtimeRequirement = requirements.get(String(runtime.requirement));
     if (!runtimeRequirement)
@@ -529,6 +567,33 @@ function validateComponent(value, where, targets, requirements) {
       fail(`${where}.service.websocket`, "must be a boolean.");
     if (service.maximumConnections !== undefined)
       integer(service.maximumConnections, `${where}.service.maximumConnections`, 1, 1e7);
+    if (row2.capacityCalibration !== undefined) {
+      const calibration = object(row2.capacityCalibration, `${where}.capacityCalibration`);
+      exact3(calibration, [
+        "path",
+        "maxConcurrency",
+        "requestsPerWorker",
+        "maximumRequestsPerWorker",
+        "maxP95Ms",
+        "maxErrorRate",
+        "safetyRatio",
+        "requestTimeoutMs",
+        "minimumStageDurationMs",
+        "maxCpuUtilizationPercent",
+        "maxMemoryUtilizationPercent"
+      ], `${where}.capacityCalibration`);
+      if (typeof calibration.path !== "string" || !HEALTH_PATH.test(calibration.path) || calibration.path.includes("..") || calibration.path.includes("//")) {
+        fail(`${where}.capacityCalibration.path`, "must be one bounded absolute loopback path.");
+      }
+      try {
+        validateCapacityCalibrationOptions({
+          ...calibration,
+          endpoint: `http://127.0.0.1:${String(service.port)}${calibration.path}`
+        });
+      } catch {
+        fail(`${where}.capacityCalibration`, "contains invalid bounds.");
+      }
+    }
     validateResources(row2.resources, `${where}.resources`);
     if (runtime.kind === "container") {
       const resources = object(row2.resources, `${where}.resources`);
@@ -991,6 +1056,15 @@ function compileDeployment(sourceValue) {
     named(componentName, "deployment.spec.components key");
     validateComponent(value, `deployment.spec.components.${componentName}`, targetDefinitions, requirementDefinitions);
   }
+  for (const targetName of targetNames) {
+    const calibrated = componentEntries.filter(([, component2]) => {
+      const candidate = component2;
+      return candidate.kind === "application" && candidate.target === targetName && candidate.capacityCalibration !== undefined;
+    });
+    if (calibrated.length > 1) {
+      fail(`deployment.spec.components`, `may calibrate at most one application on target ${targetName}.`);
+    }
+  }
   for (const [targetName, target] of targetDefinitions) {
     if (target.connectivity?.public?.mode !== "cloudflare-tunnel")
       continue;

package/dist/deploy.d.ts

@@ -340,6 +340,20 @@ export interface ApplicationComponent {
         websocket?: boolean;
         maximumConnections?: number;
     };
+    /** Optional bounded loopback workload calibration performed after a healthy release. */
+    capacityCalibration?: {
+        path: string;
+        maxConcurrency?: number;
+        requestsPerWorker?: number;
+        maximumRequestsPerWorker?: number;
+        maxP95Ms?: number;
+        maxErrorRate?: number;
+        safetyRatio?: number;
+        requestTimeoutMs?: number;
+        minimumStageDurationMs?: number;
+        maxCpuUtilizationPercent?: number;
+        maxMemoryUtilizationPercent?: number;
+    };
     resources: ResourceDefinition;
     storage?: readonly StorageMount[];
     network?: NetworkDefinition;