From 8d1b2b5df1d0db58d63d4b84f8b19bff3674e33d Mon Sep 17 00:00:00 2001
From: Matt Kane <m@mk.gg>
Date: Sun, 31 May 2026 11:57:11 +0100
Subject: [PATCH 1/5] feat(registry): release env requires + admin
 compatibility gate
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Plugins published to the experimental registry can declare release-level
environment constraints. A manifest's `requires` block (e.g.
`{ "env:emdash": ">=1.0.0", "env:astro": ">=4.16" }`) is validated at
publish time and written into the release record.

- registry-client: new dependency-free `./env` module shared by the CLI,
  server, and admin — `parseRequires` (guards the lexicon-`unknown`
  value), `isValidVersionRange`, `satisfiesRange`, and
  `checkEnvCompatibility` over a focused semver-range grammar
  (comparators, caret, tilde, partial versions, wildcard, AND sets).
- plugin-cli: `RequiresSchema` on the manifest, threaded release-level
  into `publishRelease` (never via the profile input); JSON Schema
  regenerated.
- core: capture the host Astro version in `astro:config:setup` and
  surface it (with EmDash VERSION) on the admin manifest. New
  `assertEnvCompatible` gate refuses incompatible install AND update
  with `ENV_INCOMPATIBLE` (409), placed after yank-check, before the
  artifact fetch.
- admin: RegistryPluginDetail reads host versions, renders a localized
  compatibility warning and disables Install when unsatisfied.

Closes #1031.
---
 .changeset/registry-env-requires.md           |   8 +
 .../src/components/RegistryPluginDetail.tsx   |  61 +++-
 packages/admin/src/lib/api/client.ts          |   2 +
 packages/admin/src/lib/api/registry.ts        |  21 ++
 packages/core/src/api/errors.ts               |   2 +
 packages/core/src/api/handlers/index.ts       |   2 +
 packages/core/src/api/handlers/registry.ts    |  76 +++-
 packages/core/src/astro/integration/index.ts  |  26 ++
 .../core/src/astro/integration/runtime.ts     |   8 +
 .../api/admin/plugins/registry/[id]/update.ts |   5 +-
 .../api/admin/plugins/registry/install.ts     |   9 +-
 packages/core/src/astro/types.ts              |   6 +
 packages/core/src/emdash-runtime.ts           |   1 +
 .../unit/api/registry-env-compat.test.ts      |  78 ++++
 .../schemas/emdash-plugin.schema.json         |  27 ++
 packages/plugin-cli/src/commands/publish.ts   |   1 +
 packages/plugin-cli/src/manifest/schema.ts    |  38 ++
 packages/plugin-cli/src/manifest/translate.ts |   8 +
 packages/plugin-cli/src/publish/api.ts        |  11 +
 .../plugin-cli/tests/manifest-schema.test.ts  |  54 +++
 .../tests/manifest-translate.test.ts          |  27 ++
 packages/plugin-cli/tests/publish.test.ts     |  22 ++
 packages/registry-client/package.json         |   4 +
 packages/registry-client/src/env/index.ts     | 334 ++++++++++++++++++
 packages/registry-client/src/index.ts         |   9 +
 packages/registry-client/tests/env.test.ts    | 160 +++++++++
 packages/registry-client/tsdown.config.ts     |   1 +
 27 files changed, 996 insertions(+), 5 deletions(-)
 create mode 100644 .changeset/registry-env-requires.md
 create mode 100644 packages/core/tests/unit/api/registry-env-compat.test.ts
 create mode 100644 packages/registry-client/src/env/index.ts
 create mode 100644 packages/registry-client/tests/env.test.ts

diff --git a/.changeset/registry-env-requires.md b/.changeset/registry-env-requires.md
new file mode 100644
index 000000000..b8988076e
--- /dev/null
+++ b/.changeset/registry-env-requires.md
@@ -0,0 +1,8 @@
+---
+"@emdash-cms/registry-client": minor
+"@emdash-cms/plugin-cli": minor
+"@emdash-cms/admin": minor
+"emdash": minor
+---
+
+Registry plugins can now declare environment requirements. A plugin's manifest may set a release-level `requires` block (e.g. `{ "env:emdash": ">=1.0.0", "env:astro": ">=4.16" }`), which is published into the release record. When browsing a registry plugin, the admin compares those constraints against the running EmDash and Astro versions: if the host doesn't satisfy them, it shows a compatibility warning and disables the Install button. The server enforces the same check on install and update, refusing an incompatible release with `ENV_INCOMPATIBLE` so the gate can't be bypassed.
diff --git a/packages/admin/src/components/RegistryPluginDetail.tsx b/packages/admin/src/components/RegistryPluginDetail.tsx
index f0cd9260a..41b75f2c1 100644
--- a/packages/admin/src/components/RegistryPluginDetail.tsx
+++ b/packages/admin/src/components/RegistryPluginDetail.tsx
@@ -14,6 +14,7 @@
  */
 
 import { Badge, Button, LinkButton, Select } from "@cloudflare/kumo";
+import { checkEnvCompatibility } from "@emdash-cms/registry-client/env";
 import { useLingui } from "@lingui/react/macro";
 import { ShieldCheck, Warning } from "@phosphor-icons/react";
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
@@ -22,6 +23,7 @@ import * as React from "react";
 
 import {
 	canonicalCapabilitiesForDriftCheck,
+	fetchHostEnv,
 	getRegistryPackage,
 	installRegistryPlugin,
 	listRegistryReleases,
@@ -59,6 +61,13 @@ export function RegistryPluginDetail({ pluginId, config }: RegistryPluginDetailP
 		},
 	});
 
+	// Host environment versions (`env:emdash`, `env:astro`) — used to evaluate
+	// the selected release's `requires` constraints before offering install.
+	const { data: hostEnv } = useQuery({
+		queryKey: ["host-env"],
+		queryFn: fetchHostEnv,
+	});
+
 	// Parse `<publisher>/<slug>` out of the route param. The publisher
 	// segment is either a handle (`example.dev`) or a DID
 	// (`did:plc:abc...`). Slugs are `[A-Za-z][A-Za-z0-9_-]*` (no `/`),
@@ -211,6 +220,19 @@ export function RegistryPluginDetail({ pluginId, config }: RegistryPluginDetailP
 
 	const policyOk =
 		release && pkg ? releasePassesPolicy(release, { did: pkg.did, slug }, config.policy) : true;
+
+	// Environment compatibility: compare the selected release's `requires`
+	// constraints against the running host. `requires` is the lexicon's open
+	// `unknown` value; `checkEnvCompatibility` guards its shape. Mirrors the
+	// server-side install gate so the admin can't offer an install the server
+	// would reject. Empty while the host env is still loading (fail-open until
+	// the data arrives; the server gate is the authority either way).
+	const envMismatches = React.useMemo(() => {
+		if (!release || !hostEnv) return [];
+		return checkEnvCompatibility(release.release?.requires, hostEnv);
+	}, [release, hostEnv]);
+	const envOk = envMismatches.length === 0;
+
 	// Handle resolution affects display only -- installs are addressed
 	// by DID, so an unverified or missing handle doesn't block install.
 	// A handle that *claims* a value but doesn't verify (`status:
@@ -367,7 +389,7 @@ export function RegistryPluginDetail({ pluginId, config }: RegistryPluginDetailP
 					) : (
 						<Button
 							variant="primary"
-							disabled={!release || !policyOk || handleResult.status === "invalid"}
+							disabled={!release || !policyOk || !envOk || handleResult.status === "invalid"}
 							onClick={() => setShowConsent(true)}
 						>
 							{t`Install`}
@@ -434,6 +456,32 @@ export function RegistryPluginDetail({ pluginId, config }: RegistryPluginDetailP
 				</div>
 			) : null}
 
+			{/* Environment compatibility notice. Mirrors the server install gate
+			    (ENV_INCOMPATIBLE): the selected release declares `requires`
+			    constraints the running host doesn't satisfy. Install is
+			    disabled until the host is upgraded. */}
+			{release && !envOk ? (
+				<div
+					className="flex items-start gap-3 rounded-md border border-kumo-warning bg-kumo-warning/10 p-4 text-kumo-warning"
+					role="status"
+				>
+					<Warning className="mt-0.5 h-5 w-5 shrink-0" />
+					<div>
+						<p className="font-medium">{t`Not compatible with this environment`}</p>
+						<p className="mt-1 text-sm text-kumo-default">
+							{t`This release requires a newer environment than your site currently runs. Upgrade before installing.`}
+						</p>
+						<ul className="mt-2 space-y-1 text-sm text-kumo-default">
+							{envMismatches.map((m) => (
+								<li key={m.key}>
+									{t`${envLabel(m.key)} ${m.required} required — you have ${m.host}.`}
+								</li>
+							))}
+						</ul>
+					</div>
+				</div>
+			) : null}
+
 			{/* Description */}
 			{description ? <p className="text-base text-kumo-default">{description}</p> : null}
 
@@ -595,6 +643,17 @@ function isPreReleaseVersion(version: string): boolean {
 	return PRE_RELEASE_VERSION_RE.test(version);
 }
 
+/**
+ * Human-readable name for a `requires` env key. The known EmDash environments
+ * get their proper product names; anything else falls back to the key with the
+ * `env:` prefix stripped (product names, not localised strings).
+ */
+function envLabel(key: string): string {
+	if (key === "env:emdash") return "EmDash";
+	if (key === "env:astro") return "Astro";
+	return key.startsWith("env:") ? key.slice("env:".length) : key;
+}
+
 const YANKED_LABEL_VALUE = "security:yanked";
 
 /**
diff --git a/packages/admin/src/lib/api/client.ts b/packages/admin/src/lib/api/client.ts
index 94acb3497..0e436a167 100644
--- a/packages/admin/src/lib/api/client.ts
+++ b/packages/admin/src/lib/api/client.ts
@@ -54,6 +54,8 @@ export interface FindManyResult<T> {
  */
 export interface AdminManifest {
 	version: string;
+	/** Version of Astro the host is built with, when resolvable. */
+	astroVersion?: string;
 	hash: string;
 	collections: Record<
 		string,
diff --git a/packages/admin/src/lib/api/registry.ts b/packages/admin/src/lib/api/registry.ts
index 655ffe3b5..48d5ee2f2 100644
--- a/packages/admin/src/lib/api/registry.ts
+++ b/packages/admin/src/lib/api/registry.ts
@@ -26,12 +26,14 @@ import type {
 	ValidatedReleaseView,
 	ValidatedSearchPackages,
 } from "@emdash-cms/registry-client/discovery";
+import type { HostEnv } from "@emdash-cms/registry-client/env";
 import { i18n } from "@lingui/core";
 import { msg } from "@lingui/core/macro";
 
 import { API_BASE, apiFetch, parseApiResponse, throwResponseError } from "./client.js";
 
 export type { Did, Handle };
+export type { HostEnv };
 
 // ---------------------------------------------------------------------------
 // Types
@@ -294,6 +296,25 @@ export async function listRegistryReleases(
 	return client.listReleases(did, slug, opts);
 }
 
+/**
+ * Fetch the host environment versions (`env:emdash`, `env:astro`) the running
+ * EmDash install advertises, so a release's `requires` constraints can be
+ * evaluated client-side before offering install. Reads the admin manifest,
+ * which carries `version` (EmDash) and `astroVersion`. A `"dev"` EmDash build
+ * and a missing Astro version are omitted so the compat check skips them.
+ */
+export async function fetchHostEnv(): Promise<HostEnv> {
+	const response = await apiFetch(`${API_BASE}/manifest`);
+	const manifest = await parseApiResponse<{ version?: string; astroVersion?: string }>(
+		response,
+		i18n._(msg`Failed to fetch host environment`),
+	);
+	const host: HostEnv = {};
+	if (manifest.version && manifest.version !== "dev") host["env:emdash"] = manifest.version;
+	if (manifest.astroVersion) host["env:astro"] = manifest.astroVersion;
+	return host;
+}
+
 /**
  * Resolve a publisher DID to its claimed handle using the same
  * `LocalActorResolver` pattern as `@emdash-cms/plugin-cli` and
diff --git a/packages/core/src/api/errors.ts b/packages/core/src/api/errors.ts
index ec1569fb6..1ec1c783b 100644
--- a/packages/core/src/api/errors.ts
+++ b/packages/core/src/api/errors.ts
@@ -201,6 +201,7 @@ export const ErrorCode = {
 	AGGREGATOR_NOT_FOUND: "AGGREGATOR_NOT_FOUND",
 	CAPABILITY_ESCALATION: "CAPABILITY_ESCALATION",
 	ROUTE_VISIBILITY_ESCALATION: "ROUTE_VISIBILITY_ESCALATION",
+	ENV_INCOMPATIBLE: "ENV_INCOMPATIBLE",
 	INSTALL_FAILED: "INSTALL_FAILED",
 	UNINSTALL_FAILED: "UNINSTALL_FAILED",
 	SEARCH_FAILED: "SEARCH_FAILED",
@@ -414,6 +415,7 @@ export function mapErrorStatus(code: string | undefined): number {
 		case ErrorCode.ALREADY_INSTALLED:
 		case ErrorCode.ALREADY_CONFIGURED:
 		case ErrorCode.ALREADY_UP_TO_DATE:
+		case ErrorCode.ENV_INCOMPATIBLE:
 			return 409;
 
 		// 410 Gone
diff --git a/packages/core/src/api/handlers/index.ts b/packages/core/src/api/handlers/index.ts
index 3f92e6dff..77d9aec62 100644
--- a/packages/core/src/api/handlers/index.ts
+++ b/packages/core/src/api/handlers/index.ts
@@ -171,6 +171,8 @@ export {
 
 // Registry handlers (experimental)
 export {
+	assertEnvCompatible,
+	buildHostEnv,
 	handleRegistryInstall,
 	handleRegistryUninstall,
 	handleRegistryUpdate,
diff --git a/packages/core/src/api/handlers/registry.ts b/packages/core/src/api/handlers/registry.ts
index 8c556fdb1..78f528dd2 100644
--- a/packages/core/src/api/handlers/registry.ts
+++ b/packages/core/src/api/handlers/registry.ts
@@ -40,6 +40,8 @@
 
 import { ClientResponseError, ClientValidationError } from "@atcute/client";
 import type { Did } from "@atcute/lexicons";
+import { checkEnvCompatibility } from "@emdash-cms/registry-client/env";
+import type { HostEnv } from "@emdash-cms/registry-client/env";
 import type { Kysely } from "kysely";
 
 import type { Database } from "../../database/types.js";
@@ -520,6 +522,58 @@ async function fetchArtifact(mirrors: string[], declaredUrl: string): Promise<Ui
 	);
 }
 
+/**
+ * Build the host-environment map the install/update gate compares a release's
+ * `requires` against. Keys mirror the lexicon's `env:*` convention. An
+ * environment whose version is unknown (e.g. an uncompiled build reporting
+ * `"dev"`, or Astro unresolved) is omitted so the gate skips it rather than
+ * blocking on a version it can't evaluate.
+ */
+export function buildHostEnv(emdashVersion: string, astroVersion: string | undefined): HostEnv {
+	const host: HostEnv = {};
+	if (emdashVersion && emdashVersion !== "dev") host["env:emdash"] = emdashVersion;
+	if (astroVersion) host["env:astro"] = astroVersion;
+	return host;
+}
+
+/**
+ * The shape of a single env-compatibility failure returned to the admin in
+ * the `ENV_INCOMPATIBLE` error's `details`.
+ */
+interface EnvIncompatibleError {
+	code: "ENV_INCOMPATIBLE";
+	message: string;
+	details: { requires: Record<string, string>; host: HostEnv };
+}
+
+/**
+ * Gate a release's `requires` constraints against the running host
+ * environment. `requires` is the lexicon-`unknown` value off the signed
+ * release record — never trust its shape; `checkEnvCompatibility` guards it.
+ *
+ * Returns `null` when every advertised constraint is satisfied (or there are
+ * none), or a structured `ENV_INCOMPATIBLE` error naming the unsatisfied
+ * constraints and the host versions. The error carries the guarded `requires`
+ * and `host` maps so the admin can render the same mismatch the UI gate shows.
+ */
+export function assertEnvCompatible(
+	requires: unknown,
+	hostEnv: HostEnv,
+): EnvIncompatibleError | null {
+	const mismatches = checkEnvCompatibility(requires, hostEnv);
+	if (mismatches.length === 0) return null;
+	const guarded: Record<string, string> = {};
+	for (const m of mismatches) guarded[m.key] = m.required;
+	const summary = mismatches
+		.map((m) => `${m.key} requires ${m.required} but host is ${m.host}`)
+		.join("; ");
+	return {
+		code: "ENV_INCOMPATIBLE",
+		message: `This release is not compatible with the current environment: ${summary}.`,
+		details: { requires: guarded, host: hostEnv },
+	};
+}
+
 // ── Install ────────────────────────────────────────────────────────
 
 export async function handleRegistryInstall(
@@ -528,7 +582,7 @@ export async function handleRegistryInstall(
 	sandboxRunner: SandboxRunner | null,
 	registryConfigInput: RegistryConfigInput | undefined,
 	input: RegistryInstallInput,
-	opts?: { configuredPluginIds?: Set<string> },
+	opts?: { configuredPluginIds?: Set<string>; hostEnv?: HostEnv },
 ): Promise<ApiResult<RegistryInstallResult>> {
 	// Accept either the bare-string shorthand or the full
 	// `RegistryConfig` object (see `RegistryConfigInput`).
@@ -737,6 +791,17 @@ export async function handleRegistryInstall(
 			};
 		}
 
+		// Step 3b: environment compatibility. The signed release record may
+		// carry a `requires` block (`env:emdash`, `env:astro`, ...). Refuse
+		// the install if the running host doesn't satisfy a constraint, so a
+		// stale browser tab or non-UI caller can't bypass the admin's
+		// disabled Install button. `requires` is lexicon-`unknown`; the
+		// helper guards its shape.
+		if (opts?.hostEnv) {
+			const envError = assertEnvCompatible(releaseView.release?.requires, opts.hostEnv);
+			if (envError) return { success: false, error: envError };
+		}
+
 		// Step 3a: enforce the configured minimum release age. The browser
 		// applies the same check up front for UX, but the gate lives here
 		// -- a stale browser tab, a deep link, or a non-admin-UI caller
@@ -1212,6 +1277,7 @@ export async function handleRegistryUpdate(
 		version?: string;
 		confirmCapabilityChanges?: boolean;
 		confirmRouteVisibilityChanges?: boolean;
+		hostEnv?: HostEnv;
 	},
 ): Promise<ApiResult<RegistryUpdateResult>> {
 	const registryConfig = coerceRegistryConfig(registryConfigInput);
@@ -1363,6 +1429,14 @@ export async function handleRegistryUpdate(
 			};
 		}
 
+		// Environment compatibility gate. An ungated update could otherwise
+		// land a version whose `requires` the host doesn't satisfy. Same
+		// guard as install; `requires` is lexicon-`unknown`.
+		if (opts?.hostEnv) {
+			const envError = assertEnvCompatible(signedRelease.requires, opts.hostEnv);
+			if (envError) return { success: false, error: envError };
+		}
+
 		const declaredUrl = signedRelease.artifacts?.package?.url;
 		const declaredChecksum = signedRelease.artifacts?.package?.checksum;
 		if (!declaredUrl || !declaredChecksum) {
diff --git a/packages/core/src/astro/integration/index.ts b/packages/core/src/astro/integration/index.ts
index be342fd2c..c1aee2607 100644
--- a/packages/core/src/astro/integration/index.ts
+++ b/packages/core/src/astro/integration/index.ts
@@ -10,6 +10,8 @@
  * to avoid bundling Node.js-only code into the production build.
  */
 
+import { createRequire } from "node:module";
+
 import type { AstroIntegration, AstroIntegrationLogger } from "astro";
 
 import { validateAllowedOrigins, validateOriginShape } from "../../auth/allowed-origins.js";
@@ -34,6 +36,23 @@ export type {
 } from "./runtime.js";
 export { getStoredConfig } from "./runtime.js";
 
+/**
+ * Resolve the version of Astro the host project is building with, by reading
+ * `astro/package.json` from the project's own dependency tree. Surfaced to the
+ * admin and the registry install gate so a plugin's `env:astro` constraint can
+ * be evaluated against the real host version. Returns `undefined` if Astro
+ * can't be resolved (shouldn't happen in a real build, but never throw here).
+ */
+function resolveAstroVersion(): string | undefined {
+	try {
+		const require = createRequire(import.meta.url);
+		const pkg = require("astro/package.json") as { version?: unknown };
+		return typeof pkg.version === "string" ? pkg.version : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
 /** Default storage: Local filesystem in .emdash directory */
 const DEFAULT_STORAGE = local({
 	directory: "./.emdash/uploads",
@@ -204,6 +223,13 @@ export function emdash(config: EmDashConfig = {}): AstroIntegration {
 				command,
 			}) => {
 				printBanner(logger);
+				// Capture the host's Astro version so the runtime can expose it
+				// to the admin and the registry install gate for `env:astro`
+				// constraint checks.
+				const astroVersion = resolveAstroVersion();
+				if (astroVersion !== undefined) {
+					serializableConfig.astroVersion = astroVersion;
+				}
 				// Extract i18n config from Astro config
 				// Astro locales can be strings OR { path, codes } objects — normalize to paths
 				if (astroConfig.i18n) {
diff --git a/packages/core/src/astro/integration/runtime.ts b/packages/core/src/astro/integration/runtime.ts
index 3fe2b44d7..61d504a9c 100644
--- a/packages/core/src/astro/integration/runtime.ts
+++ b/packages/core/src/astro/integration/runtime.ts
@@ -527,6 +527,14 @@ export interface EmDashConfig {
 		/** URL or path to a custom favicon for the admin panel. */
 		favicon?: string;
 	};
+
+	/**
+	 * Version of Astro the host project is building with. Populated by the
+	 * integration's `astro:config:setup` hook (not authored by the user) and
+	 * surfaced to the admin and the registry install gate so a plugin's
+	 * `env:astro` requirement can be evaluated against the real host version.
+	 */
+	astroVersion?: string;
 }
 
 const STORED_CONFIG_KEY = Symbol.for("emdash:stored-config");
diff --git a/packages/core/src/astro/routes/api/admin/plugins/registry/[id]/update.ts b/packages/core/src/astro/routes/api/admin/plugins/registry/[id]/update.ts
index dc711a919..b3c086c5e 100644
--- a/packages/core/src/astro/routes/api/admin/plugins/registry/[id]/update.ts
+++ b/packages/core/src/astro/routes/api/admin/plugins/registry/[id]/update.ts
@@ -14,9 +14,11 @@ import { z } from "zod";
 
 import { requirePerm } from "#api/authorize.js";
 import { apiError, handleError, unwrapResult } from "#api/error.js";
-import { handleRegistryUpdate } from "#api/index.js";
+import { buildHostEnv, handleRegistryUpdate } from "#api/index.js";
 import { isParseError, parseOptionalBody } from "#api/parse.js";
 
+import { VERSION } from "../../../../../../../version.js";
+
 export const prerender = false;
 
 const updateBodySchema = z.object({
@@ -64,6 +66,7 @@ export const POST: APIRoute = async ({ params, request, locals }) => {
 				version: body.version,
 				confirmCapabilityChanges: body.confirmCapabilityChanges,
 				confirmRouteVisibilityChanges: body.confirmRouteVisibilityChanges,
+				hostEnv: buildHostEnv(VERSION, emdash.config.astroVersion),
 			},
 		);
 
diff --git a/packages/core/src/astro/routes/api/admin/plugins/registry/install.ts b/packages/core/src/astro/routes/api/admin/plugins/registry/install.ts
index 25aa9d08e..3ed8620a8 100644
--- a/packages/core/src/astro/routes/api/admin/plugins/registry/install.ts
+++ b/packages/core/src/astro/routes/api/admin/plugins/registry/install.ts
@@ -17,9 +17,11 @@ import { z } from "zod";
 
 import { requirePerm } from "#api/authorize.js";
 import { apiError, handleError, unwrapResult } from "#api/error.js";
-import { handleRegistryInstall } from "#api/index.js";
+import { buildHostEnv, handleRegistryInstall } from "#api/index.js";
 import { isParseError, parseBody } from "#api/parse.js";
 
+import { VERSION } from "../../../../../../version.js";
+
 export const prerender = false;
 
 const installBodySchema = z.object({
@@ -91,7 +93,10 @@ export const POST: APIRoute = async ({ request, locals }) => {
 				version: body.version,
 				acknowledgedDeclaredAccess: body.acknowledgedDeclaredAccess,
 			},
-			{ configuredPluginIds: reservedPluginIds },
+			{
+				configuredPluginIds: reservedPluginIds,
+				hostEnv: buildHostEnv(VERSION, emdash.config.astroVersion),
+			},
 		);
 
 		if (!result.success) return unwrapResult(result);
diff --git a/packages/core/src/astro/types.ts b/packages/core/src/astro/types.ts
index 0ac391ddc..3a2f51a8d 100644
--- a/packages/core/src/astro/types.ts
+++ b/packages/core/src/astro/types.ts
@@ -108,6 +108,12 @@ export interface EmDashManifest {
 	version: string;
 	commit?: string;
 	hash: string;
+	/**
+	 * Version of Astro the host project is built with. Present when the
+	 * integration could resolve it. Surfaced so the admin can evaluate a
+	 * registry plugin's `env:astro` requirement against the running host.
+	 */
+	astroVersion?: string;
 	collections: Record<string, ManifestCollection>;
 	plugins: Record<string, ManifestPlugin>;
 	/**
diff --git a/packages/core/src/emdash-runtime.ts b/packages/core/src/emdash-runtime.ts
index 388e474ba..e88c57532 100644
--- a/packages/core/src/emdash-runtime.ts
+++ b/packages/core/src/emdash-runtime.ts
@@ -2048,6 +2048,7 @@ export class EmDashRuntime {
 		return {
 			version: VERSION,
 			commit: COMMIT,
+			astroVersion: this.config.astroVersion,
 			hash: manifestHash,
 			collections: manifestCollections,
 			plugins: manifestPlugins,
diff --git a/packages/core/tests/unit/api/registry-env-compat.test.ts b/packages/core/tests/unit/api/registry-env-compat.test.ts
new file mode 100644
index 000000000..a0522aa11
--- /dev/null
+++ b/packages/core/tests/unit/api/registry-env-compat.test.ts
@@ -0,0 +1,78 @@
+/**
+ * Environment-compatibility gate for registry install/update.
+ *
+ * `handleRegistryInstall` and `handleRegistryUpdate` both call
+ * `assertEnvCompatible` after release selection / yank-check and before the
+ * artifact fetch. The full handler path needs a mocked DiscoveryClient (tracked
+ * separately); these tests exercise the gate's decision logic directly — the
+ * same helper both handlers use — plus the host-env builder and the error-code
+ * status mapping that surfaces `ENV_INCOMPATIBLE` to the admin.
+ */
+
+import { describe, expect, it } from "vitest";
+
+import { mapErrorStatus } from "../../../src/api/errors.js";
+import { assertEnvCompatible, buildHostEnv } from "../../../src/api/handlers/registry.js";
+
+describe("buildHostEnv", () => {
+	it("maps emdash + astro versions to env:* keys", () => {
+		expect(buildHostEnv("1.2.0", "4.16.0")).toEqual({
+			"env:emdash": "1.2.0",
+			"env:astro": "4.16.0",
+		});
+	});
+
+	it("omits a dev emdash build so the gate skips it", () => {
+		expect(buildHostEnv("dev", "4.16.0")).toEqual({ "env:astro": "4.16.0" });
+	});
+
+	it("omits astro when its version is unknown", () => {
+		expect(buildHostEnv("1.2.0", undefined)).toEqual({ "env:emdash": "1.2.0" });
+	});
+});
+
+describe("assertEnvCompatible", () => {
+	const host = { "env:emdash": "1.2.0", "env:astro": "4.12.0" };
+
+	it("returns null when every constraint is satisfied", () => {
+		expect(
+			assertEnvCompatible({ "env:emdash": ">=1.0.0", "env:astro": ">=4.0.0" }, host),
+		).toBeNull();
+	});
+
+	it("returns null when there are no constraints", () => {
+		expect(assertEnvCompatible(undefined, host)).toBeNull();
+		expect(assertEnvCompatible({}, host)).toBeNull();
+	});
+
+	it("returns an ENV_INCOMPATIBLE error when a constraint is not satisfied", () => {
+		const error = assertEnvCompatible({ "env:astro": ">=4.16" }, host);
+		expect(error?.code).toBe("ENV_INCOMPATIBLE");
+		expect(error?.details.requires).toEqual({ "env:astro": ">=4.16" });
+		expect(error?.details.host).toEqual(host);
+		expect(error?.message).toContain("env:astro");
+	});
+
+	it("reports every unsatisfied constraint, skipping satisfied ones", () => {
+		const error = assertEnvCompatible({ "env:emdash": ">=2.0.0", "env:astro": ">=4.0.0" }, host);
+		expect(error?.details.requires).toEqual({ "env:emdash": ">=2.0.0" });
+	});
+
+	it("does not crash on a garbage requires shape", () => {
+		expect(assertEnvCompatible("garbage", host)).toBeNull();
+		expect(assertEnvCompatible(42, host)).toBeNull();
+		expect(assertEnvCompatible({ "env:astro": 999 }, host)).toBeNull();
+		expect(assertEnvCompatible(null, host)).toBeNull();
+	});
+
+	it("skips constraints for envs the host does not advertise", () => {
+		expect(assertEnvCompatible({ "did:plc:abc": "^1.0.0" }, host)).toBeNull();
+		expect(assertEnvCompatible({ "env:astro": ">=4.16" }, { "env:emdash": "1.2.0" })).toBeNull();
+	});
+});
+
+describe("ENV_INCOMPATIBLE status mapping", () => {
+	it("maps to 409 Conflict", () => {
+		expect(mapErrorStatus("ENV_INCOMPATIBLE")).toBe(409);
+	});
+});
diff --git a/packages/plugin-cli/schemas/emdash-plugin.schema.json b/packages/plugin-cli/schemas/emdash-plugin.schema.json
index 690e5a0d0..5b32d78c4 100644
--- a/packages/plugin-cli/schemas/emdash-plugin.schema.json
+++ b/packages/plugin-cli/schemas/emdash-plugin.schema.json
@@ -55,6 +55,9 @@
 		},
 		"repo": {
 			"$ref": "#/$defs/__schema42"
+		},
+		"requires": {
+			"$ref": "#/$defs/__schema43"
 		}
 	},
 	"required": [
@@ -465,6 +468,30 @@
 			"examples": [
 				"https://github.com/emdash-cms/plugin-gallery"
 			]
+		},
+		"__schema43": {
+			"type": "object",
+			"propertyNames": {
+				"$ref": "#/$defs/__schema44"
+			},
+			"additionalProperties": {
+				"$ref": "#/$defs/__schema45"
+			},
+			"title": "Environment requirements",
+			"description": "Host environment constraints for this release, keyed by `env:*` (e.g. \"env:astro\", \"env:emdash\") with semver-range values. EmDash refuses to install a release whose constraints the host does not satisfy.",
+			"examples": [
+				{
+					"env:emdash": ">=1.0.0",
+					"env:astro": ">=4.16"
+				}
+			]
+		},
+		"__schema44": {
+			"type": "string"
+		},
+		"__schema45": {
+			"type": "string",
+			"minLength": 1
 		}
 	}
 }
diff --git a/packages/plugin-cli/src/commands/publish.ts b/packages/plugin-cli/src/commands/publish.ts
index 6ff3a5b83..074453e51 100644
--- a/packages/plugin-cli/src/commands/publish.ts
+++ b/packages/plugin-cli/src/commands/publish.ts
@@ -311,6 +311,7 @@ async function runPublish(args: PublishArgs): Promise<void> {
 		url: args.url,
 		profileInput,
 		repo: manifestLoad?.manifest.repo,
+		requires: manifestLoad?.manifest.requires,
 		allowOverwrite: args["allow-overwrite"],
 		logger,
 	});
diff --git a/packages/plugin-cli/src/manifest/schema.ts b/packages/plugin-cli/src/manifest/schema.ts
index ca4b087db..af321a7f8 100644
--- a/packages/plugin-cli/src/manifest/schema.ts
+++ b/packages/plugin-cli/src/manifest/schema.ts
@@ -60,6 +60,7 @@ import {
 	PLUGIN_VERSION_MAX_LENGTH,
 	PLUGIN_VERSION_RE,
 } from "@emdash-cms/plugin-types";
+import { isValidVersionRange } from "@emdash-cms/registry-client/env";
 import { z } from "zod";
 
 // ──────────────────────────────────────────────────────────────────────────
@@ -245,6 +246,42 @@ export const RepoSchema = z
 		examples: ["https://github.com/emdash-cms/plugin-gallery"],
 	});
 
+/** `env:<name>` requirement keys (one or more non-colon characters). */
+const REQUIRES_ENV_KEY_RE = /^env:[^:]+$/;
+
+/**
+ * Release-level environment constraints. Mirrors `release.json#requires`: a
+ * map of `env:*` keys (host environment requirements) or package DIDs to
+ * semver-range constraint strings. EmDash uses `env:emdash` and `env:astro`.
+ *
+ * Keys are validated structurally (`env:<name>` or `did:<method>:<id>`) and
+ * values against the shared range grammar in `@emdash-cms/registry-client/env`,
+ * the same evaluator the install gate and the admin compatibility warning use,
+ * so a publisher can't ship a constraint that no consumer can evaluate.
+ */
+export const RequiresSchema = z
+	.record(
+		z
+			.string()
+			.refine(
+				(k) => REQUIRES_ENV_KEY_RE.test(k) || isDid(k),
+				'requires key must be an `env:*` requirement (e.g. "env:astro") or a package DID',
+			),
+		z
+			.string()
+			.min(1, "requires range must be a non-empty semver range")
+			.refine(
+				isValidVersionRange,
+				'requires range must be a valid semver range (e.g. ">=4.16", "^4.0.0", ">=4.16.0 <5.0.0")',
+			),
+	)
+	.meta({
+		title: "Environment requirements",
+		description:
+			'Host environment constraints for this release, keyed by `env:*` (e.g. "env:astro", "env:emdash") with semver-range values. EmDash refuses to install a release whose constraints the host does not satisfy.',
+		examples: [{ "env:emdash": ">=1.0.0", "env:astro": ">=4.16" }],
+	});
+
 // ──────────────────────────────────────────────────────────────────────────
 // Identity (slug + version)
 // ──────────────────────────────────────────────────────────────────────────
@@ -631,6 +668,7 @@ export const ManifestSchema = z
 
 		// Optional release fields.
 		repo: RepoSchema.optional(),
+		requires: RequiresSchema.optional(),
 	})
 	.strict()
 	.refine((v) => !(v.author !== undefined && v.authors !== undefined), {
diff --git a/packages/plugin-cli/src/manifest/translate.ts b/packages/plugin-cli/src/manifest/translate.ts
index 1c8e15ed9..dca1ad368 100644
--- a/packages/plugin-cli/src/manifest/translate.ts
+++ b/packages/plugin-cli/src/manifest/translate.ts
@@ -45,6 +45,13 @@ export interface NormalisedManifest {
 	keywords: string[] | undefined;
 	repo: string | undefined;
 
+	/**
+	 * Release-level environment constraints (`release.requires`). Map of
+	 * `env:*`/DID keys to semver ranges. Release-level, not profile-level —
+	 * passed to `publishRelease` separately, never via `manifestToProfileInput`.
+	 */
+	requires: Record<string, string> | undefined;
+
 	// Trust contract (defaults applied by the schema; always present here).
 	capabilities: PluginCapability[];
 	allowedHosts: string[];
@@ -166,6 +173,7 @@ export function normaliseManifest(manifest: Manifest, packageVersion?: string):
 		description: manifest.description,
 		keywords: manifest.keywords,
 		repo: manifest.repo,
+		requires: manifest.requires,
 		// Schema validation already gates capability strings to the
 		// current vocabulary via a runtime check, so by the time we get
 		// here the strings are guaranteed members of PluginCapability.
diff --git a/packages/plugin-cli/src/publish/api.ts b/packages/plugin-cli/src/publish/api.ts
index 84b47a057..e33900ac1 100644
--- a/packages/plugin-cli/src/publish/api.ts
+++ b/packages/plugin-cli/src/publish/api.ts
@@ -162,6 +162,12 @@ export interface PublishOptions {
 	 * immutable per version, so this is not a first-publish-only field.
 	 */
 	repo?: string;
+	/**
+	 * Environment constraints for this release (`release.requires` in the
+	 * lexicon). Map of `env:*`/DID keys to semver ranges. Written to the
+	 * release record when non-empty; omitted otherwise.
+	 */
+	requires?: Record<string, string>;
 	/**
 	 * Allow overwriting an existing release at `<slug>:<version>`. Default
 	 * is `false`, which causes publish to refuse with `RELEASE_ALREADY_PUBLISHED`.
@@ -245,6 +251,8 @@ interface PackageReleaseRecordShape {
 	};
 	/** Source-repository URL (`release.repo`). Omitted when not provided. */
 	repo?: string;
+	/** Environment constraints (`release.requires`). Omitted when empty. */
+	requires?: Record<string, string>;
 	/**
 	 * Open-union extension container, keyed by NSID. Releases of type
 	 * `emdash-plugin` MUST include a `releaseExtension` entry carrying the
@@ -400,6 +408,9 @@ export async function publishRelease(options: PublishOptions): Promise<PublishRe
 	if (options.repo !== undefined) {
 		releaseRecord.repo = options.repo;
 	}
+	if (options.requires !== undefined && Object.keys(options.requires).length > 0) {
+		releaseRecord.requires = options.requires;
+	}
 
 	type WriteOp =
 		| {
diff --git a/packages/plugin-cli/tests/manifest-schema.test.ts b/packages/plugin-cli/tests/manifest-schema.test.ts
index c90f035a1..6a7253eb4 100644
--- a/packages/plugin-cli/tests/manifest-schema.test.ts
+++ b/packages/plugin-cli/tests/manifest-schema.test.ts
@@ -19,6 +19,7 @@ import {
 	LicenseSchema,
 	ManifestSchema,
 	RepoSchema,
+	RequiresSchema,
 	SecurityContactSchema,
 } from "../src/manifest/schema.js";
 
@@ -121,6 +122,42 @@ describe("RepoSchema", () => {
 	});
 });
 
+describe("RequiresSchema", () => {
+	it("accepts env:* keys with semver-range values", () => {
+		expect(RequiresSchema.parse({ "env:emdash": ">=1.0.0", "env:astro": ">=4.16" })).toEqual({
+			"env:emdash": ">=1.0.0",
+			"env:astro": ">=4.16",
+		});
+	});
+
+	it("accepts caret, tilde, and AND-set ranges", () => {
+		expect(
+			RequiresSchema.parse({
+				"env:astro": "^4.0.0",
+				"env:emdash": ">=1.0.0 <2.0.0",
+			}),
+		).toBeTruthy();
+		expect(RequiresSchema.parse({ "env:astro": "~4.16.0" })).toBeTruthy();
+	});
+
+	it("accepts forward-compat DID-shaped keys", () => {
+		expect(RequiresSchema.parse({ "did:plc:abc123": "^1.0.0" })).toEqual({
+			"did:plc:abc123": "^1.0.0",
+		});
+	});
+
+	it("rejects keys that are neither env:* nor DID-shaped", () => {
+		expect(RequiresSchema.safeParse({ astro: ">=4.16" }).success).toBe(false);
+		expect(RequiresSchema.safeParse({ "env:": ">=4.16" }).success).toBe(false);
+	});
+
+	it("rejects values that aren't valid semver ranges", () => {
+		expect(RequiresSchema.safeParse({ "env:astro": "not-a-range" }).success).toBe(false);
+		expect(RequiresSchema.safeParse({ "env:astro": "" }).success).toBe(false);
+		expect(RequiresSchema.safeParse({ "env:astro": ">=" }).success).toBe(false);
+	});
+});
+
 describe("ManifestSchema (full document)", () => {
 	const minimal = {
 		slug: "my-plugin",
@@ -257,9 +294,26 @@ describe("ManifestSchema (full document)", () => {
 			description: "Image gallery block for EmDash.",
 			keywords: ["gallery", "images", "media"],
 			repo: "https://github.com/emdash-cms/plugin-gallery",
+			requires: { "env:emdash": ">=1.0.0", "env:astro": ">=4.16" },
 			capabilities: ["content:read"],
 			storage: { events: { indexes: ["timestamp"] } },
 		});
 		expect(result.success).toBe(true);
 	});
+
+	it("accepts a manifest with release-level requires", () => {
+		const result = ManifestSchema.safeParse({
+			...minimal,
+			requires: { "env:astro": ">=4.16" },
+		});
+		expect(result.success).toBe(true);
+	});
+
+	it("rejects a manifest with an invalid requires range", () => {
+		const result = ManifestSchema.safeParse({
+			...minimal,
+			requires: { "env:astro": "not-a-range" },
+		});
+		expect(result.success).toBe(false);
+	});
 });
diff --git a/packages/plugin-cli/tests/manifest-translate.test.ts b/packages/plugin-cli/tests/manifest-translate.test.ts
index 3aa80f289..31025d9d4 100644
--- a/packages/plugin-cli/tests/manifest-translate.test.ts
+++ b/packages/plugin-cli/tests/manifest-translate.test.ts
@@ -94,6 +94,27 @@ describe("normaliseManifest", () => {
 		).toThrow(/disagrees/);
 	});
 
+	it("passes release-level requires through unchanged", () => {
+		const normalised = normaliseManifest({
+			version: "0.1.0",
+			license: "MIT",
+			author: { name: "Jane" },
+			security: { email: "s@example.com" },
+			requires: { "env:emdash": ">=1.0.0", "env:astro": ">=4.16" },
+		});
+		expect(normalised.requires).toEqual({ "env:emdash": ">=1.0.0", "env:astro": ">=4.16" });
+	});
+
+	it("leaves requires undefined when the manifest omits it", () => {
+		const normalised = normaliseManifest({
+			version: "0.1.0",
+			license: "MIT",
+			author: { name: "Jane" },
+			security: { email: "s@example.com" },
+		});
+		expect(normalised.requires).toBeUndefined();
+	});
+
 	it("throws when no version is available anywhere", () => {
 		expect(() =>
 			normaliseManifest({
@@ -118,6 +139,7 @@ describe("manifestToProfileBootstrap", () => {
 			description: "desc",
 			keywords: ["k"],
 			repo: "https://github.com/example/p",
+			requires: undefined,
 			capabilities: [],
 			allowedHosts: [],
 			storage: {},
@@ -142,6 +164,7 @@ describe("manifestToProfileBootstrap", () => {
 			description: undefined,
 			keywords: undefined,
 			repo: undefined,
+			requires: undefined,
 			capabilities: [],
 			allowedHosts: [],
 			storage: {},
@@ -168,6 +191,7 @@ describe("manifestToProfileInput", () => {
 			description: "desc",
 			keywords: ["k1", "k2"],
 			repo: "https://github.com/example/p",
+			requires: { "env:astro": ">=4.16" },
 			capabilities: [],
 			allowedHosts: [],
 			storage: {},
@@ -186,6 +210,8 @@ describe("manifestToProfileInput", () => {
 		expect(input.name).toBe("Test");
 		expect(input.description).toBe("desc");
 		expect(input.keywords).toEqual(["k1", "k2"]);
+		// requires is release-level, never folded into the profile input.
+		expect("requires" in input).toBe(false);
 	});
 
 	it("omits name, description and keywords when the manifest doesn't set them", () => {
@@ -200,6 +226,7 @@ describe("manifestToProfileInput", () => {
 			description: undefined,
 			keywords: undefined,
 			repo: undefined,
+			requires: undefined,
 			capabilities: [],
 			allowedHosts: [],
 			storage: {},
diff --git a/packages/plugin-cli/tests/publish.test.ts b/packages/plugin-cli/tests/publish.test.ts
index 7451dd5df..1d2d00cf4 100644
--- a/packages/plugin-cli/tests/publish.test.ts
+++ b/packages/plugin-cli/tests/publish.test.ts
@@ -142,6 +142,28 @@ describe("publishRelease", () => {
 			expect(value.artifacts.package.contentType).toBe("application/gzip");
 		});
 
+		it("writes release-level requires into the release record when provided", async () => {
+			const pds = new MockPds({ did: TEST_DID });
+			await publishRelease(
+				buildOptions(pds, {
+					requires: { "env:emdash": ">=1.0.0", "env:astro": ">=4.16" },
+				}),
+			);
+
+			const release = pds.records.get(`at://${TEST_DID}/${NSID.packageRelease}/test-plugin:1.0.0`);
+			const value = release!.value as { requires?: Record<string, string> };
+			expect(value.requires).toEqual({ "env:emdash": ">=1.0.0", "env:astro": ">=4.16" });
+		});
+
+		it("omits requires from the release record when empty or absent", async () => {
+			const pds = new MockPds({ did: TEST_DID });
+			await publishRelease(buildOptions(pds, { requires: {} }));
+
+			const release = pds.records.get(`at://${TEST_DID}/${NSID.packageRelease}/test-plugin:1.0.0`);
+			const value = release!.value as Record<string, unknown>;
+			expect("requires" in value).toBe(false);
+		});
+
 		it("hard-fails when license is missing, with no records written", async () => {
 			const pds = new MockPds({ did: TEST_DID });
 			const opts = buildOptions(pds, {
diff --git a/packages/registry-client/package.json b/packages/registry-client/package.json
index a618bac31..998cb03c0 100644
--- a/packages/registry-client/package.json
+++ b/packages/registry-client/package.json
@@ -20,6 +20,10 @@
 		"./discovery": {
 			"types": "./dist/discovery/index.d.ts",
 			"default": "./dist/discovery/index.js"
+		},
+		"./env": {
+			"types": "./dist/env/index.d.ts",
+			"default": "./dist/env/index.js"
 		}
 	},
 	"files": [
diff --git a/packages/registry-client/src/env/index.ts b/packages/registry-client/src/env/index.ts
new file mode 100644
index 000000000..3a56c81dc
--- /dev/null
+++ b/packages/registry-client/src/env/index.ts
@@ -0,0 +1,334 @@
+/**
+ * Environment compatibility for release `requires` constraints.
+ *
+ * A release record's `requires` block is a map of `env:*` keys (host
+ * environment requirements like `env:emdash`, `env:astro`) or package DIDs to
+ * semver-range constraint strings. The lexicon types it as `unknown`; nothing
+ * upstream guarantees its shape, so {@link parseRequires} guards it before any
+ * consumer reads it.
+ *
+ * The range grammar supported here is the subset publishers actually write for
+ * environment constraints: a space-separated AND set of comparators
+ * (`>=4.16.0 <5.0.0`), caret (`^4.0.0`), tilde (`~4.16.0`), partial versions
+ * (`>=4.16`), and the wildcard (`*` / `x`). OR (`||`) is not supported and is
+ * reported as an invalid range.
+ *
+ * Pure, dependency-free, and isomorphic so the CLI (publish-time validation),
+ * the server (install/update gate), and the admin (browser compat warning)
+ * all share one implementation.
+ */
+
+export interface HostEnv {
+	/** Map of `env:*` key to the host's current version of that environment. */
+	[key: string]: string | undefined;
+}
+
+export interface EnvMismatch {
+	/** The `requires` key that was not satisfied (e.g. `env:astro`). */
+	key: string;
+	/** The required range string from the release record. */
+	required: string;
+	/** The host's version of that environment. */
+	host: string;
+}
+
+/** A parsed semver version. Prerelease is compared lexically per semver §11. */
+interface ParsedVersion {
+	major: number;
+	minor: number;
+	patch: number;
+	prerelease: string[];
+}
+
+/** `env:<name>` keys, where `<name>` is one or more non-colon characters. */
+const ENV_KEY_RE = /^env:[^:]+$/;
+/** Structural DID shape: `did:<method>:<id>` (forward-compat for package deps). */
+const DID_KEY_RE = /^did:[a-z]+:.+$/;
+
+/** A full or partial semver version, optionally prerelease-tagged. */
+const VERSION_RE =
+	/^(0|[1-9]\d*)(?:\.(0|[1-9]\d*|x|\*)(?:\.(0|[1-9]\d*|x|\*))?)?(?:-([0-9A-Za-z.-]+))?$/;
+
+/** A complete `MAJOR.MINOR.PATCH` version, optionally prerelease-tagged. */
+const FULL_VERSION_RE = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z.-]+))?$/;
+
+/** Whitespace separator between comparators in an AND-joined range. */
+const WHITESPACE_RE = /\s+/;
+
+/** A purely numeric prerelease identifier (compared numerically per semver §11). */
+const NUMERIC_IDENTIFIER_RE = /^\d+$/;
+
+type Operator = ">=" | ">" | "<=" | "<" | "=";
+
+interface Comparator {
+	op: Operator;
+	version: ParsedVersion;
+}
+
+/**
+ * Guard the lexicon-`unknown` `requires` value into a string-valued record of
+ * recognised keys. Drops any entry whose key is not `env:*`/DID-shaped or whose
+ * value is not a string. Never throws.
+ */
+export function parseRequires(value: unknown): Record<string, string> {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) return {};
+	const out: Record<string, string> = {};
+	for (const [key, raw] of Object.entries(value)) {
+		if (typeof raw !== "string") continue;
+		if (!ENV_KEY_RE.test(key) && !DID_KEY_RE.test(key)) continue;
+		out[key] = raw;
+	}
+	return out;
+}
+
+/** True when `range` is a syntactically valid version range we can evaluate. */
+export function isValidVersionRange(range: string): boolean {
+	return parseRange(range) !== null;
+}
+
+/**
+ * True when `version` satisfies `range`.
+ *
+ * Fails open (returns `true`) when either input is unparseable: an unparseable
+ * host version cannot be proven incompatible, and an unparseable range is
+ * garbage we decline to enforce. Both cases are non-blocking by design — the
+ * gate only refuses on a definite mismatch.
+ */
+export function satisfiesRange(version: string, range: string): boolean {
+	const v = parseVersion(version);
+	if (v === null) return true;
+	const comparators = parseRange(range);
+	if (comparators === null) return true;
+	return comparators.every((c) => satisfiesComparator(v, c));
+}
+
+/**
+ * Compare a release's `requires` against the host environment and return the
+ * env keys whose host version does not satisfy the required range.
+ *
+ * Entries the host doesn't advertise (no known version for that key) are
+ * skipped — we can't evaluate a constraint against an environment we don't
+ * know we're running in. The `requires` argument is the raw lexicon-`unknown`
+ * value; it is guarded internally.
+ */
+export function checkEnvCompatibility(requires: unknown, host: HostEnv): EnvMismatch[] {
+	const parsed = parseRequires(requires);
+	const mismatches: EnvMismatch[] = [];
+	for (const [key, range] of Object.entries(parsed)) {
+		const hostVersion = host[key];
+		if (hostVersion === undefined) continue;
+		if (!satisfiesRange(hostVersion, range)) {
+			mismatches.push({ key, required: range, host: hostVersion });
+		}
+	}
+	return mismatches;
+}
+
+function satisfiesComparator(v: ParsedVersion, c: Comparator): boolean {
+	const cmp = compareVersions(v, c.version);
+	switch (c.op) {
+		case ">=":
+			return cmp >= 0;
+		case ">":
+			return cmp > 0;
+		case "<=":
+			return cmp <= 0;
+		case "<":
+			return cmp < 0;
+		case "=":
+			return cmp === 0;
+	}
+}
+
+/**
+ * Parse a range into the AND set of comparators it expands to, or `null` when
+ * the range is syntactically invalid. The wildcard `*` parses to an empty set
+ * (matches everything).
+ */
+function parseRange(range: string): Comparator[] | null {
+	const trimmed = range.trim();
+	if (trimmed === "") return null;
+	if (trimmed === "*") return [];
+	if (trimmed.includes("||")) return null;
+
+	const tokens = trimmed.split(WHITESPACE_RE);
+	const comparators: Comparator[] = [];
+	for (const token of tokens) {
+		const expanded = parseComparatorToken(token);
+		if (expanded === null) return null;
+		comparators.push(...expanded);
+	}
+	return comparators;
+}
+
+function parseComparatorToken(token: string): Comparator[] | null {
+	if (token.startsWith("^")) return parseCaret(token.slice(1));
+	if (token.startsWith("~")) return parseTilde(token.slice(1));
+
+	let op: Operator = "=";
+	let rest = token;
+	if (token.startsWith(">=")) {
+		op = ">=";
+		rest = token.slice(2);
+	} else if (token.startsWith("<=")) {
+		op = "<=";
+		rest = token.slice(2);
+	} else if (token.startsWith(">")) {
+		op = ">";
+		rest = token.slice(1);
+	} else if (token.startsWith("<")) {
+		op = "<";
+		rest = token.slice(1);
+	} else if (token.startsWith("=")) {
+		op = "=";
+		rest = token.slice(1);
+	}
+
+	if (rest === "*" || rest === "x") {
+		// Bare wildcard with a comparator (e.g. `>=*`) is degenerate; treat the
+		// version-only wildcard as "any" and any comparator as unconstrained.
+		return [];
+	}
+
+	const partial = parsePartialVersion(rest);
+	if (partial === null) return null;
+
+	// An `=` against a partial version (`=4.16`, `4.x`) becomes a bounded range
+	// covering the missing segments rather than an exact match.
+	if (op === "=" && partial.wildcard) {
+		return wildcardToRange(partial);
+	}
+	return [{ op, version: partial.version }];
+}
+
+interface PartialVersion {
+	version: ParsedVersion;
+	/** True when the source omitted minor/patch or used `x`/`*` for them. */
+	wildcard: boolean;
+	/** Index of the first wildcarded/omitted segment (1 = minor, 2 = patch). */
+	wildcardAt: number;
+}
+
+function parsePartialVersion(raw: string): PartialVersion | null {
+	if (!VERSION_RE.test(raw)) return null;
+	const [main, prerelease] = raw.split("-", 2);
+	const segments = main!.split(".");
+	let wildcardAt = segments.length;
+	const nums: number[] = [];
+	for (let i = 0; i < 3; i++) {
+		const seg = segments[i];
+		if (seg === undefined || seg === "x" || seg === "*") {
+			if (wildcardAt === segments.length || i < wildcardAt) wildcardAt = Math.min(wildcardAt, i);
+			nums.push(0);
+		} else {
+			nums.push(Number(seg));
+		}
+	}
+	const wildcard = wildcardAt < 3;
+	return {
+		version: {
+			major: nums[0]!,
+			minor: nums[1]!,
+			patch: nums[2]!,
+			prerelease: prerelease ? prerelease.split(".") : [],
+		},
+		wildcard,
+		wildcardAt,
+	};
+}
+
+/** Expand a wildcarded `=` version (`4.x`, `4.16`) to a `>= lower < upper` pair. */
+function wildcardToRange(partial: PartialVersion): Comparator[] {
+	const { version, wildcardAt } = partial;
+	const lower: ParsedVersion = { ...version, prerelease: [] };
+	const upper: ParsedVersion =
+		wildcardAt <= 1
+			? { major: version.major + 1, minor: 0, patch: 0, prerelease: [] }
+			: { major: version.major, minor: version.minor + 1, patch: 0, prerelease: [] };
+	return [
+		{ op: ">=", version: lower },
+		{ op: "<", version: upper },
+	];
+}
+
+function parseCaret(raw: string): Comparator[] | null {
+	const partial = parsePartialVersion(raw);
+	if (partial === null) return null;
+	const { version } = partial;
+	const lower = version;
+	let upper: ParsedVersion;
+	if (version.major > 0) {
+		upper = { major: version.major + 1, minor: 0, patch: 0, prerelease: [] };
+	} else if (version.minor > 0) {
+		upper = { major: 0, minor: version.minor + 1, patch: 0, prerelease: [] };
+	} else {
+		upper = { major: 0, minor: 0, patch: version.patch + 1, prerelease: [] };
+	}
+	return [
+		{ op: ">=", version: lower },
+		{ op: "<", version: upper },
+	];
+}
+
+function parseTilde(raw: string): Comparator[] | null {
+	const partial = parsePartialVersion(raw);
+	if (partial === null) return null;
+	const { version, wildcardAt } = partial;
+	const lower = version;
+	// `~1` (major-only) allows the whole 1.x range; `~1.2` / `~1.2.3` allow
+	// patch-level changes within the stated minor.
+	const upper: ParsedVersion =
+		wildcardAt <= 1
+			? { major: version.major + 1, minor: 0, patch: 0, prerelease: [] }
+			: { major: version.major, minor: version.minor + 1, patch: 0, prerelease: [] };
+	return [
+		{ op: ">=", version: lower },
+		{ op: "<", version: upper },
+	];
+}
+
+function parseVersion(raw: string): ParsedVersion | null {
+	const trimmed = raw.trim();
+	const match = FULL_VERSION_RE.exec(trimmed);
+	if (!match) return null;
+	return {
+		major: Number(match[1]),
+		minor: Number(match[2]),
+		patch: Number(match[3]),
+		prerelease: match[4] ? match[4].split(".") : [],
+	};
+}
+
+function compareVersions(a: ParsedVersion, b: ParsedVersion): number {
+	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;
+	return comparePrerelease(a.prerelease, b.prerelease);
+}
+
+/** Semver §11: a version with a prerelease has lower precedence than one without. */
+function comparePrerelease(a: string[], b: string[]): number {
+	if (a.length === 0 && b.length === 0) return 0;
+	if (a.length === 0) return 1;
+	if (b.length === 0) return -1;
+	const len = Math.max(a.length, b.length);
+	for (let i = 0; i < len; i++) {
+		const ai = a[i];
+		const bi = b[i];
+		if (ai === undefined) return -1;
+		if (bi === undefined) return 1;
+		const an = NUMERIC_IDENTIFIER_RE.test(ai);
+		const bn = NUMERIC_IDENTIFIER_RE.test(bi);
+		if (an && bn) {
+			const diff = Number(ai) - Number(bi);
+			if (diff !== 0) return diff;
+		} else if (an) {
+			return -1;
+		} else if (bn) {
+			return 1;
+		} else if (ai !== bi) {
+			return ai < bi ? -1 : 1;
+		}
+	}
+	return 0;
+}
diff --git a/packages/registry-client/src/index.ts b/packages/registry-client/src/index.ts
index 365afe71d..59e667606 100644
--- a/packages/registry-client/src/index.ts
+++ b/packages/registry-client/src/index.ts
@@ -44,3 +44,12 @@ export {
 export { type PublishingClientFromHandlerOptions, PublishingClient } from "./publishing/index.js";
 
 export { type DiscoveryClientOptions, DiscoveryClient } from "./discovery/index.js";
+
+export {
+	type EnvMismatch,
+	type HostEnv,
+	checkEnvCompatibility,
+	isValidVersionRange,
+	parseRequires,
+	satisfiesRange,
+} from "./env/index.js";
diff --git a/packages/registry-client/tests/env.test.ts b/packages/registry-client/tests/env.test.ts
new file mode 100644
index 000000000..613e65f5b
--- /dev/null
+++ b/packages/registry-client/tests/env.test.ts
@@ -0,0 +1,160 @@
+import { describe, expect, it } from "vitest";
+
+import {
+	checkEnvCompatibility,
+	isValidVersionRange,
+	parseRequires,
+	satisfiesRange,
+} from "../src/env/index.js";
+
+describe("isValidVersionRange", () => {
+	it("accepts comparator ranges", () => {
+		expect(isValidVersionRange(">=4.16")).toBe(true);
+		expect(isValidVersionRange(">=4.16.0")).toBe(true);
+		expect(isValidVersionRange(">4.0.0")).toBe(true);
+		expect(isValidVersionRange("<=2.0.0")).toBe(true);
+		expect(isValidVersionRange("<2.0.0")).toBe(true);
+		expect(isValidVersionRange("=1.2.3")).toBe(true);
+		expect(isValidVersionRange("1.2.3")).toBe(true);
+	});
+
+	it("accepts caret and tilde ranges", () => {
+		expect(isValidVersionRange("^4.0.0")).toBe(true);
+		expect(isValidVersionRange("^4.16")).toBe(true);
+		expect(isValidVersionRange("~4.16.0")).toBe(true);
+		expect(isValidVersionRange("~4")).toBe(true);
+	});
+
+	it("accepts wildcard and any", () => {
+		expect(isValidVersionRange("*")).toBe(true);
+		expect(isValidVersionRange("4.x")).toBe(true);
+		expect(isValidVersionRange("4.16.x")).toBe(true);
+	});
+
+	it("accepts AND-joined comparator sets", () => {
+		expect(isValidVersionRange(">=4.16.0 <5.0.0")).toBe(true);
+	});
+
+	it("accepts prerelease versions in comparators", () => {
+		expect(isValidVersionRange(">=6.0.0-beta.0")).toBe(true);
+	});
+
+	it("rejects empty and garbage", () => {
+		expect(isValidVersionRange("")).toBe(false);
+		expect(isValidVersionRange("   ")).toBe(false);
+		expect(isValidVersionRange("not-a-range")).toBe(false);
+		expect(isValidVersionRange(">=")).toBe(false);
+		expect(isValidVersionRange("4.16.0.0")).toBe(false);
+		expect(isValidVersionRange(">>4.0.0")).toBe(false);
+	});
+});
+
+describe("satisfiesRange", () => {
+	it("evaluates comparator ranges", () => {
+		expect(satisfiesRange("4.16.0", ">=4.16")).toBe(true);
+		expect(satisfiesRange("4.16.1", ">=4.16.0")).toBe(true);
+		expect(satisfiesRange("4.12.0", ">=4.16")).toBe(false);
+		expect(satisfiesRange("4.16.0", ">4.16.0")).toBe(false);
+		expect(satisfiesRange("4.16.1", ">4.16.0")).toBe(true);
+	});
+
+	it("evaluates caret ranges", () => {
+		expect(satisfiesRange("4.16.0", "^4.0.0")).toBe(true);
+		expect(satisfiesRange("4.99.0", "^4.0.0")).toBe(true);
+		expect(satisfiesRange("5.0.0", "^4.0.0")).toBe(false);
+		expect(satisfiesRange("3.9.0", "^4.0.0")).toBe(false);
+	});
+
+	it("evaluates tilde ranges", () => {
+		expect(satisfiesRange("4.16.5", "~4.16.0")).toBe(true);
+		expect(satisfiesRange("4.17.0", "~4.16.0")).toBe(false);
+	});
+
+	it("evaluates AND-joined comparator sets", () => {
+		expect(satisfiesRange("4.16.0", ">=4.16.0 <5.0.0")).toBe(true);
+		expect(satisfiesRange("5.0.0", ">=4.16.0 <5.0.0")).toBe(false);
+	});
+
+	it("matches the wildcard against any version", () => {
+		expect(satisfiesRange("4.16.0", "*")).toBe(true);
+		expect(satisfiesRange("1.0.0-rc.1", "*")).toBe(true);
+	});
+
+	it("treats an unparseable host version as satisfied (cannot prove incompatible)", () => {
+		expect(satisfiesRange("dev", ">=4.16")).toBe(true);
+		expect(satisfiesRange("", ">=4.16")).toBe(true);
+	});
+
+	it("treats an unparseable range as satisfied (cannot enforce garbage)", () => {
+		expect(satisfiesRange("4.16.0", "not-a-range")).toBe(true);
+	});
+});
+
+describe("parseRequires", () => {
+	it("returns env:* and DID keys with string values", () => {
+		const parsed = parseRequires({
+			"env:emdash": ">=1.0.0",
+			"env:astro": ">=4.16",
+			"did:plc:abc123": "^1.0.0",
+		});
+		expect(parsed).toEqual({
+			"env:emdash": ">=1.0.0",
+			"env:astro": ">=4.16",
+			"did:plc:abc123": "^1.0.0",
+		});
+	});
+
+	it("drops non-string values", () => {
+		expect(parseRequires({ "env:astro": 4 })).toEqual({});
+		expect(parseRequires({ "env:astro": { foo: "bar" } })).toEqual({});
+	});
+
+	it("drops keys that are not env:* or DID-shaped", () => {
+		expect(parseRequires({ astro: ">=4.16", "env:": ">=1", foo: ">=1" })).toEqual({});
+	});
+
+	it("returns an empty object for non-object input", () => {
+		expect(parseRequires(undefined)).toEqual({});
+		expect(parseRequires(null)).toEqual({});
+		expect(parseRequires("garbage")).toEqual({});
+		expect(parseRequires(42)).toEqual({});
+		expect(parseRequires([])).toEqual({});
+	});
+});
+
+describe("checkEnvCompatibility", () => {
+	it("returns no mismatches when every constraint is satisfied", () => {
+		const result = checkEnvCompatibility(
+			{ "env:emdash": ">=1.0.0", "env:astro": ">=4.16" },
+			{ "env:emdash": "1.2.0", "env:astro": "4.16.0" },
+		);
+		expect(result).toEqual([]);
+	});
+
+	it("reports the env keys whose host version does not satisfy the range", () => {
+		const result = checkEnvCompatibility(
+			{ "env:emdash": ">=1.0.0", "env:astro": ">=4.16" },
+			{ "env:emdash": "1.2.0", "env:astro": "4.12.0" },
+		);
+		expect(result).toEqual([{ key: "env:astro", required: ">=4.16", host: "4.12.0" }]);
+	});
+
+	it("skips env keys the host does not advertise (no known version)", () => {
+		const result = checkEnvCompatibility(
+			{ "did:plc:abc": "^1.0.0" },
+			{ "env:emdash": "1.2.0", "env:astro": "4.16.0" },
+		);
+		expect(result).toEqual([]);
+	});
+
+	it("guards unknown requires shapes without crashing", () => {
+		expect(checkEnvCompatibility(undefined, { "env:emdash": "1.2.0" })).toEqual([]);
+		expect(checkEnvCompatibility("garbage", { "env:emdash": "1.2.0" })).toEqual([]);
+		expect(checkEnvCompatibility({ "env:astro": 999 }, { "env:astro": "4.16.0" })).toEqual([]);
+	});
+
+	it("skips host envs whose version is unknown/unparseable", () => {
+		const result = checkEnvCompatibility({ "env:emdash": ">=1.0.0" }, { "env:emdash": "dev" });
+		expect(result).toEqual([]);
+	});
+});
diff --git a/packages/registry-client/tsdown.config.ts b/packages/registry-client/tsdown.config.ts
index 6d7423e90..35689997a 100644
--- a/packages/registry-client/tsdown.config.ts
+++ b/packages/registry-client/tsdown.config.ts
@@ -5,6 +5,7 @@ export default defineConfig({
 		"src/index.ts",
 		"src/credentials/index.ts",
 		"src/discovery/index.ts",
+		"src/env/index.ts",
 		"src/publishing/index.ts",
 	],
 	format: ["esm"],

From 1ad04eb50aa73e77a3fbaba5968b6927fe50c390 Mon Sep 17 00:00:00 2001
From: Matt Kane <m@mk.gg>
Date: Sun, 31 May 2026 12:20:33 +0100
Subject: [PATCH 2/5] fix(registry): apply adversarial review findings for env
 requires

Share the version->env:* host map between server and admin via a single
hostEnvFromVersions helper, dropping the admin's redundant /manifest fetch
and the duplicated dev-skip rule (admin now derives host env from the
manifest query the shell already runs).

Log skipped env constraints server-side (findSkippedEnvConstraints) so a
host version the gate can't evaluate is observable rather than a silent
bypass. Cover the gate end-to-end through handleRegistryUpdate with a
mocked DiscoveryClient, asserting ENV_INCOMPATIBLE aborts before any
artifact fetch. Document the accepted, more-permissive prerelease range
semantics relative to node-semver.
---
 .../src/components/RegistryPluginDetail.tsx   |  19 ++-
 packages/admin/src/lib/api/registry.ts        |  30 ++--
 packages/core/src/api/handlers/registry.ts    |  26 ++--
 .../api/registry-env-gate-handler.test.ts     | 141 ++++++++++++++++++
 packages/registry-client/src/env/index.ts     |  70 +++++++++
 packages/registry-client/src/index.ts         |   3 +
 packages/registry-client/tests/env.test.ts    |  53 +++++++
 7 files changed, 311 insertions(+), 31 deletions(-)
 create mode 100644 packages/core/tests/unit/api/registry-env-gate-handler.test.ts

diff --git a/packages/admin/src/components/RegistryPluginDetail.tsx b/packages/admin/src/components/RegistryPluginDetail.tsx
index 41b75f2c1..ed2b31990 100644
--- a/packages/admin/src/components/RegistryPluginDetail.tsx
+++ b/packages/admin/src/components/RegistryPluginDetail.tsx
@@ -21,10 +21,11 @@ import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 import { Link } from "@tanstack/react-router";
 import * as React from "react";
 
+import { fetchManifest } from "../lib/api/client.js";
 import {
 	canonicalCapabilitiesForDriftCheck,
-	fetchHostEnv,
 	getRegistryPackage,
+	hostEnvFromManifest,
 	installRegistryPlugin,
 	listRegistryReleases,
 	releasePassesPolicy,
@@ -63,10 +64,13 @@ export function RegistryPluginDetail({ pluginId, config }: RegistryPluginDetailP
 
 	// Host environment versions (`env:emdash`, `env:astro`) — used to evaluate
 	// the selected release's `requires` constraints before offering install.
-	const { data: hostEnv } = useQuery({
-		queryKey: ["host-env"],
-		queryFn: fetchHostEnv,
+	// Derived from the admin manifest the shell already fetches under the same
+	// query key, so this view adds no extra round-trip.
+	const { data: manifest } = useQuery({
+		queryKey: ["manifest"],
+		queryFn: fetchManifest,
 	});
+	const hostEnv = React.useMemo(() => hostEnvFromManifest(manifest), [manifest]);
 
 	// Parse `<publisher>/<slug>` out of the route param. The publisher
 	// segment is either a handle (`example.dev`) or a DID
@@ -225,10 +229,11 @@ export function RegistryPluginDetail({ pluginId, config }: RegistryPluginDetailP
 	// constraints against the running host. `requires` is the lexicon's open
 	// `unknown` value; `checkEnvCompatibility` guards its shape. Mirrors the
 	// server-side install gate so the admin can't offer an install the server
-	// would reject. Empty while the host env is still loading (fail-open until
-	// the data arrives; the server gate is the authority either way).
+	// would reject. While the manifest is still loading `hostEnv` is empty, so
+	// every constraint is skipped (fail-open until the data arrives; the server
+	// gate is the authority either way).
 	const envMismatches = React.useMemo(() => {
-		if (!release || !hostEnv) return [];
+		if (!release) return [];
 		return checkEnvCompatibility(release.release?.requires, hostEnv);
 	}, [release, hostEnv]);
 	const envOk = envMismatches.length === 0;
diff --git a/packages/admin/src/lib/api/registry.ts b/packages/admin/src/lib/api/registry.ts
index 48d5ee2f2..122fcad15 100644
--- a/packages/admin/src/lib/api/registry.ts
+++ b/packages/admin/src/lib/api/registry.ts
@@ -26,11 +26,18 @@ import type {
 	ValidatedReleaseView,
 	ValidatedSearchPackages,
 } from "@emdash-cms/registry-client/discovery";
+import { hostEnvFromVersions } from "@emdash-cms/registry-client/env";
 import type { HostEnv } from "@emdash-cms/registry-client/env";
 import { i18n } from "@lingui/core";
 import { msg } from "@lingui/core/macro";
 
-import { API_BASE, apiFetch, parseApiResponse, throwResponseError } from "./client.js";
+import {
+	API_BASE,
+	apiFetch,
+	parseApiResponse,
+	throwResponseError,
+	type AdminManifest,
+} from "./client.js";
 
 export type { Did, Handle };
 export type { HostEnv };
@@ -297,22 +304,15 @@ export async function listRegistryReleases(
 }
 
 /**
- * Fetch the host environment versions (`env:emdash`, `env:astro`) the running
+ * Derive the host environment versions (`env:emdash`, `env:astro`) the running
  * EmDash install advertises, so a release's `requires` constraints can be
- * evaluated client-side before offering install. Reads the admin manifest,
- * which carries `version` (EmDash) and `astroVersion`. A `"dev"` EmDash build
- * and a missing Astro version are omitted so the compat check skips them.
+ * evaluated client-side before offering install. Reads the already-fetched
+ * admin manifest (`version`, `astroVersion`) rather than issuing a second
+ * request. The dev-skip / astro-omit rule is shared with the server gate via
+ * `hostEnvFromVersions`.
  */
-export async function fetchHostEnv(): Promise<HostEnv> {
-	const response = await apiFetch(`${API_BASE}/manifest`);
-	const manifest = await parseApiResponse<{ version?: string; astroVersion?: string }>(
-		response,
-		i18n._(msg`Failed to fetch host environment`),
-	);
-	const host: HostEnv = {};
-	if (manifest.version && manifest.version !== "dev") host["env:emdash"] = manifest.version;
-	if (manifest.astroVersion) host["env:astro"] = manifest.astroVersion;
-	return host;
+export function hostEnvFromManifest(manifest: AdminManifest | undefined): HostEnv {
+	return hostEnvFromVersions(manifest?.version, manifest?.astroVersion);
 }
 
 /**
diff --git a/packages/core/src/api/handlers/registry.ts b/packages/core/src/api/handlers/registry.ts
index 78f528dd2..482e66e1f 100644
--- a/packages/core/src/api/handlers/registry.ts
+++ b/packages/core/src/api/handlers/registry.ts
@@ -40,7 +40,11 @@
 
 import { ClientResponseError, ClientValidationError } from "@atcute/client";
 import type { Did } from "@atcute/lexicons";
-import { checkEnvCompatibility } from "@emdash-cms/registry-client/env";
+import {
+	checkEnvCompatibility,
+	findSkippedEnvConstraints,
+	hostEnvFromVersions,
+} from "@emdash-cms/registry-client/env";
 import type { HostEnv } from "@emdash-cms/registry-client/env";
 import type { Kysely } from "kysely";
 
@@ -524,16 +528,12 @@ async function fetchArtifact(mirrors: string[], declaredUrl: string): Promise<Ui
 
 /**
  * Build the host-environment map the install/update gate compares a release's
- * `requires` against. Keys mirror the lexicon's `env:*` convention. An
- * environment whose version is unknown (e.g. an uncompiled build reporting
- * `"dev"`, or Astro unresolved) is omitted so the gate skips it rather than
- * blocking on a version it can't evaluate.
+ * `requires` against. Delegates to the shared {@link hostEnvFromVersions} so the
+ * server gate and the admin's client-side warning apply the same dev-skip /
+ * astro-omit rule.
  */
 export function buildHostEnv(emdashVersion: string, astroVersion: string | undefined): HostEnv {
-	const host: HostEnv = {};
-	if (emdashVersion && emdashVersion !== "dev") host["env:emdash"] = emdashVersion;
-	if (astroVersion) host["env:astro"] = astroVersion;
-	return host;
+	return hostEnvFromVersions(emdashVersion, astroVersion);
 }
 
 /**
@@ -560,6 +560,14 @@ export function assertEnvCompatible(
 	requires: unknown,
 	hostEnv: HostEnv,
 ): EnvIncompatibleError | null {
+	// A constraint the host can't evaluate (unknown or unparseable host
+	// version) downgrades the gate to a no-op for that env. Log it so a
+	// silent bypass is observable rather than invisible.
+	for (const skipped of findSkippedEnvConstraints(requires, hostEnv)) {
+		console.warn(
+			`[registry] env compatibility constraint skipped: ${skipped.key} requires ${skipped.required} but host version is ${skipped.reason}`,
+		);
+	}
 	const mismatches = checkEnvCompatibility(requires, hostEnv);
 	if (mismatches.length === 0) return null;
 	const guarded: Record<string, string> = {};
diff --git a/packages/core/tests/unit/api/registry-env-gate-handler.test.ts b/packages/core/tests/unit/api/registry-env-gate-handler.test.ts
new file mode 100644
index 000000000..a1e663005
--- /dev/null
+++ b/packages/core/tests/unit/api/registry-env-gate-handler.test.ts
@@ -0,0 +1,141 @@
+/**
+ * Environment-compatibility gate wired through the real handler.
+ *
+ * `registry-env-compat.test.ts` exercises the gate's decision helper in
+ * isolation. This file drives `handleRegistryUpdate` end-to-end with a mocked
+ * `DiscoveryClient` so the wiring is covered: that `assertEnvCompatible` runs
+ * after release selection, that `opts.hostEnv` reaches it, and that an
+ * `ENV_INCOMPATIBLE` result aborts *before* any artifact fetch.
+ */
+
+import BetterSqlite3 from "better-sqlite3";
+import { Kysely, SqliteDialect } from "kysely";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { runMigrations } from "../../../src/database/migrations/runner.js";
+import type { Database as DbSchema } from "../../../src/database/types.js";
+import type { SandboxRunner } from "../../../src/plugins/sandbox/types.js";
+import { PluginStateRepository } from "../../../src/plugins/state.js";
+import type { Storage } from "../../../src/storage/types.js";
+
+/** A storage stub: present so the null-storage guard passes, never exercised. */
+const stubStorage = {
+	async download() {
+		throw new Error("not implemented");
+	},
+} as unknown as Storage;
+
+const getLatestRelease = vi.fn();
+const listReleases = vi.fn();
+const getPackage = vi.fn();
+
+vi.mock("@emdash-cms/registry-client/discovery", () => ({
+	DiscoveryClient: class {
+		getLatestRelease = getLatestRelease;
+		listReleases = listReleases;
+		getPackage = getPackage;
+	},
+}));
+
+const PUBLISHER = "did:plc:abc";
+const SLUG = "gallery";
+
+/**
+ * A release view shaped enough to pass the update handler's identity
+ * cross-check and reach the env gate, carrying a `requires` block.
+ */
+function releaseViewWithRequires(version: string, requires: Record<string, string>) {
+	return {
+		did: PUBLISHER,
+		package: SLUG,
+		version,
+		labels: [],
+		mirrors: [],
+		release: {
+			package: SLUG,
+			version,
+			requires,
+			// A real declared artifact URL: if the gate failed to abort, the
+			// handler would proceed to fetch this, tripping the `fetch` spy.
+			artifacts: {
+				package: {
+					url: "https://artifacts.test/gallery-2.0.0.tar.gz",
+					checksum: "sha256-deadbeef",
+				},
+			},
+		},
+	};
+}
+
+describe("handleRegistryUpdate env gate", () => {
+	let db: Kysely<DbSchema>;
+	let handleRegistryUpdate: typeof import("../../../src/api/handlers/registry.js").handleRegistryUpdate;
+	const stubSandbox = { isAvailable: () => true } as unknown as SandboxRunner;
+	const config = { aggregatorUrl: "https://aggregator.test" };
+	let fetchSpy: ReturnType<typeof vi.fn>;
+
+	beforeEach(async () => {
+		({ handleRegistryUpdate } = await import("../../../src/api/handlers/registry.js"));
+		const sqlite = new BetterSqlite3(":memory:");
+		db = new Kysely<DbSchema>({ dialect: new SqliteDialect({ database: sqlite }) });
+		await runMigrations(db);
+
+		const repo = new PluginStateRepository(db);
+		await repo.upsert("r_gallery000000000", "1.0.0", "active", {
+			source: "registry",
+			registryPublisherDid: PUBLISHER,
+			registrySlug: SLUG,
+		});
+
+		getLatestRelease.mockReset();
+		listReleases.mockReset();
+		getPackage.mockReset();
+		fetchSpy = vi.fn(() => {
+			throw new Error("artifact fetch must not run when the env gate rejects");
+		});
+		vi.stubGlobal("fetch", fetchSpy);
+	});
+
+	afterEach(async () => {
+		vi.unstubAllGlobals();
+		await db.destroy();
+	});
+
+	it("rejects with ENV_INCOMPATIBLE and fetches no artifact when the host fails `requires`", async () => {
+		getLatestRelease.mockResolvedValue(
+			releaseViewWithRequires("2.0.0", { "env:astro": ">=5.0.0" }),
+		);
+
+		const result = await handleRegistryUpdate(
+			db,
+			stubStorage,
+			stubSandbox,
+			config,
+			"r_gallery000000000",
+			{ hostEnv: { "env:emdash": "1.2.0", "env:astro": "4.16.0" } },
+		);
+
+		expect(result.success).toBe(false);
+		expect(result.error?.code).toBe("ENV_INCOMPATIBLE");
+		expect(fetchSpy).not.toHaveBeenCalled();
+	});
+
+	it("does not reject when the host satisfies `requires` (gate passes through)", async () => {
+		getLatestRelease.mockResolvedValue(
+			releaseViewWithRequires("2.0.0", { "env:astro": ">=4.0.0" }),
+		);
+
+		const result = await handleRegistryUpdate(
+			db,
+			stubStorage,
+			stubSandbox,
+			config,
+			"r_gallery000000000",
+			{ hostEnv: { "env:emdash": "1.2.0", "env:astro": "4.16.0" } },
+		);
+
+		// The gate passes; the update proceeds past it. With null storage the
+		// handler then fails downstream — but never with ENV_INCOMPATIBLE.
+		expect(result.error?.code).not.toBe("ENV_INCOMPATIBLE");
+	});
+});
diff --git a/packages/registry-client/src/env/index.ts b/packages/registry-client/src/env/index.ts
index 3a56c81dc..82be24ecf 100644
--- a/packages/registry-client/src/env/index.ts
+++ b/packages/registry-client/src/env/index.ts
@@ -13,6 +13,15 @@
  * (`>=4.16`), and the wildcard (`*` / `x`). OR (`||`) is not supported and is
  * reported as an invalid range.
  *
+ * Prerelease handling diverges from node-semver and is intentionally more
+ * permissive: a prerelease version satisfies any comparator whose ordering it
+ * meets, with no requirement that the comparator share its `[major,minor,patch]`
+ * tuple. So `5.0.0-alpha` satisfies `>=4.16.0 <5.0.0` here where node-semver
+ * would reject it. Hosts almost never run prerelease Astro/EmDash builds and the
+ * gate fails open on a definite-mismatch-only basis, so the looser semantics
+ * can only let an install through, never wrongly block one. Tightening this to
+ * node-semver's prerelease gating is a deliberate future change, not a bug.
+ *
  * Pure, dependency-free, and isomorphic so the CLI (publish-time validation),
  * the server (install/update gate), and the admin (browser compat warning)
  * all share one implementation.
@@ -65,6 +74,26 @@ interface Comparator {
 	version: ParsedVersion;
 }
 
+/**
+ * Build the host-environment map the install/update gate compares a release's
+ * `requires` against, from the EmDash and Astro versions the host advertises.
+ *
+ * An environment whose version is unknown is omitted so the gate skips it
+ * rather than blocking on a version it can't evaluate: an uncompiled build
+ * reporting `"dev"` for EmDash, or an unresolved Astro version. Shared by the
+ * server install/update gate and the admin's client-side compat warning so the
+ * dev-skip / astro-omit rule lives in exactly one place.
+ */
+export function hostEnvFromVersions(
+	emdashVersion: string | undefined,
+	astroVersion: string | undefined,
+): HostEnv {
+	const host: HostEnv = {};
+	if (emdashVersion && emdashVersion !== "dev") host["env:emdash"] = emdashVersion;
+	if (astroVersion) host["env:astro"] = astroVersion;
+	return host;
+}
+
 /**
  * Guard the lexicon-`unknown` `requires` value into a string-valued record of
  * recognised keys. Drops any entry whose key is not `env:*`/DID-shaped or whose
@@ -124,6 +153,47 @@ export function checkEnvCompatibility(requires: unknown, host: HostEnv): EnvMism
 	return mismatches;
 }
 
+/** An `env:*` constraint that could not be enforced against the host. */
+export interface SkippedEnvConstraint {
+	/** The `env:*` key whose constraint was skipped. */
+	key: string;
+	/** The required range string from the release record. */
+	required: string;
+	/**
+	 * `"unknown"`: the host advertises no version for this env.
+	 * `"unparseable"`: the host version exists but isn't valid semver.
+	 */
+	reason: "unknown" | "unparseable";
+}
+
+/**
+ * Find the `env:*` constraints in `requires` that {@link checkEnvCompatibility}
+ * silently skips because the host can't evaluate them: the host advertises no
+ * version for that env, or advertises one that isn't parseable semver. These
+ * are the cases where a hard gate degrades to a no-op, so the server can log
+ * them rather than bypass silently.
+ *
+ * DID-keyed constraints are excluded — those are forward-compat package deps,
+ * not host environments, and their absence from the host map is expected.
+ */
+export function findSkippedEnvConstraints(
+	requires: unknown,
+	host: HostEnv,
+): SkippedEnvConstraint[] {
+	const parsed = parseRequires(requires);
+	const skipped: SkippedEnvConstraint[] = [];
+	for (const [key, range] of Object.entries(parsed)) {
+		if (!ENV_KEY_RE.test(key)) continue;
+		const hostVersion = host[key];
+		if (hostVersion === undefined) {
+			skipped.push({ key, required: range, reason: "unknown" });
+		} else if (parseVersion(hostVersion) === null) {
+			skipped.push({ key, required: range, reason: "unparseable" });
+		}
+	}
+	return skipped;
+}
+
 function satisfiesComparator(v: ParsedVersion, c: Comparator): boolean {
 	const cmp = compareVersions(v, c.version);
 	switch (c.op) {
diff --git a/packages/registry-client/src/index.ts b/packages/registry-client/src/index.ts
index 59e667606..680adcc2d 100644
--- a/packages/registry-client/src/index.ts
+++ b/packages/registry-client/src/index.ts
@@ -48,7 +48,10 @@ export { type DiscoveryClientOptions, DiscoveryClient } from "./discovery/index.
 export {
 	type EnvMismatch,
 	type HostEnv,
+	type SkippedEnvConstraint,
 	checkEnvCompatibility,
+	findSkippedEnvConstraints,
+	hostEnvFromVersions,
 	isValidVersionRange,
 	parseRequires,
 	satisfiesRange,
diff --git a/packages/registry-client/tests/env.test.ts b/packages/registry-client/tests/env.test.ts
index 613e65f5b..3e0898384 100644
--- a/packages/registry-client/tests/env.test.ts
+++ b/packages/registry-client/tests/env.test.ts
@@ -2,6 +2,8 @@ import { describe, expect, it } from "vitest";
 
 import {
 	checkEnvCompatibility,
+	findSkippedEnvConstraints,
+	hostEnvFromVersions,
 	isValidVersionRange,
 	parseRequires,
 	satisfiesRange,
@@ -158,3 +160,54 @@ describe("checkEnvCompatibility", () => {
 		expect(result).toEqual([]);
 	});
 });
+
+describe("findSkippedEnvConstraints", () => {
+	it("returns nothing when every env constraint is evaluable", () => {
+		expect(
+			findSkippedEnvConstraints(
+				{ "env:emdash": ">=1.0.0", "env:astro": ">=4.0.0" },
+				{ "env:emdash": "1.2.0", "env:astro": "4.16.0" },
+			),
+		).toEqual([]);
+	});
+
+	it("flags an env the host does not advertise as unknown", () => {
+		expect(findSkippedEnvConstraints({ "env:astro": ">=4.16" }, { "env:emdash": "1.2.0" })).toEqual(
+			[{ key: "env:astro", required: ">=4.16", reason: "unknown" }],
+		);
+	});
+
+	it("flags an env whose host version is not parseable semver", () => {
+		expect(findSkippedEnvConstraints({ "env:emdash": ">=1.0.0" }, { "env:emdash": "dev" })).toEqual(
+			[{ key: "env:emdash", required: ">=1.0.0", reason: "unparseable" }],
+		);
+	});
+
+	it("ignores DID-keyed constraints (package deps, not host envs)", () => {
+		expect(findSkippedEnvConstraints({ "did:plc:abc": "^1.0.0" }, {})).toEqual([]);
+	});
+
+	it("does not crash on a garbage requires shape", () => {
+		expect(findSkippedEnvConstraints("garbage", {})).toEqual([]);
+		expect(findSkippedEnvConstraints(null, {})).toEqual([]);
+	});
+});
+
+describe("hostEnvFromVersions", () => {
+	it("maps emdash + astro versions to env:* keys", () => {
+		expect(hostEnvFromVersions("1.2.0", "4.16.0")).toEqual({
+			"env:emdash": "1.2.0",
+			"env:astro": "4.16.0",
+		});
+	});
+
+	it("omits a dev emdash build so the gate skips it", () => {
+		expect(hostEnvFromVersions("dev", "4.16.0")).toEqual({ "env:astro": "4.16.0" });
+	});
+
+	it("omits each env whose version is unknown", () => {
+		expect(hostEnvFromVersions("1.2.0", undefined)).toEqual({ "env:emdash": "1.2.0" });
+		expect(hostEnvFromVersions(undefined, "4.16.0")).toEqual({ "env:astro": "4.16.0" });
+		expect(hostEnvFromVersions(undefined, undefined)).toEqual({});
+	});
+});

From 0c066e1b8eef6713266db026ffcc71093be026b0 Mon Sep 17 00:00:00 2001
From: Matt Kane <m@mk.gg>
Date: Sun, 31 May 2026 12:38:24 +0100
Subject: [PATCH 3/5] refactor(registry): use node-semver for env requires
 range evaluation

Replace the hand-rolled range evaluator in registry-client's env module
with the semver package. Adds || union support and node-semver prerelease
gating; satisfiesRange passes includePrerelease so a prerelease host build
is evaluated by precedence rather than excluded from release-only ranges
(a prerelease host is not a definite mismatch). isValidVersionRange (shared
by the publish-time RequiresSchema) and the fail-open gate semantics are
unchanged.
---
 packages/registry-client/package.json      |   4 +-
 packages/registry-client/src/env/index.ts  | 288 ++-------------------
 packages/registry-client/tests/env.test.ts |  14 +
 pnpm-lock.yaml                             |  25 +-
 pnpm-workspace.yaml                        |   2 +
 5 files changed, 65 insertions(+), 268 deletions(-)

diff --git a/packages/registry-client/package.json b/packages/registry-client/package.json
index 998cb03c0..c7d98663d 100644
--- a/packages/registry-client/package.json
+++ b/packages/registry-client/package.json
@@ -41,11 +41,13 @@
 		"@atcute/atproto": "catalog:",
 		"@atcute/client": "catalog:",
 		"@atcute/lexicons": "catalog:",
-		"@emdash-cms/registry-lexicons": "workspace:*"
+		"@emdash-cms/registry-lexicons": "workspace:*",
+		"semver": "catalog:"
 	},
 	"devDependencies": {
 		"@arethetypeswrong/cli": "catalog:",
 		"@types/node": "catalog:",
+		"@types/semver": "catalog:",
 		"publint": "catalog:",
 		"tsdown": "catalog:",
 		"typescript": "catalog:",
diff --git a/packages/registry-client/src/env/index.ts b/packages/registry-client/src/env/index.ts
index 82be24ecf..10c978cdf 100644
--- a/packages/registry-client/src/env/index.ts
+++ b/packages/registry-client/src/env/index.ts
@@ -7,26 +7,16 @@
  * upstream guarantees its shape, so {@link parseRequires} guards it before any
  * consumer reads it.
  *
- * The range grammar supported here is the subset publishers actually write for
- * environment constraints: a space-separated AND set of comparators
- * (`>=4.16.0 <5.0.0`), caret (`^4.0.0`), tilde (`~4.16.0`), partial versions
- * (`>=4.16`), and the wildcard (`*` / `x`). OR (`||`) is not supported and is
- * reported as an invalid range.
- *
- * Prerelease handling diverges from node-semver and is intentionally more
- * permissive: a prerelease version satisfies any comparator whose ordering it
- * meets, with no requirement that the comparator share its `[major,minor,patch]`
- * tuple. So `5.0.0-alpha` satisfies `>=4.16.0 <5.0.0` here where node-semver
- * would reject it. Hosts almost never run prerelease Astro/EmDash builds and the
- * gate fails open on a definite-mismatch-only basis, so the looser semantics
- * can only let an install through, never wrongly block one. Tightening this to
- * node-semver's prerelease gating is a deliberate future change, not a bug.
- *
- * Pure, dependency-free, and isomorphic so the CLI (publish-time validation),
- * the server (install/update gate), and the admin (browser compat warning)
- * all share one implementation.
+ * Range evaluation delegates to node-semver (`satisfies` / `validRange` /
+ * `valid`), so the full range grammar — comparator sets, caret, tilde, partial
+ * versions, wildcards, and `||` unions — and node-semver's prerelease gating
+ * apply. semver is pure JS, so this stays isomorphic across the CLI
+ * (publish-time validation), the server (install/update gate), and the admin
+ * (browser compat warning), all sharing one implementation.
  */
 
+import { satisfies, valid, validRange } from "semver";
+
 export interface HostEnv {
 	/** Map of `env:*` key to the host's current version of that environment. */
 	[key: string]: string | undefined;
@@ -41,39 +31,11 @@ export interface EnvMismatch {
 	host: string;
 }
 
-/** A parsed semver version. Prerelease is compared lexically per semver §11. */
-interface ParsedVersion {
-	major: number;
-	minor: number;
-	patch: number;
-	prerelease: string[];
-}
-
 /** `env:<name>` keys, where `<name>` is one or more non-colon characters. */
 const ENV_KEY_RE = /^env:[^:]+$/;
 /** Structural DID shape: `did:<method>:<id>` (forward-compat for package deps). */
 const DID_KEY_RE = /^did:[a-z]+:.+$/;
 
-/** A full or partial semver version, optionally prerelease-tagged. */
-const VERSION_RE =
-	/^(0|[1-9]\d*)(?:\.(0|[1-9]\d*|x|\*)(?:\.(0|[1-9]\d*|x|\*))?)?(?:-([0-9A-Za-z.-]+))?$/;
-
-/** A complete `MAJOR.MINOR.PATCH` version, optionally prerelease-tagged. */
-const FULL_VERSION_RE = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z.-]+))?$/;
-
-/** Whitespace separator between comparators in an AND-joined range. */
-const WHITESPACE_RE = /\s+/;
-
-/** A purely numeric prerelease identifier (compared numerically per semver §11). */
-const NUMERIC_IDENTIFIER_RE = /^\d+$/;
-
-type Operator = ">=" | ">" | "<=" | "<" | "=";
-
-interface Comparator {
-	op: Operator;
-	version: ParsedVersion;
-}
-
 /**
  * Build the host-environment map the install/update gate compares a release's
  * `requires` against, from the EmDash and Astro versions the host advertises.
@@ -110,9 +72,15 @@ export function parseRequires(value: unknown): Record<string, string> {
 	return out;
 }
 
-/** True when `range` is a syntactically valid version range we can evaluate. */
+/**
+ * True when `range` is a syntactically valid version range we can evaluate.
+ *
+ * The empty string is rejected: node-semver normalises it to `*` (match any),
+ * which is never what a publisher means when they write a constraint.
+ */
 export function isValidVersionRange(range: string): boolean {
-	return parseRange(range) !== null;
+	if (range.trim() === "") return false;
+	return validRange(range) !== null;
 }
 
 /**
@@ -122,13 +90,16 @@ export function isValidVersionRange(range: string): boolean {
  * host version cannot be proven incompatible, and an unparseable range is
  * garbage we decline to enforce. Both cases are non-blocking by design — the
  * gate only refuses on a definite mismatch.
+ *
+ * `includePrerelease` evaluates a prerelease host version (a beta EmDash/Astro
+ * build) by its precedence rather than excluding it from release-only ranges.
+ * Without it, node-semver would refuse `1.0.0-rc.1` against `*` or `>=0.13.0`,
+ * blocking a prerelease host that is not a definite mismatch.
  */
 export function satisfiesRange(version: string, range: string): boolean {
-	const v = parseVersion(version);
-	if (v === null) return true;
-	const comparators = parseRange(range);
-	if (comparators === null) return true;
-	return comparators.every((c) => satisfiesComparator(v, c));
+	if (valid(version) === null) return true;
+	if (validRange(range) === null) return true;
+	return satisfies(version, range, { includePrerelease: true });
 }
 
 /**
@@ -187,218 +158,9 @@ export function findSkippedEnvConstraints(
 		const hostVersion = host[key];
 		if (hostVersion === undefined) {
 			skipped.push({ key, required: range, reason: "unknown" });
-		} else if (parseVersion(hostVersion) === null) {
+		} else if (valid(hostVersion) === null) {
 			skipped.push({ key, required: range, reason: "unparseable" });
 		}
 	}
 	return skipped;
 }
-
-function satisfiesComparator(v: ParsedVersion, c: Comparator): boolean {
-	const cmp = compareVersions(v, c.version);
-	switch (c.op) {
-		case ">=":
-			return cmp >= 0;
-		case ">":
-			return cmp > 0;
-		case "<=":
-			return cmp <= 0;
-		case "<":
-			return cmp < 0;
-		case "=":
-			return cmp === 0;
-	}
-}
-
-/**
- * Parse a range into the AND set of comparators it expands to, or `null` when
- * the range is syntactically invalid. The wildcard `*` parses to an empty set
- * (matches everything).
- */
-function parseRange(range: string): Comparator[] | null {
-	const trimmed = range.trim();
-	if (trimmed === "") return null;
-	if (trimmed === "*") return [];
-	if (trimmed.includes("||")) return null;
-
-	const tokens = trimmed.split(WHITESPACE_RE);
-	const comparators: Comparator[] = [];
-	for (const token of tokens) {
-		const expanded = parseComparatorToken(token);
-		if (expanded === null) return null;
-		comparators.push(...expanded);
-	}
-	return comparators;
-}
-
-function parseComparatorToken(token: string): Comparator[] | null {
-	if (token.startsWith("^")) return parseCaret(token.slice(1));
-	if (token.startsWith("~")) return parseTilde(token.slice(1));
-
-	let op: Operator = "=";
-	let rest = token;
-	if (token.startsWith(">=")) {
-		op = ">=";
-		rest = token.slice(2);
-	} else if (token.startsWith("<=")) {
-		op = "<=";
-		rest = token.slice(2);
-	} else if (token.startsWith(">")) {
-		op = ">";
-		rest = token.slice(1);
-	} else if (token.startsWith("<")) {
-		op = "<";
-		rest = token.slice(1);
-	} else if (token.startsWith("=")) {
-		op = "=";
-		rest = token.slice(1);
-	}
-
-	if (rest === "*" || rest === "x") {
-		// Bare wildcard with a comparator (e.g. `>=*`) is degenerate; treat the
-		// version-only wildcard as "any" and any comparator as unconstrained.
-		return [];
-	}
-
-	const partial = parsePartialVersion(rest);
-	if (partial === null) return null;
-
-	// An `=` against a partial version (`=4.16`, `4.x`) becomes a bounded range
-	// covering the missing segments rather than an exact match.
-	if (op === "=" && partial.wildcard) {
-		return wildcardToRange(partial);
-	}
-	return [{ op, version: partial.version }];
-}
-
-interface PartialVersion {
-	version: ParsedVersion;
-	/** True when the source omitted minor/patch or used `x`/`*` for them. */
-	wildcard: boolean;
-	/** Index of the first wildcarded/omitted segment (1 = minor, 2 = patch). */
-	wildcardAt: number;
-}
-
-function parsePartialVersion(raw: string): PartialVersion | null {
-	if (!VERSION_RE.test(raw)) return null;
-	const [main, prerelease] = raw.split("-", 2);
-	const segments = main!.split(".");
-	let wildcardAt = segments.length;
-	const nums: number[] = [];
-	for (let i = 0; i < 3; i++) {
-		const seg = segments[i];
-		if (seg === undefined || seg === "x" || seg === "*") {
-			if (wildcardAt === segments.length || i < wildcardAt) wildcardAt = Math.min(wildcardAt, i);
-			nums.push(0);
-		} else {
-			nums.push(Number(seg));
-		}
-	}
-	const wildcard = wildcardAt < 3;
-	return {
-		version: {
-			major: nums[0]!,
-			minor: nums[1]!,
-			patch: nums[2]!,
-			prerelease: prerelease ? prerelease.split(".") : [],
-		},
-		wildcard,
-		wildcardAt,
-	};
-}
-
-/** Expand a wildcarded `=` version (`4.x`, `4.16`) to a `>= lower < upper` pair. */
-function wildcardToRange(partial: PartialVersion): Comparator[] {
-	const { version, wildcardAt } = partial;
-	const lower: ParsedVersion = { ...version, prerelease: [] };
-	const upper: ParsedVersion =
-		wildcardAt <= 1
-			? { major: version.major + 1, minor: 0, patch: 0, prerelease: [] }
-			: { major: version.major, minor: version.minor + 1, patch: 0, prerelease: [] };
-	return [
-		{ op: ">=", version: lower },
-		{ op: "<", version: upper },
-	];
-}
-
-function parseCaret(raw: string): Comparator[] | null {
-	const partial = parsePartialVersion(raw);
-	if (partial === null) return null;
-	const { version } = partial;
-	const lower = version;
-	let upper: ParsedVersion;
-	if (version.major > 0) {
-		upper = { major: version.major + 1, minor: 0, patch: 0, prerelease: [] };
-	} else if (version.minor > 0) {
-		upper = { major: 0, minor: version.minor + 1, patch: 0, prerelease: [] };
-	} else {
-		upper = { major: 0, minor: 0, patch: version.patch + 1, prerelease: [] };
-	}
-	return [
-		{ op: ">=", version: lower },
-		{ op: "<", version: upper },
-	];
-}
-
-function parseTilde(raw: string): Comparator[] | null {
-	const partial = parsePartialVersion(raw);
-	if (partial === null) return null;
-	const { version, wildcardAt } = partial;
-	const lower = version;
-	// `~1` (major-only) allows the whole 1.x range; `~1.2` / `~1.2.3` allow
-	// patch-level changes within the stated minor.
-	const upper: ParsedVersion =
-		wildcardAt <= 1
-			? { major: version.major + 1, minor: 0, patch: 0, prerelease: [] }
-			: { major: version.major, minor: version.minor + 1, patch: 0, prerelease: [] };
-	return [
-		{ op: ">=", version: lower },
-		{ op: "<", version: upper },
-	];
-}
-
-function parseVersion(raw: string): ParsedVersion | null {
-	const trimmed = raw.trim();
-	const match = FULL_VERSION_RE.exec(trimmed);
-	if (!match) return null;
-	return {
-		major: Number(match[1]),
-		minor: Number(match[2]),
-		patch: Number(match[3]),
-		prerelease: match[4] ? match[4].split(".") : [],
-	};
-}
-
-function compareVersions(a: ParsedVersion, b: ParsedVersion): number {
-	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;
-	return comparePrerelease(a.prerelease, b.prerelease);
-}
-
-/** Semver §11: a version with a prerelease has lower precedence than one without. */
-function comparePrerelease(a: string[], b: string[]): number {
-	if (a.length === 0 && b.length === 0) return 0;
-	if (a.length === 0) return 1;
-	if (b.length === 0) return -1;
-	const len = Math.max(a.length, b.length);
-	for (let i = 0; i < len; i++) {
-		const ai = a[i];
-		const bi = b[i];
-		if (ai === undefined) return -1;
-		if (bi === undefined) return 1;
-		const an = NUMERIC_IDENTIFIER_RE.test(ai);
-		const bn = NUMERIC_IDENTIFIER_RE.test(bi);
-		if (an && bn) {
-			const diff = Number(ai) - Number(bi);
-			if (diff !== 0) return diff;
-		} else if (an) {
-			return -1;
-		} else if (bn) {
-			return 1;
-		} else if (ai !== bi) {
-			return ai < bi ? -1 : 1;
-		}
-	}
-	return 0;
-}
diff --git a/packages/registry-client/tests/env.test.ts b/packages/registry-client/tests/env.test.ts
index 3e0898384..287ec04a3 100644
--- a/packages/registry-client/tests/env.test.ts
+++ b/packages/registry-client/tests/env.test.ts
@@ -37,6 +37,10 @@ describe("isValidVersionRange", () => {
 		expect(isValidVersionRange(">=4.16.0 <5.0.0")).toBe(true);
 	});
 
+	it("accepts || union ranges", () => {
+		expect(isValidVersionRange("^4.0.0 || ^5.0.0")).toBe(true);
+	});
+
 	it("accepts prerelease versions in comparators", () => {
 		expect(isValidVersionRange(">=6.0.0-beta.0")).toBe(true);
 	});
@@ -82,6 +86,16 @@ describe("satisfiesRange", () => {
 		expect(satisfiesRange("1.0.0-rc.1", "*")).toBe(true);
 	});
 
+	it("evaluates || union ranges", () => {
+		expect(satisfiesRange("5.1.0", "^4.0.0 || ^5.0.0")).toBe(true);
+		expect(satisfiesRange("3.0.0", "^4.0.0 || ^5.0.0")).toBe(false);
+	});
+
+	it("evaluates a prerelease host by precedence, not excluded from release ranges", () => {
+		expect(satisfiesRange("1.0.0-rc.1", ">=0.13.0")).toBe(true);
+		expect(satisfiesRange("4.1.0-beta.2", "^4.0.0")).toBe(true);
+	});
+
 	it("treats an unparseable host version as satisfied (cannot prove incompatible)", () => {
 		expect(satisfiesRange("dev", ">=4.16")).toBe(true);
 		expect(satisfiesRange("", ">=4.16")).toBe(true);
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 64bc08ef1..46771d3f5 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -207,6 +207,9 @@ catalogs:
     '@types/react-dom':
       specifier: 19.2.3
       version: 19.2.3
+    '@types/semver':
+      specifier: ^7.5.8
+      version: 7.7.1
     astro:
       specifier: ^6.3.0
       version: 6.3.5
@@ -234,6 +237,9 @@ catalogs:
     react-dom:
       specifier: 19.2.4
       version: 19.2.4
+    semver:
+      specifier: ^7.6.3
+      version: 7.7.4
     tsdown:
       specifier: 0.20.3
       version: 0.20.3
@@ -366,7 +372,7 @@ importers:
     devDependencies:
       '@cloudflare/vite-plugin':
         specifier: 'catalog:'
-        version: 1.36.3(vite@8.0.11(@types/node@24.10.13)(esbuild@0.27.3)(jiti@2.6.1)(yaml@2.9.0))(workerd@1.20260507.1)(wrangler@4.95.0)
+        version: 1.36.3(vite@8.0.11(@types/node@24.10.13)(esbuild@0.27.3)(jiti@2.6.1)(yaml@2.9.0))(workerd@1.20260526.1)(wrangler@4.95.0)
       '@cloudflare/vitest-pool-workers':
         specifier: 'catalog:'
         version: 0.16.3(@vitest/runner@4.1.5)(@vitest/snapshot@4.1.5)(vitest@4.1.5)
@@ -2005,6 +2011,9 @@ importers:
       '@emdash-cms/registry-lexicons':
         specifier: workspace:*
         version: link:../registry-lexicons
+      semver:
+        specifier: 'catalog:'
+        version: 7.7.4
     devDependencies:
       '@arethetypeswrong/cli':
         specifier: 'catalog:'
@@ -2012,6 +2021,9 @@ importers:
       '@types/node':
         specifier: 'catalog:'
         version: 24.10.13
+      '@types/semver':
+        specifier: 'catalog:'
+        version: 7.7.1
       publint:
         specifier: 'catalog:'
         version: 0.3.17
@@ -6776,6 +6788,9 @@ packages:
   '@types/sax@1.2.7':
     resolution: {integrity: sha512-rO73L89PJxeYM3s3pPPjiPgVVcymqU490g0YO5n5By0k2Erzj6tay/4lr1CHAAU4JyOWd1rpQ8bCf6cZfHU96A==}
 
+  '@types/semver@7.7.1':
+    resolution: {integrity: sha512-FmgJfu+MOcQ370SD0ev7EI8TlCAfKYU+B4m5T3yXc1CiRN94g/SZPtsCkk506aUDtlMnFZvasDwHHUcZUEaYuA==}
+
   '@types/trusted-types@2.0.7':
     resolution: {integrity: sha512-ScaPdn1dQczgbl0QFTeTOmVHFULt394XJgOQNoyVhZ6r2vLnMLJfBPd53SB52T/3G36VI1/g2MZaX0cwDuXsfw==}
 
@@ -13344,9 +13359,9 @@ snapshots:
       - utf-8-validate
       - workerd
 
-  '@cloudflare/vite-plugin@1.36.3(vite@8.0.11(@types/node@24.10.13)(esbuild@0.27.3)(jiti@2.6.1)(yaml@2.9.0))(workerd@1.20260507.1)(wrangler@4.95.0)':
+  '@cloudflare/vite-plugin@1.36.3(vite@8.0.11(@types/node@24.10.13)(esbuild@0.27.3)(jiti@2.6.1)(yaml@2.9.0))(workerd@1.20260526.1)(wrangler@4.95.0)':
     dependencies:
-      '@cloudflare/unenv-preset': 2.16.1(unenv@2.0.0-rc.24)(workerd@1.20260507.1)
+      '@cloudflare/unenv-preset': 2.16.1(unenv@2.0.0-rc.24)(workerd@1.20260526.1)
       miniflare: 4.20260507.1
       unenv: 2.0.0-rc.24
       vite: 8.0.11(@types/node@24.10.13)(esbuild@0.27.3)(jiti@2.6.1)(yaml@2.9.0)
@@ -16449,6 +16464,8 @@ snapshots:
     dependencies:
       '@types/node': 24.10.13
 
+  '@types/semver@7.7.1': {}
+
   '@types/trusted-types@2.0.7':
     optional: true
 
@@ -16761,7 +16778,7 @@ snapshots:
       sirv: 3.0.2
       tinyglobby: 0.2.16
       tinyrainbow: 3.1.0
-      vitest: 4.1.5(@opentelemetry/api@1.9.0)(@types/node@24.10.13)(@vitest/browser-playwright@4.1.5)(@vitest/ui@4.1.5)(jsdom@26.1.0)(vite@8.0.14(@types/node@24.10.13)(esbuild@0.27.3)(jiti@2.6.1)(yaml@2.9.0))
+      vitest: 4.1.5(@opentelemetry/api@1.9.0)(@types/node@24.10.13)(@vitest/browser-playwright@4.1.5)(@vitest/ui@4.1.5)(jsdom@26.1.0)(vite@8.0.11(@types/node@24.10.13)(esbuild@0.27.3)(jiti@2.6.1)(yaml@2.9.0))
 
   '@vitest/utils@4.1.5':
     dependencies:
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index 301d802b6..65f1c3eb4 100644
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -132,6 +132,7 @@ catalog:
   "@types/better-sqlite3": ^7.6.12
   "@types/react": 19.2.14
   "@types/react-dom": 19.2.3
+  "@types/semver": ^7.5.8
   astro: ^6.3.0
   astro-iconset: ^0.0.4
   better-sqlite3: ^12.8.0
@@ -141,6 +142,7 @@ catalog:
   publint: 0.3.17
   react: 19.2.4
   react-dom: 19.2.4
+  semver: ^7.6.3
   tsdown: 0.20.3
   typescript: ^6.0.3
   vite: ^8.0.11

From 716803b355ef99685476af3ceccb57491ea3792c Mon Sep 17 00:00:00 2001
From: Matt Kane <m@mk.gg>
Date: Sun, 31 May 2026 14:59:56 +0100
Subject: [PATCH 4/5] refactor(registry): drop redundant buildHostEnv wrapper

buildHostEnv was a pure pass-through to hostEnvFromVersions (the shared
registry-client/env helper). The install/update routes now call
hostEnvFromVersions directly, and its duplicate dev-skip/astro-omit test
block is removed (covered by registry-client's env tests).
---
 packages/core/src/api/handlers/index.ts       |  1 -
 packages/core/src/api/handlers/registry.ts    | 16 +---------------
 .../api/admin/plugins/registry/[id]/update.ts |  5 +++--
 .../api/admin/plugins/registry/install.ts     |  5 +++--
 .../unit/api/registry-env-compat.test.ts      | 19 +------------------
 5 files changed, 8 insertions(+), 38 deletions(-)

diff --git a/packages/core/src/api/handlers/index.ts b/packages/core/src/api/handlers/index.ts
index 77d9aec62..9429fe755 100644
--- a/packages/core/src/api/handlers/index.ts
+++ b/packages/core/src/api/handlers/index.ts
@@ -172,7 +172,6 @@ export {
 // Registry handlers (experimental)
 export {
 	assertEnvCompatible,
-	buildHostEnv,
 	handleRegistryInstall,
 	handleRegistryUninstall,
 	handleRegistryUpdate,
diff --git a/packages/core/src/api/handlers/registry.ts b/packages/core/src/api/handlers/registry.ts
index 482e66e1f..51bb70d9a 100644
--- a/packages/core/src/api/handlers/registry.ts
+++ b/packages/core/src/api/handlers/registry.ts
@@ -40,11 +40,7 @@
 
 import { ClientResponseError, ClientValidationError } from "@atcute/client";
 import type { Did } from "@atcute/lexicons";
-import {
-	checkEnvCompatibility,
-	findSkippedEnvConstraints,
-	hostEnvFromVersions,
-} from "@emdash-cms/registry-client/env";
+import { checkEnvCompatibility, findSkippedEnvConstraints } from "@emdash-cms/registry-client/env";
 import type { HostEnv } from "@emdash-cms/registry-client/env";
 import type { Kysely } from "kysely";
 
@@ -526,16 +522,6 @@ async function fetchArtifact(mirrors: string[], declaredUrl: string): Promise<Ui
 	);
 }
 
-/**
- * Build the host-environment map the install/update gate compares a release's
- * `requires` against. Delegates to the shared {@link hostEnvFromVersions} so the
- * server gate and the admin's client-side warning apply the same dev-skip /
- * astro-omit rule.
- */
-export function buildHostEnv(emdashVersion: string, astroVersion: string | undefined): HostEnv {
-	return hostEnvFromVersions(emdashVersion, astroVersion);
-}
-
 /**
  * The shape of a single env-compatibility failure returned to the admin in
  * the `ENV_INCOMPATIBLE` error's `details`.
diff --git a/packages/core/src/astro/routes/api/admin/plugins/registry/[id]/update.ts b/packages/core/src/astro/routes/api/admin/plugins/registry/[id]/update.ts
index b3c086c5e..7d85b5c1e 100644
--- a/packages/core/src/astro/routes/api/admin/plugins/registry/[id]/update.ts
+++ b/packages/core/src/astro/routes/api/admin/plugins/registry/[id]/update.ts
@@ -9,12 +9,13 @@
  * routes and `confirmRouteVisibilityChanges` is absent.
  */
 
+import { hostEnvFromVersions } from "@emdash-cms/registry-client/env";
 import type { APIRoute } from "astro";
 import { z } from "zod";
 
 import { requirePerm } from "#api/authorize.js";
 import { apiError, handleError, unwrapResult } from "#api/error.js";
-import { buildHostEnv, handleRegistryUpdate } from "#api/index.js";
+import { handleRegistryUpdate } from "#api/index.js";
 import { isParseError, parseOptionalBody } from "#api/parse.js";
 
 import { VERSION } from "../../../../../../../version.js";
@@ -66,7 +67,7 @@ export const POST: APIRoute = async ({ params, request, locals }) => {
 				version: body.version,
 				confirmCapabilityChanges: body.confirmCapabilityChanges,
 				confirmRouteVisibilityChanges: body.confirmRouteVisibilityChanges,
-				hostEnv: buildHostEnv(VERSION, emdash.config.astroVersion),
+				hostEnv: hostEnvFromVersions(VERSION, emdash.config.astroVersion),
 			},
 		);
 
diff --git a/packages/core/src/astro/routes/api/admin/plugins/registry/install.ts b/packages/core/src/astro/routes/api/admin/plugins/registry/install.ts
index 3ed8620a8..20e7a966d 100644
--- a/packages/core/src/astro/routes/api/admin/plugins/registry/install.ts
+++ b/packages/core/src/astro/routes/api/admin/plugins/registry/install.ts
@@ -12,12 +12,13 @@
  * view time (handle is best-effort per the lexicon).
  */
 
+import { hostEnvFromVersions } from "@emdash-cms/registry-client/env";
 import type { APIRoute } from "astro";
 import { z } from "zod";
 
 import { requirePerm } from "#api/authorize.js";
 import { apiError, handleError, unwrapResult } from "#api/error.js";
-import { buildHostEnv, handleRegistryInstall } from "#api/index.js";
+import { handleRegistryInstall } from "#api/index.js";
 import { isParseError, parseBody } from "#api/parse.js";
 
 import { VERSION } from "../../../../../../version.js";
@@ -95,7 +96,7 @@ export const POST: APIRoute = async ({ request, locals }) => {
 			},
 			{
 				configuredPluginIds: reservedPluginIds,
-				hostEnv: buildHostEnv(VERSION, emdash.config.astroVersion),
+				hostEnv: hostEnvFromVersions(VERSION, emdash.config.astroVersion),
 			},
 		);
 
diff --git a/packages/core/tests/unit/api/registry-env-compat.test.ts b/packages/core/tests/unit/api/registry-env-compat.test.ts
index a0522aa11..8c79358b9 100644
--- a/packages/core/tests/unit/api/registry-env-compat.test.ts
+++ b/packages/core/tests/unit/api/registry-env-compat.test.ts
@@ -12,24 +12,7 @@
 import { describe, expect, it } from "vitest";
 
 import { mapErrorStatus } from "../../../src/api/errors.js";
-import { assertEnvCompatible, buildHostEnv } from "../../../src/api/handlers/registry.js";
-
-describe("buildHostEnv", () => {
-	it("maps emdash + astro versions to env:* keys", () => {
-		expect(buildHostEnv("1.2.0", "4.16.0")).toEqual({
-			"env:emdash": "1.2.0",
-			"env:astro": "4.16.0",
-		});
-	});
-
-	it("omits a dev emdash build so the gate skips it", () => {
-		expect(buildHostEnv("dev", "4.16.0")).toEqual({ "env:astro": "4.16.0" });
-	});
-
-	it("omits astro when its version is unknown", () => {
-		expect(buildHostEnv("1.2.0", undefined)).toEqual({ "env:emdash": "1.2.0" });
-	});
-});
+import { assertEnvCompatible } from "../../../src/api/handlers/registry.js";
 
 describe("assertEnvCompatible", () => {
 	const host = { "env:emdash": "1.2.0", "env:astro": "4.12.0" };

From 2d4364cdeca48bafa775913cea3419c7b07922f1 Mon Sep 17 00:00:00 2001
From: Matt Kane <m@mk.gg>
Date: Sun, 31 May 2026 15:23:27 +0100
Subject: [PATCH 5/5] refactor(registry): nest requires under release.requires

Aligns env constraints with release.artifacts (merged in #1239) under a
single release block, matching the RFC. repo stays top-level (documented
legacy for backwards compatibility). Publish reads manifest.release.requires;
the normalised manifest keeps a flat requires field.
---
 .../schemas/emdash-plugin.schema.json         | 38 +++++++++----------
 packages/plugin-cli/src/manifest/schema.ts    | 10 +++--
 packages/plugin-cli/src/manifest/translate.ts |  2 +-
 .../plugin-cli/tests/manifest-schema.test.ts  |  6 +--
 .../tests/manifest-translate.test.ts          |  2 +-
 5 files changed, 30 insertions(+), 28 deletions(-)

diff --git a/packages/plugin-cli/schemas/emdash-plugin.schema.json b/packages/plugin-cli/schemas/emdash-plugin.schema.json
index 53669b1a0..a36973805 100644
--- a/packages/plugin-cli/schemas/emdash-plugin.schema.json
+++ b/packages/plugin-cli/schemas/emdash-plugin.schema.json
@@ -56,11 +56,8 @@
 		"repo": {
 			"$ref": "#/$defs/__schema42"
 		},
-		"requires": {
-			"$ref": "#/$defs/__schema43"
-		},
 		"release": {
-			"$ref": "#/$defs/__schema46"
+			"$ref": "#/$defs/__schema43"
 		}
 	},
 	"required": [
@@ -473,12 +470,26 @@
 			]
 		},
 		"__schema43": {
+			"type": "object",
+			"properties": {
+				"requires": {
+					"$ref": "#/$defs/__schema44"
+				},
+				"artifacts": {
+					"$ref": "#/$defs/__schema47"
+				}
+			},
+			"additionalProperties": false,
+			"title": "Release",
+			"description": "Per-release fields: environment constraints (`requires`) and media artifacts (icon / screenshot / banner)."
+		},
+		"__schema44": {
 			"type": "object",
 			"propertyNames": {
-				"$ref": "#/$defs/__schema44"
+				"$ref": "#/$defs/__schema45"
 			},
 			"additionalProperties": {
-				"$ref": "#/$defs/__schema45"
+				"$ref": "#/$defs/__schema46"
 			},
 			"title": "Environment requirements",
 			"description": "Host environment constraints for this release, keyed by `env:*` (e.g. \"env:astro\", \"env:emdash\") with semver-range values. EmDash refuses to install a release whose constraints the host does not satisfy.",
@@ -489,24 +500,13 @@
 				}
 			]
 		},
-		"__schema44": {
+		"__schema45": {
 			"type": "string"
 		},
-		"__schema45": {
+		"__schema46": {
 			"type": "string",
 			"minLength": 1
 		},
-		"__schema46": {
-			"type": "object",
-			"properties": {
-				"artifacts": {
-					"$ref": "#/$defs/__schema47"
-				}
-			},
-			"additionalProperties": false,
-			"title": "Release",
-			"description": "Per-release fields, such as media artifacts (icon / screenshot / banner)."
-		},
 		"__schema47": {
 			"type": "object",
 			"properties": {
diff --git a/packages/plugin-cli/src/manifest/schema.ts b/packages/plugin-cli/src/manifest/schema.ts
index dfd0d2cc3..cdb7e74ba 100644
--- a/packages/plugin-cli/src/manifest/schema.ts
+++ b/packages/plugin-cli/src/manifest/schema.ts
@@ -640,12 +640,14 @@ export const ArtifactsSchema = z
  */
 export const ReleaseSchema = z
 	.object({
+		requires: RequiresSchema.optional(),
 		artifacts: ArtifactsSchema.optional(),
 	})
 	.strict()
 	.meta({
 		title: "Release",
-		description: "Per-release fields, such as media artifacts (icon / screenshot / banner).",
+		description:
+			"Per-release fields: environment constraints (`requires`) and media artifacts (icon / screenshot / banner).",
 	});
 
 // ──────────────────────────────────────────────────────────────────────────
@@ -753,10 +755,10 @@ export const ManifestSchema = z
 
 		// Optional release fields.
 		repo: RepoSchema.optional(),
-		requires: RequiresSchema.optional(),
 
-		// Per-release media artifacts (icon / screenshot / banner). File
-		// refs are resolved relative to the manifest at publish time.
+		// Per-release block: environment constraints (`requires`) and media
+		// artifacts (icon / screenshot / banner). File refs are resolved
+		// relative to the manifest at publish time.
 		release: ReleaseSchema.optional(),
 	})
 	.strict()
diff --git a/packages/plugin-cli/src/manifest/translate.ts b/packages/plugin-cli/src/manifest/translate.ts
index dc4b2efdd..08a69c74f 100644
--- a/packages/plugin-cli/src/manifest/translate.ts
+++ b/packages/plugin-cli/src/manifest/translate.ts
@@ -185,7 +185,7 @@ export function normaliseManifest(manifest: Manifest, packageVersion?: string):
 		description: manifest.description,
 		keywords: manifest.keywords,
 		repo: manifest.repo,
-		requires: manifest.requires,
+		requires: manifest.release?.requires,
 		artifacts: manifest.release?.artifacts,
 		// Schema validation already gates capability strings to the
 		// current vocabulary via a runtime check, so by the time we get
diff --git a/packages/plugin-cli/tests/manifest-schema.test.ts b/packages/plugin-cli/tests/manifest-schema.test.ts
index 80c03e81c..2237244c8 100644
--- a/packages/plugin-cli/tests/manifest-schema.test.ts
+++ b/packages/plugin-cli/tests/manifest-schema.test.ts
@@ -376,7 +376,7 @@ describe("ManifestSchema (full document)", () => {
 			description: "Image gallery block for EmDash.",
 			keywords: ["gallery", "images", "media"],
 			repo: "https://github.com/emdash-cms/plugin-gallery",
-			requires: { "env:emdash": ">=1.0.0", "env:astro": ">=4.16" },
+			release: { requires: { "env:emdash": ">=1.0.0", "env:astro": ">=4.16" } },
 			capabilities: ["content:read"],
 			storage: { events: { indexes: ["timestamp"] } },
 		});
@@ -386,7 +386,7 @@ describe("ManifestSchema (full document)", () => {
 	it("accepts a manifest with release-level requires", () => {
 		const result = ManifestSchema.safeParse({
 			...minimal,
-			requires: { "env:astro": ">=4.16" },
+			release: { requires: { "env:astro": ">=4.16" } },
 		});
 		expect(result.success).toBe(true);
 	});
@@ -394,7 +394,7 @@ describe("ManifestSchema (full document)", () => {
 	it("rejects a manifest with an invalid requires range", () => {
 		const result = ManifestSchema.safeParse({
 			...minimal,
-			requires: { "env:astro": "not-a-range" },
+			release: { requires: { "env:astro": "not-a-range" } },
 		});
 		expect(result.success).toBe(false);
 	});
diff --git a/packages/plugin-cli/tests/manifest-translate.test.ts b/packages/plugin-cli/tests/manifest-translate.test.ts
index 31025d9d4..501d3332b 100644
--- a/packages/plugin-cli/tests/manifest-translate.test.ts
+++ b/packages/plugin-cli/tests/manifest-translate.test.ts
@@ -100,7 +100,7 @@ describe("normaliseManifest", () => {
 			license: "MIT",
 			author: { name: "Jane" },
 			security: { email: "s@example.com" },
-			requires: { "env:emdash": ">=1.0.0", "env:astro": ">=4.16" },
+			release: { requires: { "env:emdash": ">=1.0.0", "env:astro": ">=4.16" } },
 		});
 		expect(normalised.requires).toEqual({ "env:emdash": ">=1.0.0", "env:astro": ">=4.16" });
 	});