cf-orbs 0.1.1 → 0.2.2

package/dist/file-checks.js

@@ -0,0 +1,194 @@
+// Checks on the project files: image pins, debugExec, secrets in tracked files, git mode files.
+// Used by doctor (all modes) and by init --no-deploy before its first commit. Read-only.
+import { existsSync } from "node:fs";
+import { readFile, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { CONFIG_FILE } from "./config.js";
+import { CliError, toFailedLine } from "./errors.js";
+import { readControlToken, templatesDir } from "./project.js";
+import { WRANGLER_PIN } from "./wrangler.js";
+const pass = (name, detail) => ({ name, status: "PASS", detail });
+const failed = (name, e) => ({ name, status: "FAIL", detail: toFailedLine(e) });
+const skip = (name, detail) => ({ name, status: "SKIP", detail });
+const DIGEST_REF = /@sha256:[0-9a-f]{64}$/;
+/** Base image refs in a Dockerfile that have no @sha256 digest. Earlier stage names and scratch are fine. */
+export function unpinnedFroms(dockerfile) {
+    const stages = new Set(["scratch"]);
+    const out = [];
+    for (const line of dockerfile.split(/\r?\n/)) {
+        const m = /^\s*FROM\s+(.+)$/i.exec(line);
+        if (!m)
+            continue;
+        const words = m[1].trim().split(/\s+/);
+        const ref = words.find((w) => !w.startsWith("--"));
+        if (!ref)
+            continue;
+        const known = stages.has(ref.toLowerCase());
+        const as = words.findIndex((w) => w.toLowerCase() === "as");
+        if (as !== -1 && words[as + 1])
+            stages.add(words[as + 1].toLowerCase());
+        if (!known && !DIGEST_REF.test(ref))
+            out.push(ref);
+    }
+    return out;
+}
+/** "<repo>@sha256:0123456789ab" for a PASS line. */
+function shortRefs(dockerfile) {
+    const refs = [...dockerfile.matchAll(/^\s*FROM\s+(?:--\S+\s+)*(\S+)/gim)].map((m) => m[1].replace(/@sha256:([0-9a-f]{12})[0-9a-f]{52}$/, "@sha256:$1…"));
+    return refs.join(", ");
+}
+async function pinCheck(name, file, label, fix) {
+    let text;
+    try {
+        text = await readFile(file, "utf8");
+    }
+    catch {
+        return failed(name, new CliError(`${label} not found`, "run cf-orbs init in this directory"));
+    }
+    const bad = unpinnedFroms(text);
+    if (bad.length > 0)
+        return failed(name, new CliError(`${label} FROM ${bad.join(", ")} has no @sha256 digest`, fix));
+    return pass(name, `${label} FROM ${shortRefs(text)} (by digest)`);
+}
+/** image/Dockerfile and the Dockerfile of every extra image key: each FROM is pinned by digest. */
+export async function orbImagePinCheck(p, c) {
+    const keys = [...new Set(Object.values(c?.images ?? {}))];
+    const files = [
+        ["image/Dockerfile", p.imageDockerfile],
+        ...keys.map((k) => [`image/${k}.Dockerfile`, join(p.imageDir, `${k}.Dockerfile`)]),
+    ];
+    const fix = "pin the base image as <image>@sha256:<digest> (for the Amp image: cf-orbs upgrade --digest sha256:<hex>)";
+    let first;
+    let extra = 0;
+    for (const [label, file] of files) {
+        if (label !== "image/Dockerfile" && !existsSync(file))
+            continue; // deploy reports a missing one
+        const c1 = await pinCheck("orb image pin", file, label, fix);
+        if (c1.status === "FAIL")
+            return c1;
+        if (first)
+            extra++;
+        first ??= c1;
+    }
+    return extra > 0 && first
+        ? { ...first, detail: `${first.detail}; ${extra} extra image key(s) pinned too` }
+        : first;
+}
+/** The provider image cf-orbs builds: the project copy (.cf-orbs/provider) if there is one, else the template. */
+export async function providerImagePinCheck(p, templates = templatesDir()) {
+    const copy = join(p.stateDir, "provider", "Dockerfile");
+    const tpl = join(templates, "provider", "Dockerfile");
+    // In a source checkout the templates are synced at build time; before that, read the source file.
+    const src = join(templates, "..", "..", "provider", "Dockerfile");
+    const [file, label] = existsSync(copy)
+        ? [copy, ".cf-orbs/provider/Dockerfile"]
+        : [existsSync(tpl) || !existsSync(src) ? tpl : src, "provider/Dockerfile (CLI template)"];
+    return pinCheck("provider image pin", file, label, "reinstall cf-orbs (the provider image is a CLI template), then cf-orbs deploy");
+}
+/** debugExec lets the control token run commands in orbs. WARN, never FAIL: the substrate bench needs it. */
+export function debugExecCheck(c, git) {
+    if (!c)
+        return skip("debugExec", "needs a valid config");
+    if (!c.debugExec)
+        return pass("debugExec", "false (the control token cannot run commands in orbs)");
+    const then = git ? "commit and push" : "run cf-orbs deploy";
+    return {
+        name: "debugExec",
+        status: "WARN",
+        detail: toFailedLine(new CliError("debugExec is true: whoever has the control token can run any command in any orb", `set "debugExec": false in ${CONFIG_FILE}, then ${then} (keep it on only for the substrate bench)`)),
+    };
+}
+const AOP_TOKEN = /aop_live_[A-Za-z0-9_-]{8,}/;
+const MAX_SCAN_BYTES = 10_000_000;
+/**
+ * Files (relative to dir) that hold an Amp provider token or one of the given secret values.
+ * Never returns the values. Skips files over 10 MB.
+ */
+export async function filesWithSecrets(dir, files, values) {
+    const hits = [];
+    const vals = values.filter((v) => v.length >= 8);
+    for (const f of files) {
+        const path = join(dir, f);
+        try {
+            if ((await stat(path)).size > MAX_SCAN_BYTES)
+                continue;
+            const text = await readFile(path, "latin1");
+            if (AOP_TOKEN.test(text) || vals.some((v) => text.includes(v)))
+                hits.push(f);
+        }
+        catch { }
+    }
+    return hits;
+}
+/** `git ls-files` of dir, or undefined when dir is not in a git work tree (or git is missing). */
+export async function gitTrackedFiles(run, dir) {
+    const r = await run("git", ["-C", dir, "ls-files", "-z"], { timeoutMs: 30_000 });
+    if (r.code !== 0)
+        return undefined;
+    return r.stdout.split("\0").filter(Boolean);
+}
+/** No aop_live_ token and no control token value in a file git tracks. SKIP outside a git work tree. */
+export async function trackedSecretsCheck(run, p, extra = []) {
+    const name = "secrets in git";
+    const files = await gitTrackedFiles(run, p.dir);
+    if (!files)
+        return skip(name, "not a git repository");
+    const ct = await readControlToken(p);
+    const hits = await filesWithSecrets(p.dir, files, [...(ct ? [ct] : []), ...extra]);
+    if (hits.length === 0)
+        return pass(name, `${files.length} tracked file(s), no aop_live_ or control token`);
+    return failed(name, new CliError(`a token is in tracked file(s): ${hits.slice(0, 5).join(", ")}${hits.length > 5 ? ", …" : ""}`, "git rm --cached those files (or remove the token), make a new token, and purge it from history if you pushed"));
+}
+/** Git mode: .cf-orbs/control-token and .cf-orbs/state.json are ignored and not tracked. */
+export async function gitignoreCheck(run, p) {
+    const name = "gitignore";
+    const paths = [".cf-orbs/control-token", ".cf-orbs/state.json"];
+    const notIgnored = [];
+    for (const f of paths) {
+        // exit 0: ignored; 1: not ignored or tracked; 128: no repo. Fall back to the .gitignore lines then.
+        const r = await run("git", ["-C", p.dir, "check-ignore", "-q", f], { timeoutMs: 30_000 });
+        if (r.code === 0)
+            continue;
+        if (r.code === 1) {
+            notIgnored.push(f);
+            continue;
+        }
+        let lines = [];
+        try {
+            lines = (await readFile(p.gitignore, "utf8")).split(/\r?\n/).map((l) => l.trim());
+        }
+        catch { }
+        if (!lines.includes(f))
+            notIgnored.push(f);
+    }
+    if (notIgnored.length === 0)
+        return pass(name, `${paths.join(" and ")} are ignored`);
+    return failed(name, new CliError(`${notIgnored.join(" and ")} not ignored by git (or tracked)`, `add ${notIgnored.join(" and ")} to .gitignore and run git rm --cached on any that git tracks`));
+}
+/** Git mode: package.json pins the wrangler version the CLI uses (Workers Builds installs that one). */
+export async function wranglerPinCheck(p) {
+    const name = "wrangler pin";
+    let pkg;
+    try {
+        pkg = JSON.parse(await readFile(p.packageJson, "utf8"));
+    }
+    catch {
+        return failed(name, new CliError("package.json is missing or not valid JSON", "rerun cf-orbs init --no-deploy (it writes one)"));
+    }
+    const v = pkg.devDependencies?.wrangler ?? pkg.dependencies?.wrangler;
+    if (v === WRANGLER_PIN)
+        return pass(name, `package.json pins wrangler ${v}, same as cf-orbs`);
+    return failed(name, new CliError(`package.json ${v ? `pins wrangler ${v}` : "has no wrangler dependency"}; cf-orbs uses ${WRANGLER_PIN}`, `set devDependencies.wrangler to "${WRANGLER_PIN}", run npm install, commit and push`));
+}
+/** All file checks for doctor, in output order. git: state.mode is "git". */
+export async function fileChecks(run, p, c, o) {
+    const out = [
+        await orbImagePinCheck(p, c),
+        await providerImagePinCheck(p, o.templates),
+        debugExecCheck(c, o.git),
+        await trackedSecretsCheck(run, p),
+    ];
+    if (o.git)
+        out.push(await gitignoreCheck(run, p), await wranglerPinCheck(p));
+    return out;
+}

package/dist/index.js

@@ -30,9 +30,12 @@ export const COMMANDS = {
             "--provider cloudflare|external   where amp orb provider runs (default cloudflare)",
             "--token-file <file>              Amp provider token file (else AMP_ORB_PROVIDER_TOKEN, else prompt)",
             "--account-id <id>                Cloudflare account (else CLOUDFLARE_ACCOUNT_ID, else ask)",
-            "--provider-name <name>           Amp provider name, as in Amp Settings → Orbs (default cf-orbs)",
+            "--provider-name <name>           Amp provider name, as in Amp Settings → Orbs (else AMP_ORB_PROVIDER_NAME, saved name, config name, then cf-orbs)",
             "--subdomain <name>               workers.dev subdomain to register if the account has none",
             "--vcpu <1|2|3|4>                 orb size: N vCPU, N x 3 GiB, 20 GB disk (default 4; 2 is cheaper)",
+            "--name <name>                    Worker name (default cf-orbs; a second install needs another)",
+            "--no-deploy                      preview: no Docker, no deploy. Make a git repo for Workers Builds,",
+            "                                 create the Worker and its secrets, print the dashboard steps",
         ],
         flags: {
             provider: { type: "string" },
@@ -41,6 +44,8 @@ export const COMMANDS = {
             "provider-name": { type: "string" },
             subdomain: { type: "string" },
             vcpu: { type: "string" },
+            name: { type: "string" },
+            "no-deploy": { type: "boolean" },
         },
         dirPositional: true,
         run: initCommand,

package/dist/project.js

@@ -6,6 +6,8 @@
 //   cf-orbs.config.jsonc     user config (source of truth)
 //   image/Dockerfile         orb image, user-editable; upgrade bumps its digest; image/<key>.Dockerfile for extra keys
 //   .gitignore               generated; keeps .cf-orbs/ (and its control-token) out of git
+//                            (git mode: only control-token and state.json; Workers Builds needs the rest)
+//   package.json             git mode only: pins wrangler for Workers Builds
 //   .cf-orbs/
 //     wrangler.jsonc         generated
 //     worker/src/**          copied from templates on every deploy
@@ -35,6 +37,7 @@ export function projectPaths(dir) {
         state: join(s, "state.json"),
         controlToken: join(s, "control-token"),
         gitignore: join(d, ".gitignore"),
+        packageJson: join(d, "package.json"),
     };
 }
 /** cli/templates, resolved from this file (works from src/ under vitest and from dist/ when installed). */
@@ -105,15 +108,31 @@ export const GITIGNORE_LINES = [
     ".wrangler/",
     "node_modules/",
 ];
+/** Git mode (init --no-deploy): the generated files are committed, so only these stay out of git. */
+export const GIT_MODE_GITIGNORE_LINES = [
+    ".cf-orbs/control-token",
+    ".cf-orbs/state.json",
+    ".wrangler/",
+    "node_modules/",
+];
+/** Lines of the local layout that hide the generated files. Git mode removes them. */
+const LOCAL_ONLY_LINES = new Set([".cf-orbs/*", "!.cf-orbs/state.json"]);
 /** Add the cf-orbs lines to <dir>/.gitignore, keeping existing lines. */
-export async function ensureGitignore(p) {
+export async function ensureGitignore(p, git = false) {
     let cur = "";
     try {
         cur = await readFile(p.gitignore, "utf8");
     }
     catch { }
+    if (git && cur.split(/\r?\n/).some((l) => LOCAL_ONLY_LINES.has(l.trim()))) {
+        cur = cur
+            .split(/(?<=\n)/)
+            .filter((l) => !LOCAL_ONLY_LINES.has(l.trim()))
+            .join("");
+        await writeFile(p.gitignore, cur);
+    }
     const have = new Set(cur.split(/\r?\n/).map((l) => l.trim()));
-    const add = GITIGNORE_LINES.filter((l) => !have.has(l));
+    const add = (git ? GIT_MODE_GITIGNORE_LINES : GITIGNORE_LINES).filter((l) => !have.has(l));
     if (add.length === 0)
         return;
     const sep = cur === "" || cur.endsWith("\n") ? "" : "\n";
@@ -155,7 +174,7 @@ export async function materialize(p, opts = {}) {
         await writeFile(p.config, text);
         wroteConfig = true;
     }
-    await ensureGitignore(p);
+    await ensureGitignore(p, opts.git);
     return { wroteConfig, wroteDockerfile };
 }
 /** The files the provider image is built from, relative to .cf-orbs/ (its build context). */
@@ -213,3 +232,15 @@ export async function cliVersion() {
         return "0.0.0";
     }
 }
+/** Git mode deploy command: Workers Builds runs it in the repo root. */
+export const GIT_DEPLOY_COMMAND = "npx wrangler deploy --config .cf-orbs/wrangler.jsonc";
+/** Root package.json for git mode: Workers Builds installs the wrangler version it names. */
+export function gitPackageJson(name, wrangler) {
+    const pkg = {
+        name,
+        private: true,
+        scripts: { deploy: "wrangler deploy --config .cf-orbs/wrangler.jsonc" },
+        devDependencies: { wrangler },
+    };
+    return `${JSON.stringify(pkg, null, 2)}\n`;
+}

package/dist/wrangler-template.js

@@ -40,6 +40,9 @@ export function buildWranglerConfig(c, o = {}) {
         main: "worker/src/index.ts",
         compatibility_date: COMPATIBILITY_DATE,
         compatibility_flags: ["nodejs_compat"],
+        // explicit, so wrangler does not warn: the control plane is on workers.dev; preview URLs are not used
+        workers_dev: true,
+        preview_urls: false,
         observability: { enabled: true },
         containers: [
             orbContainer,

package/dist/wrangler.js

@@ -37,6 +37,8 @@ export const runProcess = (cmd, args, o = {}) => new Promise((resolve) => {
         resolve({ code: code ?? 1, stdout, stderr });
     });
 });
+/** The wrangler version the CLI depends on (cli/package.json). Git mode pins the same version in package.json. */
+export const WRANGLER_PIN = "4.156.0";
 /** [command, ...prefix args] that runs the pinned wrangler. Prefers the CLI's own dependency over npx. */
 export function wranglerCommand() {
     try {
@@ -46,7 +48,7 @@ export function wranglerCommand() {
             return [process.execPath, [bin]];
     }
     catch { }
-    return [process.platform === "win32" ? "npx.cmd" : "npx", ["--yes", "wrangler@4.156.0"]];
+    return [process.platform === "win32" ? "npx.cmd" : "npx", ["--yes", `wrangler@${WRANGLER_PIN}`]];
 }
 export function makeWrangler(run = runProcess, base = {}) {
     const [cmd, prefix] = wranglerCommand();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cf-orbs",
-  "version": "0.1.1",
+  "version": "0.2.2",
   "description": "Run Amp orbs on Cloudflare Containers: self-hosted orb provider, one command to install.",
   "license": "Apache-2.0",
   "type": "module",

package/templates/cf-orbs.config.example.jsonc

@@ -5,7 +5,7 @@
   "name": "cf-orbs",
 
   // Orb size. One size per install: Amp sends no size to the provider.
-  // Custom: vcpu 1-4, memoryMib up to 12288 and at least 3072 per vCPU, diskMb 8000-20000.
+  // Custom: vcpu 1-4 (fractions allowed), memoryMib up to 12288 and at least 3072 per vCPU, diskMb 8000-20000.
   // Or a named type: "standard-1" .. "standard-4". "lite" and "basic" are too small for the orb image.
   // Default 4 vCPU, 12 GiB, 20 GB. `cf-orbs init --vcpu N` writes N vCPU, N x 3 GiB, 20 GB (--vcpu 2 is cheaper).
   "instance": { "vcpu": 4, "memoryMib": 12288, "diskMb": 20000 },
@@ -53,4 +53,18 @@
 
   // Enable wrangler containers ssh for orbs (debug only).
   "debugSsh": false
+
+  // Turn on the exec and bench routes. Only for the substrate benchmark: the control token can then run
+  // commands in orbs. true or false.
+  // "debugExec": false,
+
+  // Minutes an orb may sit idle before the container stops. 5-360.
+  // "inactivityTimeoutMinutes": 15,
+
+  // Seconds between watchdog checks of an orb. 10-3600, and shorter than inactivityTimeoutMinutes.
+  // "alarmSeconds": 60,
+
+  // Digest of the Amp orb image the "orb" image is built from. Used for log lines only.
+  // Must look like sha256:<64 hex digits>.
+  // "ampImageDigest": "sha256:378c5e2188f00960eca36dc806aa04e1cacd92c2341665bcdf4692326c462d6d"
 }

package/templates/dispatch/dispatch.sh

@@ -1,5 +1,5 @@
 #!/bin/sh
-# cf-orbs dispatch program. `amp orb provider` runs it once per job (D11, D12).
+# cf-orbs dispatch program. `amp orb provider` runs it once per job.
 #
 # Input (env, from Amp): ORB_OPERATION ORB_ID ORB_IMAGE ORB_SNAPSHOT_ID ORB_TOKEN AMP_URL
 # Input (env, from cf-orbs):
@@ -190,7 +190,7 @@ redact() { CFO_CTL=$CTL_TOKEN awk "$REDACT_AWK"; }
 say() { printf '%s\n' "$*" | redact; }
 
 # fail <message> [exit code]. One final line on stdout and stderr. Worker errors already start
-# with "Failed: "; drop it so the line has one prefix (D12).
+# with "Failed: "; drop it so the line has one prefix.
 fail() {
   msg=$1
   while :; do
@@ -223,7 +223,7 @@ case $OP in
   *) fail "unknown ORB_OPERATION '$(clean "$OP")' — fix: update cf-orbs (npx cf-orbs@latest deploy)" 2 ;;
 esac
 
-# Same rule as the server (D2): ^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$
+# Same rule as the server: ^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$
 orb_ok=1
 case $ORB in
   "" | [!A-Za-z0-9]* | *[!A-Za-z0-9_-]*) orb_ok=0 ;;

package/templates/image/Dockerfile

@@ -1,4 +1,4 @@
-# cf-orbs orb image (D4). Built by `cf-orbs deploy` (wrangler) and stored under the image key "orb".
+# cf-orbs orb image. Built by `cf-orbs deploy` (wrangler) and stored under the image key "orb".
 #
 # Why a digest pin and not :latest
 #   A snapshot only restores onto the image it was taken from. A moving tag gives a new image on the
@@ -10,7 +10,7 @@
 #   The base image has no init and its CMD (python3) exits at once. tini is PID 1, keeps the container
 #   up with `sleep infinity`, and reaps the processes that cf-orbs starts with setsid (amp orb bootstrap
 #   and its children). -s makes tini a subreaper, so orphans of those processes are reaped too.
-#   tini is pinned to one Debian version so that a rebuild without cache gives the same layer (R18).
+#   tini is pinned to one Debian version so that a rebuild without cache gives the same layer.
 #   If apt cannot find that version any more, bump it and treat the result as a new image.
 #
 # How to add toolchains

package/templates/provider/Dockerfile

@@ -1,4 +1,4 @@
-# cf-orbs provider image (D18). Runs `amp orb provider /app/dispatch.sh` under tini.
+# cf-orbs provider image. Runs `amp orb provider /app/dispatch.sh` under tini.
 # Build context is the repo root (wrangler image entry: build_context ".."):
 #   docker build -f provider/Dockerfile -t cf-orbs-provider .
 FROM node:24-bookworm-slim@sha256:c86ecead9e55a5210ac1727de38a4ca840bf03dcaf34dc9749addbf383b1920c
@@ -6,7 +6,7 @@ FROM node:24-bookworm-slim@sha256:c86ecead9e55a5210ac1727de38a4ca840bf03dcaf34dc
 # Pinned Amp CLI. Bump with Renovate or by hand; the provider must match Amp's job protocol.
 ARG AMP_CLI_VERSION=0.0.1793390435-g08e9ec
 
-# curl: dispatch.sh (D12). tini: PID 1 that forwards signals and reaps children.
+# curl: dispatch.sh. tini: PID 1 that forwards signals and reaps children.
 RUN apt-get update \
   && apt-get install -y --no-install-recommends curl ca-certificates tini \
   && rm -rf /var/lib/apt/lists/*

package/templates/provider/entry.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# cf-orbs provider entry (D18). Runs `amp orb provider <dispatch>` in a loop.
+# cf-orbs provider entry. Runs `amp orb provider <dispatch>` in a loop.
 # Output is redacted, then written to stdout and to the log file. The log is capped.
 # Env:
 #   AMP_ORB_PROVIDER_TOKEN  required. Read by amp; never printed.

package/templates/worker/src/api.ts

@@ -18,7 +18,7 @@ import { type Env, orbDoName, PROVIDER_DO_NAME, REGISTRY_DO_NAME } from "./env";
 import { BENCH_ORB_RE, type BenchStartRequest, parseBenchStart } from "./orb/bench";
 import { restartProvider } from "./provider-restart";
 
-export const API_VERSION = "0.1.0";
+export const API_VERSION = "0.2.2";
 
 /** D2. Amp sends `amp-<thread id>`. Never starts with `_` or `.`, so it cannot look like an internal name. */
 export const ORB_ID_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;

package/templates/worker/src/core/config.ts

@@ -5,6 +5,7 @@ import {
   DEFAULT_CONFIG,
   type InstanceSpec,
   MAX_PREWARM,
+  type OrbInstanceSpec,
   type ProjectSnapshotRefresh,
   type ProviderConfig,
 } from "./types";
@@ -37,9 +38,9 @@ function num(v: unknown, name: string, min: number, max: number, integer = true)
   return v;
 }
 
-export function validateInstance(v: unknown): InstanceSpec {
+export function validateInstance(v: unknown): OrbInstanceSpec {
   if (typeof v === "string") {
-    if ((NAMED as readonly string[]).includes(v)) return v as InstanceSpec;
+    if ((NAMED as readonly string[]).includes(v)) return v as OrbInstanceSpec;
     if (v === "lite" || v === "basic" || v === "dev") {
       fail(
         `instance ${v} is too small for the orb image`,

package/templates/worker/src/core/types.ts

@@ -49,7 +49,7 @@ export interface SnapshotHandle {
   id: string; // Cloudflare snapshot id
   size: number; // bytes reported by snapshotContainer
   imageKey: string; // key in images map the snapshot was taken from
-  instance: InstanceSpec;
+  instance: OrbInstanceSpec;
   createdAt: string; // ISO
   lastRestoredAt?: string; // ISO; set on every successful restore. Expiry = max(createdAt, lastRestoredAt) + 30 d (D7)
   name?: string;
@@ -70,6 +70,7 @@ export interface SpawnEntry {
 /** OrbRecord.spawns keeps this many entries, oldest first. */
 export const SPAWN_HISTORY = 10;
 
+/** Any Cloudflare Containers instance size. "lite" (256 MiB) is used only by the provider container. */
 export type InstanceSpec =
   | "lite"
   | "standard-1"
@@ -78,6 +79,9 @@ export type InstanceSpec =
   | "standard-4"
   | { vcpu: number; memoryMib: number; diskMb: number };
 
+/** An orb size. "lite" is too small for the orb image, so config validation rejects it. */
+export type OrbInstanceSpec = Exclude<InstanceSpec, "lite">;
+
 /** Per-orb record in OrbSession storage under key "orb". */
 export interface OrbRecord {
   /** Schema version (D13). Old and new Worker code share storage; a missing v reads as 1. */
@@ -85,7 +89,7 @@ export interface OrbRecord {
   orbId: string;
   state: OrbState;
   imageKey: string;
-  instance: InstanceSpec;
+  instance: OrbInstanceSpec;
   handle?: SnapshotHandle; // per-orb snapshot (last pause or checkpoint)
   bootstrapTokenSha?: string; // first 16 hex of sha256(ORB_TOKEN) for the running bootstrap
   awakeSince?: string;
@@ -136,7 +140,7 @@ export type ProjectSnapshotRefresh = "off" | "on-change";
 
 /** Provider-level configuration, derived from cf-orbs.config.jsonc and passed as Worker vars (JSON string in CF_ORBS_CONFIG). */
 export interface ProviderConfig {
-  instance: InstanceSpec; // default { vcpu: 4, memoryMib: 12288, diskMb: 20000 }
+  instance: OrbInstanceSpec; // default { vcpu: 4, memoryMib: 12288, diskMb: 20000 }
   maxRunning: number; // default 20
   maxAwakeHours: number; // default 12
   checkpointMinutes: number; // default 0 = off