@pithy-sh/core 0.1.0

package/src/semver/semver.ts

@@ -0,0 +1,156 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * Semantic versions: one parse, one format, one order.
+ *
+ * Anything that has to *rank* versions needs semver §11.4 — order a release feed, decide what sits
+ * between installed and latest, sort a prerelease against the stable it precedes. §11.4 is short and
+ * every clause of it is a trap: numeric identifiers compare numerically and alphanumerics compare
+ * lexically, a numeric identifier ranks *below* an alphanumeric one, a longer identifier set wins when
+ * every shared identifier is equal, and a stable outranks every prerelease of the same core. Each of
+ * those is one line to get wrong, and getting one wrong shows up as a feed in the wrong order rather
+ * than as an error.
+ *
+ * So it lives here once. The kit's update notifier uses it and ignores the prerelease field, which is
+ * the narrowness it wants rather than a second implementation.
+ *
+ * **The parse is a split, not a string.** A version held as one string compares as text, and text puts
+ * `1.10.0` below `1.9.0`. Split into numbers, the core comparison is three integer comparisons — and
+ * for an adopter storing versions in SQLite, three integer columns are a row-value predicate
+ * (`(major, minor, patch) > (?, ?, ?)`) that the database orders correctly on its own. SQL cannot
+ * express prerelease precedence in that predicate, so a query built that way over-selects a stable
+ * against a prerelease of the same core and {@link compareSemver} settles it in app code.
+ */
+
+import { z } from "zod";
+
+/** The largest version part that survives a round trip through a number. */
+const MAX_PART = Number.MAX_SAFE_INTEGER;
+
+/**
+ * Semver's grammar, minus what carries no order. Build metadata (`+sha`) is matched so it can be
+ * discarded: the spec excludes it from precedence, so keeping it would imply an ordering it does not
+ * have. A leading `v` is tolerated because tags and changelogs carry one.
+ */
+const SEMVER_PATTERN =
+  /^v?(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/;
+
+export const Semver = z
+  .object({
+    major: z.number().int().nonnegative().describe("The major version. A breaking change increments it."),
+    minor: z.number().int().nonnegative().describe("The minor version. A backwards-compatible feature increments it."),
+    patch: z.number().int().nonnegative().describe("The patch version. A backwards-compatible fix increments it."),
+    prerelease: z
+      .string()
+      .nullable()
+      .describe(
+        "The prerelease tag without its leading hyphen (`rc.1`), or null for a stable release. Null sorts above any prerelease of the same core.",
+      ),
+  })
+  .describe(
+    "A semantic version split into its parts. Three numbers a database can compare as a row value, plus the prerelease tag that only `compareSemver` can order.",
+  );
+export type Semver = z.output<typeof Semver>;
+
+/** How far behind a version is, in each place. */
+export const SemverGap = z
+  .object({
+    major: z.number().int().nonnegative().describe("How many major versions have been published since."),
+    minor: z.number().int().nonnegative().describe("How many minor versions have accrued within the current major."),
+    patch: z.number().int().nonnegative().describe("How many patch versions have accrued within the current minor."),
+  })
+  .describe(
+    "How far an installed version is behind the latest one, counted in version places. Three counts and nothing else, so two versions with the same core are zero apart here however their prereleases rank — that difference is precedence, and `compareSemver` is what answers it.",
+  );
+export type SemverGap = z.output<typeof SemverGap>;
+
+/** Parse a version string into its parts. Returns null for anything that is not a version. */
+export function parseSemver(value: string): Semver | null {
+  const match = SEMVER_PATTERN.exec(value.trim());
+  if (!match) return null;
+  const [, major, minor, patch, prerelease] = match;
+  const parts = [Number(major), Number(minor), Number(patch)] as const;
+  // A part past a safe integer cannot round-trip, and silently truncating one would make the
+  // comparison lie. Refuse it as unparseable instead.
+  if (parts.some((part) => part > MAX_PART)) return null;
+  return { major: parts[0], minor: parts[1], patch: parts[2], prerelease: prerelease ?? null };
+}
+
+/** Render a parsed version back to its canonical string. */
+export function formatSemver(version: Semver): string {
+  const core = `${version.major}.${version.minor}.${version.patch}`;
+  return version.prerelease === null ? core : `${core}-${version.prerelease}`;
+}
+
+/** Compare two dot-separated prerelease identifiers, per semver §11.4. */
+function comparePrereleaseIdentifier(a: string, b: string): number {
+  const aNumeric = /^\d+$/.test(a);
+  const bNumeric = /^\d+$/.test(b);
+  // Numeric identifiers compare numerically and always rank below alphanumeric ones. As digit strings
+  // rather than through `Number`, because an identifier is not bounded the way `MAX_PART` bounds the
+  // core: above 2^53 two distinct identifiers round to the same float and compare equal, which would
+  // leave a `latest` decided by whatever order the rows arrived in. The grammar forbids a leading zero,
+  // so more digits is a larger number and equal lengths order lexicographically.
+  if (aNumeric && bNumeric) {
+    if (a.length !== b.length) return a.length - b.length;
+    return a < b ? -1 : a > b ? 1 : 0;
+  }
+  if (aNumeric) return -1;
+  if (bNumeric) return 1;
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+/** Compare two prerelease tags. A larger set of identifiers wins when every shared one is equal. */
+function comparePrerelease(a: string, b: string): number {
+  const left = a.split(".");
+  const right = b.split(".");
+  for (let i = 0; i < Math.max(left.length, right.length); i += 1) {
+    const l = left[i];
+    const r = right[i];
+    if (l === undefined) return -1;
+    if (r === undefined) return 1;
+    const ordered = comparePrereleaseIdentifier(l, r);
+    if (ordered !== 0) return ordered;
+  }
+  return 0;
+}
+
+/**
+ * Compare two versions by semver precedence. Negative when `a` precedes `b`. Suitable as an
+ * `Array.prototype.sort` comparator, so it accepts the nulls {@link parseSemver} returns — an
+ * unparseable version sorts below every real one rather than throwing mid-sort.
+ */
+export function compareSemver(a: Semver | null, b: Semver | null): number {
+  if (a === null || b === null) return a === b ? 0 : a === null ? -1 : 1;
+  if (a.major !== b.major) return a.major - b.major;
+  if (a.minor !== b.minor) return a.minor - b.minor;
+  if (a.patch !== b.patch) return a.patch - b.patch;
+  if (a.prerelease === b.prerelease) return 0;
+  // Stable outranks any prerelease of the same core.
+  if (a.prerelease === null) return 1;
+  if (b.prerelease === null) return -1;
+  return comparePrerelease(a.prerelease, b.prerelease);
+}
+
+/**
+ * How far `installed` is behind `latest`, per place.
+ *
+ * Each place counts only what accrued while the places above it stayed put, which is what makes the
+ * number mean something: `1.2.3` against `1.6.1` is four minors and one patch behind, not four minors
+ * and *negative two* patches. Somebody running something newer than we know about is ahead, not behind,
+ * so the gap floors at zero rather than going negative.
+ *
+ * **A zero gap is not a claim of being current.** Two versions with the same core sit zero places apart
+ * whatever their prereleases say, so `1.2.3-rc.1` against `1.2.3` measures zero even though it precedes
+ * it. That is the shape being honest about its limits rather than a bug to paper over: counting places
+ * cannot express a prerelease, {@link compareSemver} is what ranks them, and inventing a phantom patch
+ * here would put a number on screen that no release actually carries.
+ */
+export function semverGap(installed: Semver, latest: Semver): SemverGap {
+  if (compareSemver(installed, latest) >= 0) return { major: 0, minor: 0, patch: 0 };
+  const major = Math.max(0, latest.major - installed.major);
+  const minor = major > 0 ? latest.minor : Math.max(0, latest.minor - installed.minor);
+  const patch = major > 0 || minor > 0 ? latest.patch : Math.max(0, latest.patch - installed.patch);
+  return { major, minor, patch };
+}

package/src/text/comments.ts

@@ -0,0 +1,165 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * `source` with every comment blanked — the one comment stripper this repository's gates share.
+ *
+ * A tripwire that reads source has to walk past prose, because this repository's docblocks quote the
+ * very thing their gate forbids: a paragraph explaining why a config must never read `process.env`, a
+ * header naming `@cloudflare/workers-types` in a sentence. Blanking is what makes the prose invisible
+ * without making the file shorter.
+ *
+ * **Blanked rather than deleted: every character becomes a space and every newline survives**, so the
+ * line number in a failure is the line number in the file, a caller may split on `\n` and index, and a
+ * caller may slice the blanked text at an offset it measured on the original. Deleting is the cheaper
+ * thing to write and it silently joins the code either side of a block comment onto one line, which
+ * costs the position of everything below it.
+ *
+ * **It walks the source rather than matching a pattern, because the pattern has two measured false
+ * negatives.** One `replace` over a comment pattern has no notion of a string, and a string is where a
+ * comment can be forged:
+ *
+ * - `const base = "https://api.cloudflare.com";` opens a line comment at the `//` inside the URL, and
+ *   everything after it on that line is blanked — a `process.env.CLOUDFLARE_API_TOKEN` read beside it,
+ *   a `D1Database` beside it, whatever the caller was looking for.
+ * - `include: ["**\/*.workers.test.ts"]` opens a block comment at the `/*` inside the glob, which runs
+ *   to the next `*\/` anywhere later in the file — the next docblock will do — and blanks every line
+ *   between.
+ *
+ * Both were measured against planted source, and both are silent: the scan reports nothing and passes.
+ * A prohibition that a URL can switch off is worse than no prohibition, because the file it exempts
+ * looks scanned.
+ *
+ * **Strings are stepped over, not blanked.** The job is comments, and preserving a string keeps a real
+ * read inside a template — `` `${process.env.CLOUDFLARE_API_TOKEN}` `` — visible to the caller. A string
+ * that merely *contains* the text is then a false positive, which is the direction a gate should fail in.
+ *
+ * **A regex literal is stepped over too**, because `/^["']|["']$/` is a quote a string state would open
+ * on, and a runaway string swallows every line to the next quote. Told apart from division by the last
+ * significant character: a `/` where a value may begin starts a literal, and one after an operand is a
+ * divide. An unterminated string or regex stops at the newline, so a bad guess costs one line rather
+ * than the rest of the file.
+ *
+ * ## Why it lives in `@pithy-sh/core`, of all places
+ *
+ * It was written in `@pithy-sh/cli`'s `ci/sourceFiles.ts`, beside the walk its first three callers used
+ * (#437). `packages/core/src/worker-safety.test.ts` is the caller that could not follow it there:
+ * it guards which bare specifiers core's shipped source imports, it had the naive pattern, and
+ * `@pithy-sh/core` must never depend on `@pithy-sh/cli` — core is bundled into the adopter's Worker, so
+ * its dependency set is a shipped surface and the arrow runs cli → core only (#439).
+ *
+ * The alternatives were a documented copy and a drift gate over two copies. That pattern is real here —
+ * `envIsolation.workers.test.ts` restates `CLOUDFLARE_ENV_KEYS` under exactly this constraint — and it
+ * holds for two string constants, which a gate can compare for equality. Over a hundred-line walk it
+ * degrades into comparing function text, which changes on a rename and says nothing about behavior.
+ *
+ * So the third home, and core is the only package every caller already imports: the CLI, `email`,
+ * `payments` and `ui-react` all declare it, and `worker-safety.test.ts` reaches it with a relative path.
+ * The cost is honest and small. This is source-text tooling inside the package that ships into a Worker
+ * — but core has no barrel, so a module nothing imports is never reached by an adopter's bundler at all,
+ * and the price is bytes in a tarball rather than bytes in a Worker. And it earns its keep as a Worker
+ * neighbor on its own terms: **it imports nothing and touches no Node builtin**, which is the property
+ * `worker-safety.test.ts` exists to enforce, so the gate now polices the stripper it reads with.
+ */
+export function blankComments(source: string): string {
+  let out = "";
+  let previous = "";
+  let index = 0;
+  while (index < source.length) {
+    const char = source[index] as string;
+    const pair = source.slice(index, index + 2);
+    if (pair === "//" || pair === "/*") {
+      const stop = endOfComment(source, index, pair);
+      out += source.slice(index, stop).replace(/[^\n]/g, " ");
+      index = stop;
+      continue;
+    }
+    if (char === '"' || char === "'" || char === "`") {
+      const stop = endOfQuoted(source, index, char, char !== "`");
+      out += source.slice(index, stop);
+      index = stop;
+      previous = char;
+      continue;
+    }
+    if (char === "/" && VALUE_POSITION.has(previous)) {
+      const stop = endOfRegex(source, index);
+      out += source.slice(index, stop);
+      index = stop;
+      previous = "/";
+      continue;
+    }
+    out += char;
+    if (!/\s/.test(char)) previous = char;
+    index += 1;
+  }
+  return out;
+}
+
+/**
+ * After one of these, a `/` opens a regex literal; after anything else it divides. The empty string is
+ * the start of the file. A wrong guess is bounded — see {@link endOfRegex}.
+ */
+const VALUE_POSITION = new Set([
+  "",
+  "(",
+  ",",
+  "=",
+  ":",
+  "[",
+  "!",
+  "&",
+  "|",
+  "?",
+  "{",
+  "}",
+  ";",
+  "+",
+  "-",
+  "*",
+  "%",
+  "^",
+  "~",
+  "<",
+  ">",
+]);
+
+/** Where a comment ends. An unterminated block comment runs to the end of the file, as it does for tsc. */
+function endOfComment(source: string, start: number, pair: string): number {
+  if (pair === "//") {
+    const newline = source.indexOf("\n", start);
+    return newline === -1 ? source.length : newline;
+  }
+  const close = source.indexOf("*/", start + 2);
+  return close === -1 ? source.length : close + 2;
+}
+
+/** Where a quoted run ends: past its closing quote, or at the newline a single-line quote cannot cross. */
+function endOfQuoted(source: string, start: number, quote: string, singleLine: boolean): number {
+  for (let index = start + 1; index < source.length; index += 1) {
+    const char = source[index];
+    if (char === "\\") {
+      index += 1;
+      continue;
+    }
+    if (char === quote) return index + 1;
+    if (char === "\n" && singleLine) return index;
+  }
+  return source.length;
+}
+
+/** Where a regex literal ends. A `/` inside a character class does not close it; a newline does. */
+function endOfRegex(source: string, start: number): number {
+  let inClass = false;
+  for (let index = start + 1; index < source.length; index += 1) {
+    const char = source[index];
+    if (char === "\\") {
+      index += 1;
+      continue;
+    }
+    if (char === "\n") return index;
+    if (char === "[") inClass = true;
+    else if (char === "]") inClass = false;
+    else if (char === "/" && !inClass) return index + 1;
+  }
+  return source.length;
+}

package/src/version.generated.ts

@@ -0,0 +1,16 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+// GENERATED by scripts/stampVersions.ts — do not edit by hand. Regenerate with `bun run stamp-versions`.
+//
+// A Worker cannot read its own package.json, so this is how @pithy-sh/core knows its own version at
+// runtime. The capability attaches it, and `GET /control-plane/manifest` reports it per capability —
+// which is what answers "should this project upgrade" and "is this customer exposed to what we just
+// fixed". Those questions are only answerable per module, because a project composes some capabilities
+// and not others.
+
+/** This package's npm name — the join key against a release feed. */
+export const PACKAGE_NAME = "@pithy-sh/core";
+
+/** This package's version, stamped from its own package.json at generation time. */
+export const PACKAGE_VERSION = "0.1.0";

package/src/worker/health.ts

@@ -0,0 +1,42 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * **Where every Pithy Worker answers liveness — written once, read by everyone who needs it.**
+ *
+ * `createBackend` mounts this route, the CLI's route allowlist keeps it worker-first, `pithy deploy`
+ * probes it after a release, and the bare home screen a no-auth scaffold ships fetches it. Four sites,
+ * one path, and until #400 each of them wrote it out.
+ *
+ * The failure that earned this module is the quietest one in the front end. `home.bare.tsx` is the
+ * **only** screen a project with no auth composed gets, and its entire content is that one request. A
+ * rename here without a matching edit there renders *"The worker says: unknown."* — a 200, no error, no
+ * failed build, nothing in a log. The adopter's first screen showing a word that is not a status, for a
+ * reason nowhere on the page.
+ *
+ * A gate comparing the copies would have watched that. This removes it instead: the template imports
+ * the constant, so a rename moves the screen with it, and there is no second string left to disagree
+ * with. `docs/CONVENTIONS.md` § *Seeded files* is the general form — **removing the class beats
+ * watching it** — and #377, #366, #393 and #394 are the same move made earlier.
+ *
+ * ## Why a module of its own
+ *
+ * Because a client bundle imports it. Everything else in `@pithy-sh/core` that a route path could sit
+ * beside pulls Hono, the Workers types, or both, and the scaffolded SPA is a browser program that must
+ * import neither. This file declares one string and imports nothing, so the seeded screen can read it
+ * without dragging a server runtime into the client's program.
+ */
+
+/**
+ * `GET /health` — public, and deliberately so.
+ *
+ * It reads nothing about the caller, so there is no session to send it. That is what makes it the one
+ * request the bare home screen can make with no auth capability in the project, and why
+ * `sameOrigin.test.ts` exempts that screen's `fetch` rather than routing it through a credentialed
+ * primitive.
+ *
+ * The leading slash is part of the value. Hono mounts it, `firstSegment` splits it, and `verifyDeploy`
+ * appends it to a declared origin — all three want the same string, and a bare `health` would make two
+ * of them concatenate wrongly in silence.
+ */
+export const HEALTH_PATH = "/health";

package/src/worker/identity.ts

@@ -0,0 +1,243 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * What a running Worker knows about itself — the three vars every Pithy Worker is scaffolded with, and
+ * the one reader for them.
+ *
+ * The Cloudflare runtime hands a script **nothing** about its own identity. `TraceItem.scriptName` is
+ * what a *tail consumer* sees about someone else, `version_metadata` carries an id, a tag and a
+ * creation time but no name, and `navigator.userAgent` is the constant `"Cloudflare-Workers"` in every
+ * Worker alive. So
+ * identity is stamped, not derived: `pithy init` and `pithy worker add` write `PROJECT`, `ENVIRONMENT`,
+ * and `WORKER` into every environment stanza of the Worker's own `wrangler.jsonc`.
+ *
+ * Stamping also beats deriving even where a value looks recoverable. A host's script name leads with
+ * its project, but `<project>-<env>-<capability>` cannot be parsed back into its parts once a project
+ * name contains a hyphen — and wrangler appends `-staging`/`-prod` at deploy, so the script name is not
+ * even stable across environments while `apps/<name>/` is.
+ *
+ * The names live here because they had already been copied: `ENVIRONMENT_VAR` was declared privately in
+ * both `workflow/host.ts` and `controlPlane/capability.ts`, character for character. A third copy for
+ * `WORKER` would have made the drift structural — the arrangement where a rule stops being one rule.
+ */
+
+/** The var naming the owning project: the root `pithy.config.ts` `name`, kebabed. */
+export const PROJECT_VAR = "PROJECT";
+
+/** The var naming the environment this deployment serves — `dev`, `staging`, or `prod`. */
+export const ENVIRONMENT_VAR = "ENVIRONMENT";
+
+/**
+ * The var carrying a Worker's **own** dev origin, from `pithy dev` to whatever launches that Worker.
+ *
+ * Not stamped into `wrangler.jsonc` like the three above, and that is the whole point of it. A dev port
+ * is *allocated* — every checkout reserves its own block — so this is the one identity value a file in
+ * the repository cannot state: written down, it is right in the first checkout on a machine and wrong
+ * in every other one (#462).
+ *
+ * It lives here for the reason the others do. `pithy dev` writes it and `@pithy-sh/vite` reads it, and
+ * those two packages cannot import each other — the CLI depends on vite's package, and vite's may not
+ * depend on the CLI. A privately declared copy on each side is the arrangement where one rule quietly
+ * becomes two.
+ *
+ * **A carrier, not a binding.** It reaches a *process*, not a Worker: `process.env` inside workerd is
+ * that script's own vars and nothing else. `@pithy-sh/vite`'s `devWorkerConfig()` is what turns it into
+ * the Worker's `BASE_URL`, which is the binding anything at runtime actually reads.
+ */
+export const WORKER_ORIGIN_VAR = "PITHY_WORKER_ORIGIN";
+
+/**
+ * The var naming the Worker itself: its `apps/<name>` **directory** name, not its deploy name.
+ *
+ * The directory name is the identity everything else already keys on — the `apps/*` registry, the
+ * `--worker` flag, the `.dev.config.json` port block. The deploy name (`<project>-<name>`) would
+ * re-encode the project as noise beside a `project` column that already carries it, and the deployed
+ * script's real name varies by environment where the directory does not.
+ */
+export const WORKER_VAR = "WORKER";
+
+/**
+ * The version-metadata binding Cloudflare injects, naming the exact build that is running.
+ *
+ * Not a var — a binding, declared as `"version_metadata": { "binding": "CF_VERSION_METADATA" }` and
+ * populated by the platform rather than by the scaffold. It belongs beside the three vars anyway,
+ * because it answers the same question they do and is read on the same path: this is what a Worker knows
+ * about itself.
+ *
+ * **The name is the join.** It is what `pithy init` and `pithy worker add` write and what this module
+ * reads; binding a differently-named one creates a binding nothing consumes, which is the failure this
+ * whole thread is repairing — the reader shipped, the template never declared it, and the field was
+ * silently absent in every scaffolded project.
+ */
+export const VERSION_METADATA_BINDING = "CF_VERSION_METADATA";
+
+/** Where a Worker is running, as it can state about itself. Every field is `null` when unstamped. */
+export interface WorkerIdentity {
+  /** The owning project, or `null` when the Worker carries no `PROJECT` var. */
+  project: string | null;
+  /** The environment this deployment serves, or `null` when unstamped. */
+  environment: string | null;
+  /** The Worker's `apps/<name>` directory name, or `null` when unstamped. */
+  worker: string | null;
+  /**
+   * The deployed build's Cloudflare version id, or `null` off-platform and wherever the
+   * `CF_VERSION_METADATA` binding is absent.
+   *
+   * Opaque and per-deploy: it identifies *exactly which build* is running, which is the right answer for
+   * forensics, for reproducing a report, and for pinning what an audited action ran against. It carries
+   * no version semantics, so it says nothing about which features a Worker has — that is what the
+   * composed package versions in the control-plane manifest are for.
+   */
+  version: string | null;
+}
+
+/**
+ * Everything the `CF_VERSION_METADATA` binding carries about the build that is running.
+ *
+ * **Measured, not read off the docs.** A `wrangler dev` (4.120.1 / miniflare 4) against a Worker
+ * declaring `version_metadata` hands the binding as `{ id, tag, timestamp }` — three own keys, every
+ * value a string, `timestamp` an ISO-8601 instant. Every field is independently `null` here, because a
+ * partial binding is what a platform change looks like from inside a Worker and losing the id over a
+ * renamed sibling would be the worse trade.
+ *
+ * **It names a *version*, never a deployment.** That distinction is the whole ceiling on what a client
+ * can conclude from it — see {@link workerVersionMetadata}.
+ */
+export interface WorkerVersionMetadata {
+  /** The version id: opaque, per version, and the answer to "which build". `null` where the binding is. */
+  id: string | null;
+  /**
+   * The version tag, set only by `wrangler versions upload --tag`, or `null`.
+   *
+   * Empty in every local dev and in every deploy nobody tagged, so `""` reads as absent rather than as a
+   * tag to compare against. Read here so this reader mirrors the binding; deliberately **not** stamped
+   * on the control-plane header — it is adopter-authored free text, and the two questions a management
+   * client asks are answered without it.
+   */
+  tag: string | null;
+  /**
+   * When this **version was uploaded**, ISO-8601, verbatim as the platform issued it — or `null`.
+   *
+   * **Cloudflare has two objects here, and this binding describes one of them.** A *version* is an
+   * immutable upload of code and config: an id, a created timestamp and a tag, fixed at upload and never
+   * again. A *deployment* points at one or more versions with traffic percentages, and is its own object
+   * with its own id and its own time. `CF_VERSION_METADATA` reports the **version**, faithfully — and
+   * the runtime hands a script **no binding for the deployment at all**.
+   *
+   * Everything else follows from that. A rollback creates a *new deployment* aimed at an *existing
+   * version*, so nothing in this binding moves: not staleness, not ambiguity, a different object. The
+   * same answer covers the next question and the one after — a traffic split, a gradual rollout, which
+   * deployment is serving: a Worker cannot see any of it. An ordinary redeploy is not affected, because
+   * every `wrangler deploy` uploads and so mints a new version, id and all, even for a one-character
+   * change.
+   *
+   * Measured, 2026-08-10, which is what turned that from a reading of the docs into a fact: a probe
+   * Worker on a real account, version `A` uploaded, `B` four seconds later, then a real `wrangler
+   * rollback` to `A`. Two minutes on, the Worker reported `A`'s id **and `A`'s original timestamp**,
+   * unmoved — while wrangler's own rollback output named the new deployment's version list.
+   *
+   * The value is relayed for comparison and never interpreted. A consumer's rule is
+   * `workerBuildChanged` in `controlPlane/wire.ts`: anything that moved is a change, and a direction is
+   * not a meaning — propagation lag alone can make an older version answer for a while after a deploy.
+   *
+   * `null` for anything that is not a parseable instant. That is the one place this reader refuses
+   * rather than relays, and the consumer is the reason: a client does `Date.parse` on it and compares,
+   * an unparseable string is `NaN`, and every `NaN` comparison is false — so garbage would read as
+   * "not newer", which is silently indistinguishable from "unchanged".
+   */
+  createdAt: string | null;
+}
+
+/** One binding field, or `null` for anything that is not a non-empty string. */
+function carried(meta: Record<string, unknown>, field: string): string | null {
+  const value = meta[field];
+  return typeof value === "string" && value.trim() !== "" ? value : null;
+}
+
+/** One var, trimmed, or `null` for anything that is not a non-empty string. */
+function stamped(env: Record<string, unknown>, name: string): string | null {
+  const value = env[name];
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  return trimmed === "" ? null : trimmed;
+}
+
+/**
+ * Read a Worker's stamped identity off its `env`.
+ *
+ * **Never throws, and never guesses.** Both matter on the one call path this exists for: the audit
+ * recorder stamps origin onto every event, and the recorder is contractually non-fatal — a throw here
+ * would turn "this row has no origin" into "there is no row", which is the strictly worse failure. An
+ * absent var is an ordinary, permanent state: a Worker scaffolded before these vars existed carries
+ * none of them and nothing back-fills it, so `null` is reported rather than inferred. An invented
+ * origin would be indistinguishable from a real one for as long as the trail is kept.
+ */
+export function workerIdentity(env: unknown): WorkerIdentity {
+  if (typeof env !== "object" || env === null || Array.isArray(env)) {
+    return { project: null, environment: null, worker: null, version: null };
+  }
+  const vars = env as Record<string, unknown>;
+  return {
+    project: stamped(vars, PROJECT_VAR),
+    environment: stamped(vars, ENVIRONMENT_VAR),
+    worker: stamped(vars, WORKER_VAR),
+    version: workerVersion(env),
+  };
+}
+
+/**
+ * Read the whole `CF_VERSION_METADATA` binding: which build is running, and when that build was made.
+ *
+ * **The one reader of the binding**, which is why it returns all of it. The seam used to take the id and
+ * drop the rest, and the module docstring above described a two-field binding — so the field this
+ * function exists for was discarded by a reader that did not know it was there.
+ *
+ * ## What a client can conclude
+ *
+ * Holding the last `(id, createdAt)` it saw, and comparing field by field only where both sides carried
+ * a value: anything that differs is a change. Absence on either side is silence, never change.
+ * `workerBuildChanged` in `controlPlane/wire.ts` is that rule, written once so no client hand-rolls it.
+ *
+ * ## What it cannot see, and why that is a boundary rather than a gap
+ *
+ * **This binding describes a version. Nothing inside a Worker can observe a deployment** — see
+ * {@link WorkerVersionMetadata.createdAt} for the two objects and the measurement. So a rollback, a
+ * traffic split, a gradual rollout: all invisible here, and no field the seam could add would change
+ * that, because the runtime hands a script no binding for the object that carries them. A client that
+ * needs a deployment reads Cloudflare's deployments API, in the customer's own account.
+ *
+ * The temptation is to synthesise one. Isolate boot time is the only in-Worker candidate and it is
+ * worse than nothing: it changes on every cold start, so it would report a redeploy dozens of times a
+ * day, and a false change costs more than a missed one for a client that invalidates a rendered pane on
+ * it. Nothing is stamped.
+ *
+ * Same never-throws, never-guesses contract as {@link workerIdentity}.
+ */
+export function workerVersionMetadata(env: unknown): WorkerVersionMetadata {
+  const absent: WorkerVersionMetadata = { id: null, tag: null, createdAt: null };
+  if (typeof env !== "object" || env === null || Array.isArray(env)) return absent;
+  const meta = (env as Record<string, unknown>)[VERSION_METADATA_BINDING];
+  if (typeof meta !== "object" || meta === null) return absent;
+  const fields = meta as Record<string, unknown>;
+  const createdAt = carried(fields, "timestamp");
+  return {
+    id: carried(fields, "id"),
+    tag: carried(fields, "tag"),
+    // Relayed verbatim, never re-encoded — but only once it is a time at all.
+    createdAt: createdAt !== null && Number.isFinite(Date.parse(createdAt)) ? createdAt : null,
+  };
+}
+
+/**
+ * The deployed build's version id, off the `CF_VERSION_METADATA` binding, or `null`.
+ *
+ * Kept on its own because four callers want the id and nothing else: the request logger's `version`
+ * correlation field, `/health`, the control-plane manifest, and the seam's response header. Its shape
+ * is unchanged and deliberately so — every one of those compares or records a single opaque string, and
+ * widening it would have rewritten an audit column and a wire field to carry something none of them
+ * asked for. {@link workerVersionMetadata} is where the rest of the binding lives.
+ */
+export function workerVersion(env: unknown): string | null {
+  return workerVersionMetadata(env).id;
+}