@hexclave/cli 1.0.117 → 1.0.119

package/src/lib/deployment-config.test.ts

@@ -15,6 +15,17 @@ function evaluate(servicesExport: unknown, mode: "deploy" | "dev" = "deploy") {
   return evaluateDeploymentConfig({ deployFilePath: DEPLOY_FILE_PATH, deploymentGroupIdExport: "test-source", deployExport, mode });
 }
 
+// The same deploy file opted into a runtime with the internal `version` export.
+function evaluateWithVersion(servicesExport: unknown, version: unknown, mode: "deploy" | "dev" = "deploy") {
+  const deployExport = (context: ServicesFunctionContext) => ({
+    services: typeof servicesExport === "function" ? (servicesExport as (ctx: ServicesFunctionContext) => unknown)(context) : servicesExport,
+  });
+  return evaluateDeploymentConfig({ deployFilePath: DEPLOY_FILE_PATH, deploymentGroupIdExport: "test-source", deployExport, versionExport: version, mode });
+}
+function evaluateOnGcp(servicesExport: unknown, mode: "deploy" | "dev" = "deploy") {
+  return evaluateWithVersion(servicesExport, "gcp-beta-1", mode);
+}
+
 describe("evaluateDeploymentConfig (deploy mode)", () => {
   it("preserves __proto__ as an environment variable instead of mutating the result prototype", () => {
     const { services } = evaluate(() => ({
@@ -96,6 +107,44 @@ describe("evaluateDeploymentConfig (deploy mode)", () => {
     });
   });
 
+  it("reads memory from the ladder its service type actually has machines for", () => {
+    const memoryOf = (service: unknown) => evaluate(() => ({ web: service })).services.get("web")?.definition.memory;
+    expect(memoryOf({ type: "serverless", ports: {}, memory: "8GB" })).toBe("8GB");
+    expect(memoryOf({ type: "server", ports: {}, memory: "4GB" })).toBe("4GB");
+    // Absent stays absent rather than being written out as the default: the
+    // backend normalizes an explicit default back out anyway, and a definition
+    // that states what it already runs must not read differently from one that
+    // says nothing.
+    expect(memoryOf({ type: "serverless", ports: {} })).toBe(undefined);
+    // The ladder is the RUNTIME's. On the default runtime a server may be 512MB (every Fly
+    // service ran on that shape before sizes existed); on GCP no 512MB machine shape exists,
+    // so the rung a serverless may use is not one a server may — and the error names the
+    // ladder for THIS service on THIS runtime.
+    expect(memoryOf({ type: "server", ports: {}, memory: "512MB" })).toBe("512MB");
+    const badGcpMemory = (service: unknown) => () => evaluateOnGcp(() => ({ web: service }));
+    expect(badGcpMemory({ type: "server", ports: {}, memory: "512MB" }))
+      .toThrow(/deploy\.services\.web\.memory must be one of "1GB", "2GB", "4GB", "8GB"/);
+    expect(evaluateOnGcp(() => ({ web: { type: "server", ports: {}, memory: "4GB" } })).services.get("web")?.definition.memory).toBe("4GB");
+    // Sizes only the builder may ask for are not service sizes.
+    const badMemory = (service: unknown) => () => evaluate(() => ({ web: service }));
+    expect(badMemory({ type: "serverless", ports: {}, memory: "32GB" })).toThrow(/must be one of/);
+  });
+
+  it("refuses non-canonical memory spellings but says which one to write", () => {
+    const memory = (value: unknown) => () => evaluate(() => ({ web: { type: "serverless", ports: {}, memory: value } }));
+    // Recognising a spelling is not accepting it: one canonical token per size,
+    // for the same reason a port key may not have a leading zero.
+    expect(memory("4gb")).toThrow(/Write it as "4GB"/);
+    expect(memory("4 GB")).toThrow(/Write it as "4GB"/);
+    expect(memory("4Gi")).toThrow(/Write it as "4GB"/);
+    expect(memory("4096MB")).toThrow(/Write it as "4GB"/);
+    // "Mb" is megabits, so it is called out rather than silently accepted.
+    expect(memory("512Mb")).toThrow(/megabits/);
+    // Unrecognisable values fall back to naming the ladder.
+    expect(memory("3GB")).toThrow(/must be one of/);
+    expect(memory(4096)).toThrow(/must be one of/);
+  });
+
   it("rejects port lists it could not serve", () => {
     const evaluatePorts = (ports: unknown) => () => evaluate(() => ({ web: { type: "serverless", ports } }));
     // The FIELD is still required — an omitted `ports` is a forgotten line far
@@ -189,37 +238,41 @@ describe("evaluateDeploymentConfig (deploy mode)", () => {
     }))).not.toThrow();
   });
 
-  it("only makes a deploy dependency of references that need the target deployed", () => {
-    // internalHost and internalUrl(<port>) are deterministic — they resolve
-    // before the target exists — so they must not order or serialize deploys.
-    const deterministicallyWired = () => evaluate(({ service }: ServicesFunctionContext) => ({
+  it("makes a deploy dependency of every reference the runtime cannot answer up front", () => {
+    // Which references wait depends on the RUNTIME (see connectionRequiresTargetDeployed).
+    // On the default runtime a private url(<port>) and hostname() are name-derived and
+    // known before anything runs, so they produce NO edge; on GCP both are the target's
+    // runtime address, so a consumer put first would fail the deploy on an unresolved
+    // ref, and every service output orders the deploy.
+    const deployFile = ({ service }: ServicesFunctionContext) => ({
       web: {
         type: "serverless", public: true, ports: { 3000: { protocol: "http" } },
         env: { API: (service("api") as any).url(8080), DB_HOST: (service("db") as any).hostname() },
       },
       api: { type: "serverless", ports: { 8080: { protocol: "http" }, 9090: { protocol: "http" } } },
       db: { type: "server", ports: { 5432: { protocol: "tcp" } } },
-    }));
-    expect(deterministicallyWired).not.toThrow();
-    // One level: nothing waits on anything.
-    expect(computeDeploymentLevels(deterministicallyWired().services)).toEqual([["web", "api", "db"]]);
-
-    // Mutual wiring through deterministic references is legal, and used to be
-    // rejected as a false circular dependency.
-    const mutual = () => evaluate(({ service }: ServicesFunctionContext) => ({
-      web: { type: "serverless", ports: { 3000: { protocol: "http" } }, env: { API: (service("api") as any).url() } },
+    });
+    const onFly = evaluate(deployFile);
+    expect(computeDeploymentLevels(onFly.services, onFly.runtime)).toEqual([["web", "api", "db"]]);
+    const onGcp = evaluateOnGcp(deployFile);
+    expect(computeDeploymentLevels(onGcp.services, onGcp.runtime)).toEqual([["api", "db"], ["web"]]);
+
+    // The accepted cost on GCP: two services that each read the other's address are a
+    // real cycle there, because neither can go first. Reported as one, with the way out.
+    // On the default runtime the same file deploys in one level.
+    const mutual = ({ service }: ServicesFunctionContext) => ({
+      web: { type: "serverless", ports: { 3000: { protocol: "http" } }, env: { API: (service("api") as any).url(8080) } },
       api: { type: "serverless", ports: { 8080: { protocol: "http" } }, env: { WEB_HOST: (service("web") as any).hostname() } },
-    }));
-    expect(mutual).not.toThrow();
-    // `web` still waits on `api`: a bare internalUrl() reads the target's ports.
-    expect(computeDeploymentLevels(mutual().services)).toEqual([["api"], ["web"]]);
+    });
+    expect(computeDeploymentLevels(evaluate(mutual).services, "fly")).toEqual([["web", "api"]]);
+    expect(() => computeDeploymentLevels(evaluateOnGcp(mutual).services, "gcp")).toThrow(/circular connection dependency/);
 
-    // A `url` reference is still a real dependency.
+    // A public `url` was always a dependency, and still is.
     const publicUrl = evaluate(({ service }: ServicesFunctionContext) => ({
       web: { type: "serverless", ports: { 3000: { protocol: "http" } }, env: { API: (service("api") as any).url() } },
       api: { type: "serverless", public: true, ports: { 8080: { protocol: "http" } } },
     }));
-    expect(computeDeploymentLevels(publicUrl.services)).toEqual([["api"], ["web"]]);
+    expect(computeDeploymentLevels(publicUrl.services, publicUrl.runtime)).toEqual([["api"], ["web"]]);
   });
 
   it("leaves references to services of other deployment sources to the backend", () => {
@@ -290,17 +343,34 @@ describe("evaluateDeploymentConfig (deploy mode)", () => {
     }))).toThrow("use the `hexclave` context object instead");
   });
 
-  it("rejects a self-referential PUBLIC url but allows a private one", () => {
-    // The public URL only exists once the service is up, which its own first
-    // deploy cannot provide.
-    expect(() => evaluate(({ service }: ServicesFunctionContext) => ({
+  it("rejects a self-referential address the runtime cannot answer up front", () => {
+    // A public URL is produced by the service's own rollout on either runtime, so no
+    // self-reference to it can resolve before the deploy that creates it finishes.
+    const publicSelf = ({ service }: ServicesFunctionContext) => ({
       web: { type: "serverless", public: true, ports: { 3000: { protocol: "http" } }, env: { SELF: (service("web") as any).url(3000) } },
-    }))).toThrow("cannot exist before the service does");
-    // A private port's URL is deterministic, so a service may reference its own.
-    const { services } = evaluate(({ service }: ServicesFunctionContext) => ({
-      web: { type: "serverless", ports: { 3000: { protocol: "http" } }, env: { SELF: (service("web") as any).url(3000) } },
-    }));
-    expect(services.get("web")?.definition.env.SELF).toEqual({ type: "connection", value: "web.url:3000" });
+    });
+    expect(() => evaluate(publicSelf)).toThrow("cannot exist before the service is deployed");
+    expect(() => evaluateOnGcp(publicSelf)).toThrow("cannot exist before the service is deployed");
+    // A private address is name-derived on the default runtime and known in advance, so a
+    // service may name its own; on GCP nothing publishes such a record, so it blocks on the
+    // real address like any other output — and would reach the deploy as an unresolvable ref.
+    const privateSelf = ({ service }: ServicesFunctionContext) => ({
+      web: { type: "serverless", ports: { 3000: { protocol: "http" } }, env: { SELF: (service("web") as any).url(3000), HOST: (service("web") as any).hostname() } },
+    });
+    expect(() => evaluate(privateSelf)).not.toThrow();
+    expect(() => evaluateOnGcp(privateSelf)).toThrow("cannot exist before the service is deployed");
+  });
+
+  it("reads the internal `version` export, and refuses one it does not know", () => {
+    const deployFile = () => ({ web: { type: "serverless", ports: { 3000: { protocol: "http" } } } });
+    expect(evaluate(deployFile)).toMatchObject({ runtime: "fly", version: undefined });
+    expect(evaluateOnGcp(deployFile)).toMatchObject({ runtime: "gcp", version: "gcp-beta-1" });
+    // Refused rather than ignored: a typo in our own token must not silently deploy to the
+    // default, and a stray export in someone's file must not silently mean anything.
+    const withVersion = (version: unknown) => () => evaluateWithVersion(deployFile, version);
+    expect(withVersion("gcp")).toThrow(/unknown `version` export "gcp"/);
+    expect(withVersion("1.0.0")).toThrow(/gcp-beta-1/);
+    expect(withVersion(1)).toThrow(/must be a string/);
   });
 
   it("rejects assigning the whole service() return instead of an output", () => {
@@ -572,8 +642,9 @@ describe("the deployment envelope", () => {
     expect(evaluateExports(7, deployExport)).toThrow("must be a string");
     expect(evaluateExports("-nope", deployExport)).toThrow("Invalid deployment group id");
     expect(evaluateExports("backend", deployExport)().sourceId).toBe("backend");
-    // Dots are legal: deployments declared in hexclave.config.ts belong to a
-    // group named after the file.
+    // Dots are legal: a group id appears in no reference, so nothing has to
+    // parse one — and projects that predate the move of services out of
+    // hexclave.config.ts still have a stored group named after that file.
     expect(evaluateExports("hexclave.config.ts", deployExport)().sourceId).toBe("hexclave.config.ts");
   });
 
@@ -762,11 +833,12 @@ describe("computeDeploymentLevels", () => {
     expect(computeDeploymentLevels(services)).toEqual([["web"]]);
   });
 
-  it("does not treat a self internalUrl reference as a cycle", () => {
-    // A self `internalUrl` is deterministic (see evaluateDeploymentConfig), so it must not
-    // create a self-edge that computeDeploymentLevels would report as a false cycle.
-    const services = build(({ service }) => ({
-      web: { type: "serverless", ports: { 3000: { protocol: "http" } }, env: { SELF: (service("web") as any).url(3000) } },
+  it("does not treat a hexclave output reference as a cycle", () => {
+    // `hexclave.*` comes from the managed service, which always exists, so it must not become
+    // an edge. Self-references to a service's own address never reach here at all — they are
+    // rejected during evaluation, since no rollout can produce an address it needs first.
+    const services = build(({ hexclave }) => ({
+      web: { type: "serverless", ports: { 3000: { protocol: "http" } }, env: { PROJECT_ID: (hexclave as any).projectId } },
     }));
     expect(computeDeploymentLevels(services)).toEqual([["web"]]);
   });
@@ -819,3 +891,39 @@ describe("build and start commands", () => {
     expect(() => evaluate(web({ runCommand: "node server.js" }))).toThrow(/unknown field "runCommand"/);
   });
 });
+
+describe("the deploy export's builder", () => {
+  const evaluateDeploy = (deployRaw: unknown) => evaluateDeploymentConfig({
+    deployFilePath: DEPLOY_FILE_PATH,
+    deploymentGroupIdExport: "test-source",
+    deployExport: () => deployRaw,
+    mode: "deploy",
+  });
+  const withServices = (extra: Record<string, unknown>) => ({
+    services: { web: { type: "serverless", ports: { 3000: { protocol: "http" } }, env: {} } },
+    ...extra,
+  });
+
+  it("is a sibling of services, because one machine builds them all", () => {
+    expect(evaluateDeploy(withServices({ builder: { memory: "32GB" } })).builder).toEqual({ memory: "32GB" });
+    // Its ladder starts where the service ladders stop: a builder is a transient
+    // machine sized for a build, not for an idling service.
+    expect(evaluateDeploy(withServices({ builder: { memory: "8GB" } })).builder).toEqual({ memory: "8GB" });
+    expect(() => evaluateDeploy(withServices({ builder: { memory: "512MB" } }))).toThrow(/deploy\.builder\.memory of .* must be one of "8GB", "16GB", "32GB"/);
+    expect(() => evaluateDeploy(withServices({ builder: { memory: "32gb" } }))).toThrow(/Write it as "32GB"/);
+  });
+
+  it("collapses an empty builder to no opinion at all", () => {
+    // `{}` and absent both mean "let the deployment decide"; storing one as a
+    // declaration would make them read differently downstream.
+    expect(evaluateDeploy(withServices({})).builder).toBe(undefined);
+    expect(evaluateDeploy(withServices({ builder: {} })).builder).toBe(undefined);
+  });
+
+  it("rejects fields neither half of the deploy export knows", () => {
+    expect(() => evaluateDeploy(withServices({ builder: { cpu: 4 } }))).toThrow(/unknown field "cpu"/);
+    expect(() => evaluateDeploy(withServices({ builder: "32GB" }))).toThrow(/must be an object/);
+    // The top-level check now names both supported fields rather than just one.
+    expect(() => evaluateDeploy(withServices({ builders: {} }))).toThrow(/unknown field "builders". Supported fields: services, builder/);
+  });
+});

package/src/lib/deployment-config.ts

@@ -1,9 +1,10 @@
 // Evaluates the `deploy` export of hexclave.deploy.ts.
 //
-// Deployments live in their OWN file, separate from hexclave.config.ts: one
-// Hexclave project can be deployed from several repositories, each shipping the
-// services it owns, and each of those repositories has a deploy file of its own
-// while only one of them (if any) owns the project's configuration.
+// Deployments live in their OWN file, separate from hexclave.config.ts, which
+// holds the project's configuration and nothing else: one Hexclave project can
+// be deployed from several repositories, each shipping the services it owns,
+// and each of those repositories has a deploy file of its own while only one of
+// them (if any) owns the project's configuration.
 //
 // The export is a FUNCTION of the deployment context returning `{ services }`.
 // The context is where `secret()`, `service()` and `hexclave.*` come from.
@@ -67,16 +68,18 @@ import {
   MAX_VOLUME_ID_LENGTH,
   MAX_VOLUME_SIZE_GB,
   MIN_VOLUME_SIZE_GB,
+  BUILDER_MEMORY_SIZES,
   SERVICE_OUTPUT_KEYS,
   connectionRequiresTargetDeployed,
+  deploymentMemorySizesForType,
   deploymentServiceIsBuilt,
+  suggestDeploymentMemorySize,
   formatConnectionValue,
   isValidDeploymentCommand,
   parseConnectionValue,
   parseDeploymentImageRef,
   DEPLOYMENT_PORT_KEY_REGEX,
   deploymentPortEntries,
-  deploymentPortEntry,
   reservedStandardPortConflicts,
   standardPortsHolderPort,
   type DeploymentEnvVarDefinition,
@@ -85,6 +88,13 @@ import {
   type DeploymentServiceType,
   type DeploymentVolumeDefinition,
   type HexclaveOutputKey,
+  type DeploymentBuilderDefinition,
+  type DeploymentMemorySize,
+  DEFAULT_DEPLOYMENT_RUNTIME,
+  deploymentPortEntry,
+  DEPLOYMENT_VERSION_TOKENS,
+  deploymentRuntimeForVersion,
+  type DeploymentRuntime,
 } from "@hexclave/shared/dist/deployments";
 import { PROJECT_SECRET_KEY_REGEX } from "@hexclave/shared/dist/project-secrets";
 import fs from "node:fs";
@@ -94,14 +104,6 @@ import { CliError, errorMessage } from "./errors.js";
 // The names checked (in order) when --deploy-file is not passed.
 export const DEPLOY_FILE_CANDIDATES = ["hexclave.deploy.ts", "hexclave.deploy.js"];
 
-/** Whether `cwd` contains a deploy file at all. */
-export function hasDeployFile(cwd: string): boolean {
-  return DEPLOY_FILE_CANDIDATES.some((candidate) => {
-    const resolved = path.resolve(cwd, candidate);
-    return fs.existsSync(resolved) && fs.statSync(resolved).isFile();
-  });
-}
-
 /**
  * Resolves the deploy file path: --deploy-file wins (and must exist); otherwise
  * the first existing candidate in `cwd`. A deploy file is REQUIRED — service
@@ -329,13 +331,55 @@ export type EvaluatedServices = {
   // but previously owned by this source as removed.
   sourceId: string,
   services: Map<string, EvaluatedService>,
+  // The machine that builds them. One per deployment, so it sits here rather
+  // than on any service. Undefined = the deployment picks the size its build
+  // shape needs.
+  builder: DeploymentBuilderDefinition | undefined,
+  // The infrastructure runtime the file's `version` export selects, and the
+  // token itself (undefined when absent). Internal: the export is undocumented,
+  // and absent means the default runtime — see DEPLOYMENT_VERSIONS.
+  runtime: DeploymentRuntime,
+  version: string | undefined,
 };
 
 const KNOWN_SERVICE_FIELDS = new Set([
-  "type", "public", "ports", "minInstances", "maxInstances",
+  "type", "public", "ports", "minInstances", "maxInstances", "memory",
   "rootDirectory", "dockerfilePath", "image", "devCommand", "buildCommand", "startCommand", "persistentVolumes", "env",
 ]);
 const KNOWN_VOLUME_FIELDS = new Set(["path", "sizeGb"]);
+// `services` and `builder` are the two halves of a deploy file: what to run, and
+// what to build it on.
+const KNOWN_DEPLOY_FIELDS = new Set(["services", "builder"]);
+const KNOWN_BUILDER_FIELDS = new Set(["memory"]);
+
+/**
+ * Reads a memory size token, refusing anything but the canonical spelling.
+ *
+ * `available` is the ladder for this particular slot — a "server" has no 512MB
+ * shape and the builder starts where the services stop — so the message names
+ * what this thing can be rather than every token that exists.
+ *
+ * Near-misses get a "did you mean": `"4gb"`, `"4 GB"` and `"4Gi"` are all
+ * refused, but they are what somebody types first, and a bare list of seven
+ * tokens leaves the reader to spot the difference by eye.
+ */
+function readMemoryField(
+  raw: unknown,
+  at: string,
+  available: readonly DeploymentMemorySize[],
+): DeploymentMemorySize | undefined {
+  if (raw === undefined) return undefined;
+  const options = available.map((size) => JSON.stringify(size)).join(", ");
+  if (typeof raw !== "string") {
+    throw new CliError(`${at} must be one of ${options} (got ${JSON.stringify(raw)}). Write the size with its unit, e.g. \`memory: "4GB"\`.`);
+  }
+  if ((available as readonly string[]).includes(raw)) return raw as DeploymentMemorySize;
+  const suggestion = suggestDeploymentMemorySize(raw);
+  if (suggestion !== null && (available as readonly string[]).includes(suggestion)) {
+    throw new CliError(`${at} is ${JSON.stringify(raw)}. Write it as ${JSON.stringify(suggestion)} — sizes have one spelling each, in MB or GB (note the capital B; "Mb" is megabits).`);
+  }
+  throw new CliError(`${at} must be one of ${options} (got ${JSON.stringify(raw)}).`);
+}
 
 function readOptionalIntegerField(record: Record<string, unknown>, serviceId: string, field: string): number | undefined {
   const value = record[field];
@@ -434,11 +478,11 @@ function evaluatePorts(serviceId: string, isPublic: boolean, portsRaw: unknown):
 
   const entries = deploymentPortEntries(ports);
 
-  // FLY.IO PLATFORM LIMITATION, VERIFIED against real Fly: a public service is
-  // all-HTTP. Fly's shared public IPv4 tells apps apart by SNI (TLS) or Host
-  // (HTTP); a raw TCP stream carries neither, so the edge accepts the connection
-  // and then drops it. Lifting this needs a dedicated IPv4 per service, which is
-  // a billing decision rather than a code change.
+  // PLATFORM LIMITATION: a public service is all-HTTP. Public traffic arrives
+  // through one shared Application Load Balancer that tells services apart by SNI
+  // (TLS) or Host (HTTP); a raw TCP stream carries neither, so the edge accepts
+  // the connection and then drops it. Lifting this needs a dedicated public
+  // address per service, which is a cost decision rather than a code change.
   const tcpPorts = entries.filter((entry) => entry.protocol === "tcp");
   if (isPublic && tcpPorts.length > 0) {
     throw new CliError(`deploy.services.${serviceId} is \`public: true\` but declares the "tcp" port${tcpPorts.length === 1 ? "" : "s"} ${tcpPorts.map((entry) => entry.port).join(", ")}. Raw TCP carries no SNI or Host header, so a shared public address cannot tell which service a connection is for. Keep the service private and reach it with service(${JSON.stringify(serviceId)}).hostname() and the port number, or move the TCP ports to their own service.`);
@@ -469,6 +513,28 @@ function evaluatePorts(serviceId: string, isPublic: boolean, portsRaw: unknown):
   return ports;
 }
 
+/**
+ * Reads the deploy export's `builder`.
+ *
+ * Returns undefined when the file says nothing OR when it declares an empty
+ * object: both mean "no opinion", and storing `{}` would make an empty
+ * declaration look different from an absent one to every reader downstream.
+ */
+function evaluateBuilder(deployFilePath: string, builderRaw: unknown): DeploymentBuilderDefinition | undefined {
+  if (builderRaw === undefined) return undefined;
+  if (builderRaw === null || typeof builderRaw !== "object" || Array.isArray(builderRaw)) {
+    throw new CliError(`deploy.builder of ${deployFilePath} must be an object, e.g. \`builder: { memory: "32GB" }\`.`);
+  }
+  const record = builderRaw as Record<string, unknown>;
+  for (const field of Object.keys(record)) {
+    if (!KNOWN_BUILDER_FIELDS.has(field)) {
+      throw new CliError(`deploy.builder of ${deployFilePath} has an unknown field ${JSON.stringify(field)}. Known fields: ${[...KNOWN_BUILDER_FIELDS].join(", ")}.`);
+    }
+  }
+  const memory = readMemoryField(record.memory, `deploy.builder.memory of ${deployFilePath}`, BUILDER_MEMORY_SIZES);
+  return memory === undefined ? undefined : { memory };
+}
+
 function evaluatePersistentVolumes(serviceId: string, volumesRaw: unknown): Record<string, DeploymentVolumeDefinition> | undefined {
   if (volumesRaw === undefined || volumesRaw === null) return undefined;
   if (typeof volumesRaw !== "object" || Array.isArray(volumesRaw)) {
@@ -602,18 +668,19 @@ const EXAMPLE_DEPLOYMENT_EXPORT = `  export const deploymentGroupId = "my-app";
  */
 export function evaluateDeploymentConfig(options: {
   deployFilePath: string,
-  // The file's `deploymentGroupId` export — the deployment group id. Required in
-  // a deploy file; the caller passes CONFIG_FILE_DEPLOYMENT_SOURCE_ID for
-  // deployments declared in hexclave.config.ts, which has no id of its own.
+  // The file's `deploymentGroupId` export — the deployment group id.
   deploymentGroupIdExport: unknown,
   // The file's `id` export, which is what this used to be called. Passed so a
   // file still using the old name fails with the rename instead of the
   // less helpful "no `deploymentGroupId` export".
   legacyIdExport?: unknown,
   deployExport: unknown,
+  // The file's `version` export, if any: an internal token selecting the
+  // infrastructure runtime. Absent is the default.
+  versionExport?: unknown,
   mode: "deploy" | "dev",
 }): EvaluatedServices {
-  const { deployFilePath, deploymentGroupIdExport, legacyIdExport, deployExport, mode } = options;
+  const { deployFilePath, deploymentGroupIdExport, legacyIdExport, deployExport, versionExport, mode } = options;
   const deployFileDirectory = path.dirname(deployFilePath);
 
   // `id` was the old name for this export. Refuse the file outright rather than
@@ -639,6 +706,18 @@ export function evaluateDeploymentConfig(options: {
     throw new CliError(`Invalid deployment group id ${JSON.stringify(sourceId)} in ${deployFilePath}. Ids must be at most ${MAX_DEPLOYMENT_SOURCE_ID_LENGTH} characters and contain only letters, numbers, underscores, dots, and hyphens (not starting with a dot or hyphen).`);
   }
 
+  // Refused loudly rather than ignored, in both directions: a typo in one of our
+  // own tokens must not silently deploy to the default runtime, and a stray
+  // `version` in someone's deploy file must not silently mean anything.
+  const version = versionExport === undefined ? undefined : versionExport;
+  if (version !== undefined && typeof version !== "string") {
+    throw new CliError(`The \`version\` export of ${deployFilePath} must be a string (got ${typeof version}). Remove it unless you were given a value for it.`);
+  }
+  const runtime = deploymentRuntimeForVersion(version);
+  if (runtime === null) {
+    throw new CliError(`The deploy file ${deployFilePath} has an unknown \`version\` export ${JSON.stringify(version)}. Remove it, or use one of: ${DEPLOYMENT_VERSION_TOKENS.join(", ")}.`);
+  }
+
   if (deployExport === undefined) {
     throw new CliError(`The deploy file ${deployFilePath} has no \`deploy\` export. Add one, e.g.:\n${EXAMPLE_DEPLOYMENT_EXPORT}`);
   }
@@ -673,10 +752,13 @@ export function evaluateDeploymentConfig(options: {
   }
   const deployRecord = deployRaw as Record<string, unknown>;
   for (const field of Object.keys(deployRecord)) {
-    if (field !== "services") {
-      throw new CliError(`The \`deploy\` export of ${deployFilePath} returned an unknown field ${JSON.stringify(field)}. The only supported field is \`services\`.`);
+    if (!KNOWN_DEPLOY_FIELDS.has(field)) {
+      throw new CliError(`The \`deploy\` export of ${deployFilePath} returned an unknown field ${JSON.stringify(field)}. Supported fields: ${[...KNOWN_DEPLOY_FIELDS].join(", ")}.`);
     }
   }
+  // The builder is one machine per deployment, so it is read once here rather
+  // than per service.
+  const builder = evaluateBuilder(deployFilePath, deployRecord.builder);
   const servicesRaw = deployRecord.services;
   if (servicesRaw === undefined) {
     throw new CliError(`The \`deploy\` export of ${deployFilePath} returned no \`services\`. Add them, e.g.:\n${EXAMPLE_DEPLOYMENT_EXPORT}`);
@@ -704,7 +786,7 @@ export function evaluateDeploymentConfig(options: {
     }
     if (!(DEPLOYMENT_SERVICE_TYPES as readonly unknown[]).includes(record.type)) {
       throw new CliError(record.type === undefined
-        ? `deploy.services.${serviceId} has no \`type\`. Add \`type: "server"\` (single suspending instance, may have persistentVolumes) or \`type: "serverless"\` (scales out, stops on scale-down).`
+        ? `deploy.services.${serviceId} has no \`type\`. Add \`type: "server"\` (single always-on instance, may have persistentVolumes, paid plan) or \`type: "serverless"\` (scales out, stops on scale-down).`
         : `deploy.services.${serviceId}.type must be ${DEPLOYMENT_SERVICE_TYPES.map((knownType: string) => JSON.stringify(knownType)).join(" or ")} (got ${JSON.stringify(record.type)}).`);
     }
     const serviceType = record.type as DeploymentServiceType;
@@ -807,6 +889,10 @@ export function evaluateDeploymentConfig(options: {
       }
     }
 
+    // The ladder is the service type's own: a "server" runs on whole machines
+    // and has no 512MB shape to run on.
+    const memory = readMemoryField(record.memory, `deploy.services.${serviceId}.memory`, deploymentMemorySizesForType(serviceType, runtime));
+
     // A volume is local disk on a single host and attaches to at most one
     // instance, so only a "server" can hold one.
     const persistentVolumes = evaluatePersistentVolumes(serviceId, record.persistentVolumes);
@@ -839,6 +925,12 @@ export function evaluateDeploymentConfig(options: {
         // A "serverless" defaults to 0 (scale to zero) downstream.
         min_instances: serviceType === "server" ? minInstances ?? 1 : minInstances,
         max_instances: maxInstances,
+        // Left undefined when the file says nothing, rather than written out
+        // like `public` above: the default is applied at deploy time, and a
+        // definition that states the value it already runs at must hash the
+        // same as one that omits it — otherwise adding `memory: "1GB"` to a
+        // running server would replace the machine for no change at all.
+        memory,
         // Stored/displayed as a config-directory-relative posix path ("." for
         // the config directory itself) — an absolute local path would be
         // meaningless (and leak local filesystem layout) server-side.
@@ -955,30 +1047,27 @@ export function evaluateDeploymentConfig(options: {
     }
   }
 
-  // A service referencing its own PUBLIC url can never be satisfied: that URL
-  // only exists once the service is up (or a domain verifies), which its own
-  // first deploy cannot provide. Its private address is deterministic and fine
-  // to self-reference. Mirrors the backend check, but fails before anything is
-  // uploaded.
+  // A service referencing an address of its OWN that its rollout produces can never be
+  // satisfied: the reference would have to resolve before the deploy that creates it has
+  // finished. Which addresses those are depends on the runtime (see
+  // connectionRequiresTargetDeployed): on the default runtime a private address is
+  // name-derived and known before anything runs, so only a public url is a cycle; on GCP
+  // every service output is. Caught here rather than at deploy time, where it surfaced as
+  // "blocked on unresolved refs" after the upload — and where no retry could ever clear it.
   for (const [serviceId, service] of services) {
     for (const [envVarKey, value] of Object.entries(service.env)) {
       if (value.kind !== "connection") continue;
       const parsed = parseConnectionValue(value.reference);
-      if (parsed === null || parsed.serviceId !== serviceId || parsed.outputKey !== "url") continue;
-      // Only a PUBLIC service's own url() is a cycle: it resolves to the platform
-      // URL, which does not exist until the service is up. A private service's
-      // resolves from its deterministic hostname, so it can name itself.
-      if (service.definition.public !== true) continue;
-      const ports = deploymentPortEntries(service.definition.ports);
-      const port = parsed.port === null
-        ? ports.filter((entry) => entry.protocol === "http")[0]
-        : ports.find((entry) => entry.port === parsed.port);
-      if (port === undefined) continue;
-      throw new CliError(`deploy.services.${serviceId}.env.${envVarKey} connects to the service's own public URL (port ${port.port}), which cannot exist before the service does. Use service("${serviceId}").hostname() for its own address.`);
+      if (parsed === null || parsed.serviceId !== serviceId) continue;
+      const targetIsPublic = parsed.port === null || deploymentPortEntry(service.definition.ports, parsed.port) === null
+        ? null
+        : service.definition.public === true;
+      if (!connectionRequiresTargetDeployed(runtime, parsed.outputKey, parsed.port, targetIsPublic)) continue;
+      throw new CliError(`deploy.services.${serviceId}.env.${envVarKey} connects to the service's own ${parsed.outputKey}, which cannot exist before the service is deployed. ${runtime === "fly" && parsed.outputKey === "url" ? `Use service("${serviceId}").hostname() for its own address.` : "Set it as a plain env var, or have the service read its own address at runtime."}`);
     }
   }
 
-  return { sourceId, services };
+  return { sourceId, services, builder, runtime, version };
 }
 
 /**
@@ -987,7 +1076,7 @@ export function evaluateDeploymentConfig(options: {
  * services within one level are independent of each other. Throws on circular
  * dependencies, naming the cycle.
  */
-export function computeDeploymentLevels(services: Map<string, EvaluatedService>): string[][] {
+export function computeDeploymentLevels(services: Map<string, EvaluatedService>, runtime: DeploymentRuntime = DEFAULT_DEPLOYMENT_RUNTIME): string[][] {
   const dependencies = new Map<string, Set<string>>();
   for (const [serviceId, service] of services) {
     const serviceDependencies = new Set<string>();
@@ -1000,19 +1089,16 @@ export function computeDeploymentLevels(services: Map<string, EvaluatedService>)
       // connections to services of ANOTHER deployment source are resolved
       // against already-deployed state, since that source deploys on its own
       // schedule and is not part of this deploy at all.
-      // Self-references never create a deploy edge: a self `url` is rejected outright above,
-      // and self internal outputs are deterministic from the synced definition (they don't depend on the
-      // service having deployed). Adding a self-edge here would make computeDeploymentLevels
-      // report a false circular-dependency error for a config that deploys fine.
+      // Self-references never create a deploy edge: every self-reference to an address output
+      // is rejected outright above, and the outputs that remain do not depend on the service
+      // having deployed. Adding a self-edge here would make computeDeploymentLevels report a
+      // circular-dependency error where the check above gives the specific reason.
       //
-      // The same reasoning excludes DETERMINISTIC cross-service references: only
-      // `url` and a bare `internalUrl()` need the target deployed. Counting the
-      // rest would serialize independent deploys and reject mutually-wired
-      // services as circular.
-      // Publicness decides whether a url() reference has to wait: a private
-      // service's URL is built from the deterministic hostname, so it resolves
-      // before the target exists. A target this file does not define is not part
-      // of this deploy either way, so it never becomes an edge.
+      // The same reasoning excludes DETERMINISTIC cross-service references, which
+      // the runtime decides (see connectionRequiresTargetDeployed): counting them
+      // would serialize independent deploys and reject mutually-wired services as
+      // circular. A target this file does not define is not part of this deploy
+      // either way, so it never becomes an edge.
       const target = services.get(targetServiceId);
       if (target === undefined) continue;
       // Null when the named port is not one the target declares — the reference
@@ -1021,7 +1107,7 @@ export function computeDeploymentLevels(services: Map<string, EvaluatedService>)
       const targetIsPublic = parsed.port === null || deploymentPortEntry(target.definition.ports, parsed.port) === null
         ? null
         : target.definition.public === true;
-      if (!connectionRequiresTargetDeployed(parsed.outputKey, parsed.port, targetIsPublic)) continue;
+      if (!connectionRequiresTargetDeployed(runtime, parsed.outputKey, parsed.port, targetIsPublic)) continue;
       if (targetServiceId !== HEXCLAVE_SERVICE_ID && targetServiceId !== serviceId) {
         serviceDependencies.add(targetServiceId);
       }
@@ -1154,9 +1240,9 @@ function resolveHexclaveOutputFromSessionEnv(envVarKey: string, outputKey: Hexcl
 }
 
 /**
- * Loads a TypeScript/JavaScript module via jiti. Shared by the deploy-file and
- * config-file loaders below so both fail with the same error on an unloadable
- * file; `description` names which of the two it was.
+ * Loads a TypeScript/JavaScript module via jiti, reporting an unloadable file as
+ * a CliError rather than whatever jiti threw. `description` is how the file is
+ * named in that error.
  */
 async function importModule(filePath: string, description: string): Promise<Record<string, unknown>> {
   const { createJiti } = await import("jiti");
@@ -1174,20 +1260,8 @@ async function importModule(filePath: string, description: string): Promise<Reco
  * the first (`id`) comes back too, so evaluation can name the rename instead of
  * reporting a missing export.
  */
-export async function importDeployModule(deployFilePath: string): Promise<{ deploymentGroupId: unknown, legacyId: unknown, deploy: unknown }> {
+export async function importDeployModule(deployFilePath: string): Promise<{ deploymentGroupId: unknown, legacyId: unknown, deploy: unknown, version: unknown }> {
   const module = await importModule(deployFilePath, "deploy file");
-  return { deploymentGroupId: module.deploymentGroupId, legacyId: module.id, deploy: module.deploy };
+  return { deploymentGroupId: module.deploymentGroupId, legacyId: module.id, deploy: module.deploy, version: module.version };
 }
 
-/**
- * Loads a config file (hexclave.config.ts) and returns its `config` export, plus
- * a `deploy` export if it has one — a project small enough to keep its
- * services in the config file may declare them there instead of in a deploy
- * file. Those services belong to a deployment group named after the file (the
- * config file has no `deploymentGroupId` export of its own), so they can coexist
- * with the deploy files of other repositories deploying into the same project.
- */
-export async function importConfigModule(configPath: string): Promise<{ config: unknown, deploy: unknown }> {
-  const module = await importModule(configPath, "config file");
-  return { config: module.config, deploy: module.deploy };
-}