@warlock.js/web 5.0.0

package/esm/vite/gate-c-verify.d.mts

@@ -0,0 +1,118 @@
+import { EnvironmentClassifier, EnvironmentClassifierOptions } from "./gate-a-resolve.mjs";
+import { PublicEnvTracker } from "./gate-b-secrets.mjs";
+import { Plugin } from "vite";
+
+//#region ../web/src/vite/gate-c-verify.d.ts
+interface ServerExportLeak {
+  fileName: string;
+  exportName: string;
+  line?: number;
+}
+interface ServerImportEdgeLeak {
+  fileName: string;
+  moduleId: string;
+  packageName: string;
+}
+interface PublicEnvManifestEntry {
+  key: string;
+  /** `null` when `redacted` is true — see `isSafeToShowValue`. */
+  value: string | null;
+  redacted: boolean;
+}
+/**
+ * A structurally-minimal view of Rollup's `OutputBundle` — only the fields
+ * Gate C actually reads. Deliberately NOT the real `OutputBundle`/`OutputChunk`
+ * types: Part 1's own discipline requires proving Gate C catches a bundle
+ * that a real pipeline could never produce (a hand-built leaked chunk), and
+ * forcing every test fixture to satisfy Rollup's full chunk shape would
+ * fight that requirement for no safety benefit — Vite's real `generateBundle`
+ * hook still hands Gate C a real `OutputBundle`, which is a structural
+ * superset of this.
+ */
+type BundleLike = Record<string, {
+  type?: string;
+  fileName?: string;
+  code?: string;
+  moduleIds?: readonly string[];
+}>;
+/**
+ * Thrown when an emitted chunk cannot be parsed, which means Gate C could not
+ * inspect it. A gate that skips what it cannot read reports "no violation
+ * found" on precisely the input it failed to look at — the one input where
+ * that answer is worthless. So an unreadable chunk fails the build instead.
+ */
+/**
+ * Part 1, item 1: parses each emitted chunk's ACTUAL code (never pre-transform
+ * source) and looks for a top-level binding named one of the five server
+ * exports. A parse failure on an emitted chunk FAILS the gate
+ * (`UnverifiableChunkError`) — it is never skipped. Skipping would report the
+ * bundle clean on the one chunk the gate did not actually inspect, which is a
+ * safety check failing open; a build stopped on an unreadable chunk is
+ * recoverable, a boundary silently unenforced is not.
+ *
+ * This SURVIVES real minification (pinned by the `gate-c-verify.spec.ts`
+ * "D.8" describe block). A minifier (esbuild,
+ * Vite's default) is only free to rename LOCAL bindings; the exported name
+ * itself is part of the module's public interface and is never mangled — a
+ * minified `export const route = ...` still emits `export { e as route }`,
+ * with the local identifier renamed (`e`) but `route` intact as the specifier's
+ * `exported` name, which is exactly the field `collectServerExportNames`
+ * reads for the `ExportNamedDeclaration` specifier form. No name-independent
+ * redesign needed here — verified against a real `build.minify: true` output,
+ * not assumed.
+ */
+declare function findLeakedServerExports(bundle: BundleLike): ServerExportLeak[];
+/**
+ * Part 1, item 2: walks every emitted chunk's `moduleIds` (the resolved,
+ * absolute file paths of every source module Rollup actually bundled into
+ * that chunk) and classifies each one via the SAME `EnvironmentClassifier`
+ * Gate A's `resolveId` uses, re-derived from `gate-a-resolve.ts` rather than
+ * hand-rolled a second time. A moduleId that maps to a governed-scope
+ * package classified `"server"` is an import edge Gate A should already
+ * have refused — if it's here anyway, the earlier gate has a bug.
+ *
+ * D.8 verdict: this SURVIVES real minification unconditionally, and for a
+ * stronger reason than item 1 above — it never reads emitted code text or
+ * identifier names at all. `moduleIds` is Rollup's own bundling metadata
+ * (which resolved source files ended up in this chunk), untouched by
+ * minification, which only rewrites code, not that metadata. Verified
+ * against a real `build.minify: true` output in `gate-c-verify.spec.ts`.
+ */
+declare function findLeakedServerImportEdges(bundle: BundleLike, classifier: Pick<EnvironmentClassifier, "environmentOf" | "packageNameForFilePath">): ServerImportEdgeLeak[];
+/**
+ * The enumerated, human-reviewable list of
+ * every `PUBLIC_*` key actually inlined into the client bundle. Built
+ * directly from `tracker.referencedKeys` — the exact same `Set` Gate B's own
+ * `generateBundle` unread-key check (`gate-b-secrets.ts`) reads from — so
+ * this manifest and that exclusion logic agree BY CONSTRUCTION: they are two
+ * readers of one Set, not two independent recomputations of "which keys were
+ * read" that could drift apart. A key only reaches `referencedKeys` once
+ * `findViolation` in `gate-b-secrets.ts` has seen a statically-resolved
+ * `import.meta.env.PUBLIC_X` read for it, which is also precisely the
+ * condition under which Gate B allows its value to be inlined at all — an
+ * unread key that somehow leaked in anyway is a Gate B `generateBundle`
+ * BUILD FAILURE (see `gate-b-secrets.ts`), never silently listed here.
+ */
+declare function buildPublicEnvManifest(tracker: PublicEnvTracker): PublicEnvManifestEntry[];
+interface GateCOptions extends EnvironmentClassifierOptions {
+  /**
+   * Shared with `gateBSecrets({ tracker })` — required for the manifest to
+   * reflect what THIS build's Gate B pass actually saw. Defaults to a
+   * private, unshared tracker (always empty) if omitted, which is only ever
+   * correct when Gate C runs standalone in a test.
+   */
+  tracker?: PublicEnvTracker;
+  /** Defaults to `"warlock-env-manifest.json"` (Suki's suggested name). */
+  manifestFileName?: string;
+}
+/**
+ * The client-build Vite plugin. Runs only at `generateBundle` — Gate C has
+ * nothing to say about source, only about the bundle Rollup actually wrote.
+ * Skipped for the SSR/server build, same as Gate B (`gate-b-secrets.ts`):
+ * a page's server exports are meant to survive in that build; only the
+ * client build is judged.
+ */
+declare function gateCVerify(options?: GateCOptions): Plugin;
+//#endregion
+export { GateCOptions, PublicEnvManifestEntry, ServerExportLeak, ServerImportEdgeLeak, buildPublicEnvManifest, findLeakedServerExports, findLeakedServerImportEdges, gateCVerify };
+//# sourceMappingURL=gate-c-verify.d.mts.map

package/esm/vite/gate-c-verify.mjs

@@ -0,0 +1,263 @@
+import { createEnvironmentClassifier } from "./gate-a-resolve.mjs";
+import { createPublicEnvTracker } from "./gate-b-secrets.mjs";
+import { SERVER_EXPORT_NAMES } from "./projection.mjs";
+import { parse } from "@babel/parser";
+
+//#region ../web/src/vite/gate-c-verify.ts
+/**
+* Gate C — emitted-output verification.
+*
+* Projection removes the five server exports before the client graph forms.
+* Gate A refuses forbidden import PATHS. Gate B refuses inline secret reads.
+* All three act BEFORE or DURING the build, on source or the module graph —
+* none of them ever looks at what actually came out the other end. Gate C
+* is that check: a build-time assertion on the EMITTED client bundle for
+* every page, verifying:
+*
+*   1. The emitted code contains none of the five server export names
+*      (`route`, `middleware`, `validation`, `loader`, `metadata`) as a
+*      top-level binding, exported or not — `findLeakedServerExports`.
+*   2. The emitted module graph (Rollup's `OutputBundle`, as seen in
+*      `generateBundle`) contains no import edge into a
+*      `warlock.environment: "server"` (or absent-defaulting-to-server)
+*      package — re-derived from the exact classifier Gate A uses
+*      (`gate-a-resolve.ts`'s `createEnvironmentClassifier`), never a second,
+*      independently-drifting classification scheme — `findLeakedServerImportEdges`.
+*
+* This is defense in depth: if projection or Gate A has a bug that lets
+* something through, Gate C is what turns "shipped a leak" into "build
+* fails." Both check functions are exported as PURE functions over a bundle
+* object precisely so a test can construct a bundle where projection/Gate A
+* are bypassed entirely (a hand-built leaked chunk, never produced by a real
+* pipeline run) and still prove Gate C catches it independently — re-running
+* the D.1-D.5 happy-path fixtures through the composed pipeline only proves
+* the happy path, never that Gate C itself has teeth.
+*
+* Gate C also emits the inlined-`PUBLIC_*`-value manifest — see
+* `buildPublicEnvManifest` below — and is the only
+* one of the three gates that runs exclusively at `generateBundle` time: it
+* has nothing to say about source, only about output.
+*/
+/**
+* Recursively collects every top-level statement's bound name(s), matching:
+*   - `const route = ...` / `function loader() {}` (exported or not — the
+*     check is on top-level BINDINGS, not top-level exports).
+*   - `export const route = ...` / `export function loader() {}` (the
+*     `ExportNamedDeclaration` wrapper form).
+*   - `export { route }` (the bare re-export-specifier form Rollup sometimes
+*     emits instead of inlining the declaration itself).
+*/
+function collectServerExportNames(stmt) {
+	const matches = [];
+	const line = stmt.loc?.start?.line;
+	function record(name) {
+		if (name && SERVER_EXPORT_NAMES.has(name)) matches.push({
+			name,
+			line: line ?? 0
+		});
+	}
+	if (stmt.type === "VariableDeclaration") {
+		for (const decl of stmt.declarations) if (decl.id?.type === "Identifier") record(decl.id.name);
+	} else if (stmt.type === "FunctionDeclaration") record(stmt.id?.name);
+	else if (stmt.type === "ExportNamedDeclaration") {
+		if (stmt.declaration) matches.push(...collectServerExportNames(stmt.declaration));
+		for (const specifier of stmt.specifiers ?? []) record(specifier.exported?.name ?? specifier.exported?.value);
+	}
+	return matches;
+}
+/**
+* Thrown when an emitted chunk cannot be parsed, which means Gate C could not
+* inspect it. A gate that skips what it cannot read reports "no violation
+* found" on precisely the input it failed to look at — the one input where
+* that answer is worthless. So an unreadable chunk fails the build instead.
+*/
+var UnverifiableChunkError = class extends Error {
+	fileName;
+	constructor(fileName, cause) {
+		super([
+			`Warlock stopped this build: a file in your client bundle could not be checked for server-only code.`,
+			``,
+			`File: ${fileName}`,
+			`Cause: this file could not be parsed as JavaScript, so the client/server boundary check could not be performed on it. Warlock cannot confirm that the server-only exports (route, middleware, validation, loader, metadata) were kept out of it.`,
+			`Fix: the build is being stopped rather than passed, because a file that was never checked is not a file known to be safe. This emitted file is outside the JavaScript syntax Warlock can currently verify. Two things commonly put it there, and this error cannot tell which: the output uses syntax newer than the parser Warlock ships with, or a plugin or loader emitted non-standard syntax into the client bundle. Check the compatibility of whatever produced this file, then build again.`
+		].join("\n"));
+		this.name = "UnverifiableChunkError";
+		this.fileName = fileName;
+		if (cause !== void 0) this.cause = cause;
+	}
+};
+/**
+* Part 1, item 1: parses each emitted chunk's ACTUAL code (never pre-transform
+* source) and looks for a top-level binding named one of the five server
+* exports. A parse failure on an emitted chunk FAILS the gate
+* (`UnverifiableChunkError`) — it is never skipped. Skipping would report the
+* bundle clean on the one chunk the gate did not actually inspect, which is a
+* safety check failing open; a build stopped on an unreadable chunk is
+* recoverable, a boundary silently unenforced is not.
+*
+* This SURVIVES real minification (pinned by the `gate-c-verify.spec.ts`
+* "D.8" describe block). A minifier (esbuild,
+* Vite's default) is only free to rename LOCAL bindings; the exported name
+* itself is part of the module's public interface and is never mangled — a
+* minified `export const route = ...` still emits `export { e as route }`,
+* with the local identifier renamed (`e`) but `route` intact as the specifier's
+* `exported` name, which is exactly the field `collectServerExportNames`
+* reads for the `ExportNamedDeclaration` specifier form. No name-independent
+* redesign needed here — verified against a real `build.minify: true` output,
+* not assumed.
+*/
+function findLeakedServerExports(bundle) {
+	const leaks = [];
+	for (const file of Object.values(bundle)) {
+		if (!file || file.type !== "chunk" || typeof file.code !== "string") continue;
+		let ast;
+		try {
+			ast = parse(file.code, {
+				sourceType: "module",
+				plugins: ["typescript", "jsx"]
+			});
+		} catch (error) {
+			throw new UnverifiableChunkError(file.fileName ?? "(unnamed chunk)", error);
+		}
+		for (const stmt of ast.program.body) for (const match of collectServerExportNames(stmt)) leaks.push({
+			fileName: file.fileName,
+			exportName: match.name,
+			line: match.line
+		});
+	}
+	return leaks;
+}
+/**
+* Part 1, item 2: walks every emitted chunk's `moduleIds` (the resolved,
+* absolute file paths of every source module Rollup actually bundled into
+* that chunk) and classifies each one via the SAME `EnvironmentClassifier`
+* Gate A's `resolveId` uses, re-derived from `gate-a-resolve.ts` rather than
+* hand-rolled a second time. A moduleId that maps to a governed-scope
+* package classified `"server"` is an import edge Gate A should already
+* have refused — if it's here anyway, the earlier gate has a bug.
+*
+* D.8 verdict: this SURVIVES real minification unconditionally, and for a
+* stronger reason than item 1 above — it never reads emitted code text or
+* identifier names at all. `moduleIds` is Rollup's own bundling metadata
+* (which resolved source files ended up in this chunk), untouched by
+* minification, which only rewrites code, not that metadata. Verified
+* against a real `build.minify: true` output in `gate-c-verify.spec.ts`.
+*/
+function findLeakedServerImportEdges(bundle, classifier) {
+	const leaks = [];
+	for (const file of Object.values(bundle)) {
+		if (!file || file.type !== "chunk") continue;
+		for (const moduleId of file.moduleIds ?? []) {
+			const packageName = classifier.packageNameForFilePath(moduleId);
+			if (!packageName) continue;
+			if (classifier.environmentOf(packageName) === "server") leaks.push({
+				fileName: file.fileName,
+				moduleId,
+				packageName
+			});
+		}
+	}
+	return leaks;
+}
+/**
+* Conservative "does this PUBLIC_* value look safe to print in the reviewable
+* manifest" heuristic: if genuinely unsure, show the key only — never guess
+* that a value is safe. The whole point of this manifest is that the `PUBLIC_`
+* prefix rule alone is not trustworthy — someone can and will name an actual
+* secret `PUBLIC_STRIPE_KEY` — so a value that LOOKS like a credential is
+* redacted regardless of what its key is named. Non-string values (booleans,
+* numbers) are never secret-shaped and always shown.
+*/
+const CREDENTIALED_URL_RE = /:\/\/[^/\s]+:[^/\s@]+@/;
+const KNOWN_SECRET_PREFIX_RES = [
+	/^sk_(live|test)_/i,
+	/^rk_(live|test)_/i,
+	/^AKIA[0-9A-Z]{12,}/,
+	/^gh[pousr]_[A-Za-z0-9]{20,}/,
+	/^glpat-[A-Za-z0-9_-]{20,}/,
+	/^xox[baprs]-[A-Za-z0-9-]{10,}/,
+	/^eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/
+];
+const HIGH_ENTROPY_TOKEN_RE = /^[A-Za-z0-9+/_=-]{32,}$/;
+function isSafeToShowValue(value) {
+	if (typeof value !== "string" || value.length === 0) return true;
+	if (CREDENTIALED_URL_RE.test(value)) return false;
+	if (KNOWN_SECRET_PREFIX_RES.some((re) => re.test(value))) return false;
+	if (HIGH_ENTROPY_TOKEN_RE.test(value) && /[0-9]/.test(value) && /[a-zA-Z]/.test(value)) return false;
+	return true;
+}
+function stringifyEnvValue(value) {
+	if (typeof value === "string") return value;
+	return JSON.stringify(value) ?? "undefined";
+}
+/**
+* The enumerated, human-reviewable list of
+* every `PUBLIC_*` key actually inlined into the client bundle. Built
+* directly from `tracker.referencedKeys` — the exact same `Set` Gate B's own
+* `generateBundle` unread-key check (`gate-b-secrets.ts`) reads from — so
+* this manifest and that exclusion logic agree BY CONSTRUCTION: they are two
+* readers of one Set, not two independent recomputations of "which keys were
+* read" that could drift apart. A key only reaches `referencedKeys` once
+* `findViolation` in `gate-b-secrets.ts` has seen a statically-resolved
+* `import.meta.env.PUBLIC_X` read for it, which is also precisely the
+* condition under which Gate B allows its value to be inlined at all — an
+* unread key that somehow leaked in anyway is a Gate B `generateBundle`
+* BUILD FAILURE (see `gate-b-secrets.ts`), never silently listed here.
+*/
+function buildPublicEnvManifest(tracker) {
+	return [...tracker.referencedKeys].sort().map((key) => {
+		const value = tracker.declaredEnv[key];
+		const safe = isSafeToShowValue(value);
+		return {
+			key,
+			value: safe ? stringifyEnvValue(value) : null,
+			redacted: !safe
+		};
+	});
+}
+/**
+* The client-build Vite plugin. Runs only at `generateBundle` — Gate C has
+* nothing to say about source, only about the bundle Rollup actually wrote.
+* Skipped for the SSR/server build, same as Gate B (`gate-b-secrets.ts`):
+* a page's server exports are meant to survive in that build; only the
+* client build is judged.
+*/
+function gateCVerify(options = {}) {
+	const classifier = createEnvironmentClassifier(options);
+	const tracker = options.tracker ?? createPublicEnvTracker();
+	const manifestFileName = options.manifestFileName ?? "warlock-env-manifest.json";
+	return {
+		name: "warlock:gate-c-verify",
+		generateBundle(_outputOptions, bundle) {
+			if (this.environment?.config?.consumer === "server") return;
+			const exportLeak = findLeakedServerExports(bundle)[0];
+			if (exportLeak) this.error([
+				`Gate C refused a build: a server export survived into the emitted client bundle.`,
+				``,
+				`File: ${exportLeak.fileName}${exportLeak.line ? `:${exportLeak.line}` : ""}`,
+				`Export: ${exportLeak.exportName}`,
+				`Cause: "${exportLeak.exportName}" is one of the five server exports (route, middleware, validation, loader, metadata) and is still present as a top-level binding in the EMITTED client chunk — projection and/or Gate A should have removed or refused it before the bundle was written.`,
+				`Fix: this should already be impossible if projection and Gate A ran correctly — investigate why "${exportLeak.exportName}" reached the emitted output (a projection bug, a build config that bypasses these plugins, or a plugin ordering change) rather than assuming this build is a one-off; Gate C is defense in depth, not the primary fence.`
+			].join("\n"));
+			const importEdgeLeak = findLeakedServerImportEdges(bundle, classifier)[0];
+			if (importEdgeLeak) this.error([
+				`Gate C refused a build: a server-only import edge survived into the emitted client bundle's module graph.`,
+				``,
+				`File: ${importEdgeLeak.fileName}`,
+				`Module: ${importEdgeLeak.moduleId}`,
+				`Cause: "${importEdgeLeak.moduleId}" belongs to ${importEdgeLeak.packageName}, a server-only package (it declares "warlock": { "environment": "server" } in its package.json), and is present among the bundled modules of the emitted client chunk "${importEdgeLeak.fileName}" — Gate A's resolveId should have refused this import before it ever reached the bundle.`,
+				`Fix: this should already be impossible if Gate A ran on this build — investigate why ${importEdgeLeak.packageName} reached the emitted output (a Gate A bypass, a custom resolveId/external override, or a plugin ordering change) rather than assuming this build is a one-off; Gate C is defense in depth, not the primary fence.`
+			].join("\n"));
+			const manifest = buildPublicEnvManifest(tracker);
+			this.emitFile({
+				type: "asset",
+				fileName: manifestFileName,
+				source: JSON.stringify(manifest, null, 2)
+			});
+		}
+	};
+}
+
+//#endregion
+export { buildPublicEnvManifest, findLeakedServerExports, findLeakedServerImportEdges, gateCVerify };
+//# sourceMappingURL=gate-c-verify.mjs.map

package/esm/vite/gate-c-verify.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate-c-verify.mjs","names":[],"sources":["../../../../../../../web/src/vite/gate-c-verify.ts"],"sourcesContent":["/**\r\n * Gate C — emitted-output verification.\r\n *\r\n * Projection removes the five server exports before the client graph forms.\r\n * Gate A refuses forbidden import PATHS. Gate B refuses inline secret reads.\r\n * All three act BEFORE or DURING the build, on source or the module graph —\r\n * none of them ever looks at what actually came out the other end. Gate C\r\n * is that check: a build-time assertion on the EMITTED client bundle for\r\n * every page, verifying:\r\n *\r\n *   1. The emitted code contains none of the five server export names\r\n *      (`route`, `middleware`, `validation`, `loader`, `metadata`) as a\r\n *      top-level binding, exported or not — `findLeakedServerExports`.\r\n *   2. The emitted module graph (Rollup's `OutputBundle`, as seen in\r\n *      `generateBundle`) contains no import edge into a\r\n *      `warlock.environment: \"server\"` (or absent-defaulting-to-server)\r\n *      package — re-derived from the exact classifier Gate A uses\r\n *      (`gate-a-resolve.ts`'s `createEnvironmentClassifier`), never a second,\r\n *      independently-drifting classification scheme — `findLeakedServerImportEdges`.\r\n *\r\n * This is defense in depth: if projection or Gate A has a bug that lets\r\n * something through, Gate C is what turns \"shipped a leak\" into \"build\r\n * fails.\" Both check functions are exported as PURE functions over a bundle\r\n * object precisely so a test can construct a bundle where projection/Gate A\r\n * are bypassed entirely (a hand-built leaked chunk, never produced by a real\r\n * pipeline run) and still prove Gate C catches it independently — re-running\r\n * the D.1-D.5 happy-path fixtures through the composed pipeline only proves\r\n * the happy path, never that Gate C itself has teeth.\r\n *\r\n * Gate C also emits the inlined-`PUBLIC_*`-value manifest — see\r\n * `buildPublicEnvManifest` below — and is the only\r\n * one of the three gates that runs exclusively at `generateBundle` time: it\r\n * has nothing to say about source, only about output.\r\n */\r\nimport { parse } from \"@babel/parser\";\r\nimport type { Plugin } from \"vite\";\r\nimport {\r\n  createEnvironmentClassifier,\r\n  type EnvironmentClassifier,\r\n  type EnvironmentClassifierOptions,\r\n} from \"./gate-a-resolve\";\r\nimport { createPublicEnvTracker, type PublicEnvTracker } from \"./gate-b-secrets\";\r\nimport { SERVER_EXPORT_NAMES } from \"./projection\";\r\n\r\nexport interface ServerExportLeak {\r\n  fileName: string;\r\n  exportName: string;\r\n  line?: number;\r\n}\r\n\r\nexport interface ServerImportEdgeLeak {\r\n  fileName: string;\r\n  moduleId: string;\r\n  packageName: string;\r\n}\r\n\r\nexport interface PublicEnvManifestEntry {\r\n  key: string;\r\n  /** `null` when `redacted` is true — see `isSafeToShowValue`. */\r\n  value: string | null;\r\n  redacted: boolean;\r\n}\r\n\r\n/**\r\n * A structurally-minimal view of Rollup's `OutputBundle` — only the fields\r\n * Gate C actually reads. Deliberately NOT the real `OutputBundle`/`OutputChunk`\r\n * types: Part 1's own discipline requires proving Gate C catches a bundle\r\n * that a real pipeline could never produce (a hand-built leaked chunk), and\r\n * forcing every test fixture to satisfy Rollup's full chunk shape would\r\n * fight that requirement for no safety benefit — Vite's real `generateBundle`\r\n * hook still hands Gate C a real `OutputBundle`, which is a structural\r\n * superset of this.\r\n */\r\ntype BundleLike = Record<\r\n  string,\r\n  {\r\n    type?: string;\r\n    fileName?: string;\r\n    code?: string;\r\n    moduleIds?: readonly string[];\r\n  }\r\n>;\r\n\r\n/**\r\n * Recursively collects every top-level statement's bound name(s), matching:\r\n *   - `const route = ...` / `function loader() {}` (exported or not — the\r\n *     check is on top-level BINDINGS, not top-level exports).\r\n *   - `export const route = ...` / `export function loader() {}` (the\r\n *     `ExportNamedDeclaration` wrapper form).\r\n *   - `export { route }` (the bare re-export-specifier form Rollup sometimes\r\n *     emits instead of inlining the declaration itself).\r\n */\r\nfunction collectServerExportNames(stmt: any): Array<{ name: string; line: number }> {\r\n  const matches: Array<{ name: string; line: number }> = [];\r\n  const line = stmt.loc?.start?.line as number | undefined;\r\n\r\n  function record(name: string | undefined) {\r\n    if (name && SERVER_EXPORT_NAMES.has(name)) matches.push({ name, line: line ?? 0 });\r\n  }\r\n\r\n  if (stmt.type === \"VariableDeclaration\") {\r\n    for (const decl of stmt.declarations) {\r\n      if (decl.id?.type === \"Identifier\") record(decl.id.name);\r\n    }\r\n  } else if (stmt.type === \"FunctionDeclaration\") {\r\n    record(stmt.id?.name);\r\n  } else if (stmt.type === \"ExportNamedDeclaration\") {\r\n    if (stmt.declaration) matches.push(...collectServerExportNames(stmt.declaration));\r\n    for (const specifier of stmt.specifiers ?? []) {\r\n      record(specifier.exported?.name ?? specifier.exported?.value);\r\n    }\r\n  }\r\n\r\n  return matches;\r\n}\r\n\r\n/**\r\n * Thrown when an emitted chunk cannot be parsed, which means Gate C could not\r\n * inspect it. A gate that skips what it cannot read reports \"no violation\r\n * found\" on precisely the input it failed to look at — the one input where\r\n * that answer is worthless. So an unreadable chunk fails the build instead.\r\n */\r\nexport class UnverifiableChunkError extends Error {\r\n  readonly fileName: string;\r\n\r\n  constructor(fileName: string, cause?: unknown) {\r\n    super(\r\n      [\r\n        `Warlock stopped this build: a file in your client bundle could not be checked for server-only code.`,\r\n        ``,\r\n        `File: ${fileName}`,\r\n        `Cause: this file could not be parsed as JavaScript, so the client/server boundary check could not be performed on it. Warlock cannot confirm that the server-only exports (route, middleware, validation, loader, metadata) were kept out of it.`,\r\n        `Fix: the build is being stopped rather than passed, because a file that was never checked is not a file known to be safe. This emitted file is outside the JavaScript syntax Warlock can currently verify. Two things commonly put it there, and this error cannot tell which: the output uses syntax newer than the parser Warlock ships with, or a plugin or loader emitted non-standard syntax into the client bundle. Check the compatibility of whatever produced this file, then build again.`,\r\n      ].join(\"\\n\"),\r\n    );\r\n    this.name = \"UnverifiableChunkError\";\r\n    this.fileName = fileName;\r\n    if (cause !== undefined) (this as { cause?: unknown }).cause = cause;\r\n  }\r\n}\r\n\r\n/**\r\n * Part 1, item 1: parses each emitted chunk's ACTUAL code (never pre-transform\r\n * source) and looks for a top-level binding named one of the five server\r\n * exports. A parse failure on an emitted chunk FAILS the gate\r\n * (`UnverifiableChunkError`) — it is never skipped. Skipping would report the\r\n * bundle clean on the one chunk the gate did not actually inspect, which is a\r\n * safety check failing open; a build stopped on an unreadable chunk is\r\n * recoverable, a boundary silently unenforced is not.\r\n *\r\n * This SURVIVES real minification (pinned by the `gate-c-verify.spec.ts`\r\n * \"D.8\" describe block). A minifier (esbuild,\r\n * Vite's default) is only free to rename LOCAL bindings; the exported name\r\n * itself is part of the module's public interface and is never mangled — a\r\n * minified `export const route = ...` still emits `export { e as route }`,\r\n * with the local identifier renamed (`e`) but `route` intact as the specifier's\r\n * `exported` name, which is exactly the field `collectServerExportNames`\r\n * reads for the `ExportNamedDeclaration` specifier form. No name-independent\r\n * redesign needed here — verified against a real `build.minify: true` output,\r\n * not assumed.\r\n */\r\nexport function findLeakedServerExports(bundle: BundleLike): ServerExportLeak[] {\r\n  const leaks: ServerExportLeak[] = [];\r\n\r\n  for (const file of Object.values(bundle)) {\r\n    if (!file || file.type !== \"chunk\" || typeof file.code !== \"string\") continue;\r\n\r\n    let ast: any;\r\n    try {\r\n      ast = parse(file.code, { sourceType: \"module\", plugins: [\"typescript\", \"jsx\"] });\r\n    } catch (error) {\r\n      throw new UnverifiableChunkError(file.fileName ?? \"(unnamed chunk)\", error);\r\n    }\r\n\r\n    for (const stmt of ast.program.body as any[]) {\r\n      for (const match of collectServerExportNames(stmt)) {\r\n        leaks.push({ fileName: file.fileName as string, exportName: match.name, line: match.line });\r\n      }\r\n    }\r\n  }\r\n\r\n  return leaks;\r\n}\r\n\r\n/**\r\n * Part 1, item 2: walks every emitted chunk's `moduleIds` (the resolved,\r\n * absolute file paths of every source module Rollup actually bundled into\r\n * that chunk) and classifies each one via the SAME `EnvironmentClassifier`\r\n * Gate A's `resolveId` uses, re-derived from `gate-a-resolve.ts` rather than\r\n * hand-rolled a second time. A moduleId that maps to a governed-scope\r\n * package classified `\"server\"` is an import edge Gate A should already\r\n * have refused — if it's here anyway, the earlier gate has a bug.\r\n *\r\n * D.8 verdict: this SURVIVES real minification unconditionally, and for a\r\n * stronger reason than item 1 above — it never reads emitted code text or\r\n * identifier names at all. `moduleIds` is Rollup's own bundling metadata\r\n * (which resolved source files ended up in this chunk), untouched by\r\n * minification, which only rewrites code, not that metadata. Verified\r\n * against a real `build.minify: true` output in `gate-c-verify.spec.ts`.\r\n */\r\nexport function findLeakedServerImportEdges(\r\n  bundle: BundleLike,\r\n  classifier: Pick<EnvironmentClassifier, \"environmentOf\" | \"packageNameForFilePath\">,\r\n): ServerImportEdgeLeak[] {\r\n  const leaks: ServerImportEdgeLeak[] = [];\r\n\r\n  for (const file of Object.values(bundle)) {\r\n    if (!file || file.type !== \"chunk\") continue;\r\n\r\n    for (const moduleId of file.moduleIds ?? []) {\r\n      const packageName = classifier.packageNameForFilePath(moduleId);\r\n      if (!packageName) continue;\r\n      if (classifier.environmentOf(packageName) === \"server\") {\r\n        leaks.push({ fileName: file.fileName as string, moduleId, packageName });\r\n      }\r\n    }\r\n  }\r\n\r\n  return leaks;\r\n}\r\n\r\n/**\r\n * Conservative \"does this PUBLIC_* value look safe to print in the reviewable\r\n * manifest\" heuristic: if genuinely unsure, show the key only — never guess\r\n * that a value is safe. The whole point of this manifest is that the `PUBLIC_`\r\n * prefix rule alone is not trustworthy — someone can and will name an actual\r\n * secret `PUBLIC_STRIPE_KEY` — so a value that LOOKS like a credential is\r\n * redacted regardless of what its key is named. Non-string values (booleans,\r\n * numbers) are never secret-shaped and always shown.\r\n */\r\nconst CREDENTIALED_URL_RE = /:\\/\\/[^/\\s]+:[^/\\s@]+@/; // scheme://user:pass@host\r\nconst KNOWN_SECRET_PREFIX_RES = [\r\n  /^sk_(live|test)_/i, // Stripe secret key (pk_ publishable is a different prefix)\r\n  /^rk_(live|test)_/i, // Stripe restricted key\r\n  /^AKIA[0-9A-Z]{12,}/, // AWS access key id\r\n  /^gh[pousr]_[A-Za-z0-9]{20,}/, // GitHub personal/OAuth/user/server tokens\r\n  /^glpat-[A-Za-z0-9_-]{20,}/, // GitLab personal access token\r\n  /^xox[baprs]-[A-Za-z0-9-]{10,}/, // Slack tokens\r\n  /^eyJ[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$/, // JWT (3 base64url segments)\r\n];\r\n// A long opaque token made up only of base64url/hex-ish characters, with both\r\n// letters and digits, and no separators a human-authored public value (a\r\n// URL, a short id) would normally contain — conservatively treated as a\r\n// secret-shaped random token even though it might genuinely be safe.\r\nconst HIGH_ENTROPY_TOKEN_RE = /^[A-Za-z0-9+/_=-]{32,}$/;\r\n\r\nfunction isSafeToShowValue(value: unknown): boolean {\r\n  if (typeof value !== \"string\" || value.length === 0) return true;\r\n  if (CREDENTIALED_URL_RE.test(value)) return false;\r\n  if (KNOWN_SECRET_PREFIX_RES.some((re) => re.test(value))) return false;\r\n  if (HIGH_ENTROPY_TOKEN_RE.test(value) && /[0-9]/.test(value) && /[a-zA-Z]/.test(value)) return false;\r\n  return true;\r\n}\r\n\r\nfunction stringifyEnvValue(value: unknown): string {\r\n  if (typeof value === \"string\") return value;\r\n  return JSON.stringify(value) ?? \"undefined\";\r\n}\r\n\r\n/**\r\n * The enumerated, human-reviewable list of\r\n * every `PUBLIC_*` key actually inlined into the client bundle. Built\r\n * directly from `tracker.referencedKeys` — the exact same `Set` Gate B's own\r\n * `generateBundle` unread-key check (`gate-b-secrets.ts`) reads from — so\r\n * this manifest and that exclusion logic agree BY CONSTRUCTION: they are two\r\n * readers of one Set, not two independent recomputations of \"which keys were\r\n * read\" that could drift apart. A key only reaches `referencedKeys` once\r\n * `findViolation` in `gate-b-secrets.ts` has seen a statically-resolved\r\n * `import.meta.env.PUBLIC_X` read for it, which is also precisely the\r\n * condition under which Gate B allows its value to be inlined at all — an\r\n * unread key that somehow leaked in anyway is a Gate B `generateBundle`\r\n * BUILD FAILURE (see `gate-b-secrets.ts`), never silently listed here.\r\n */\r\nexport function buildPublicEnvManifest(tracker: PublicEnvTracker): PublicEnvManifestEntry[] {\r\n  return [...tracker.referencedKeys]\r\n    .sort()\r\n    .map((key) => {\r\n      const value = tracker.declaredEnv[key];\r\n      const safe = isSafeToShowValue(value);\r\n      return { key, value: safe ? stringifyEnvValue(value) : null, redacted: !safe };\r\n    });\r\n}\r\n\r\nexport interface GateCOptions extends EnvironmentClassifierOptions {\r\n  /**\r\n   * Shared with `gateBSecrets({ tracker })` — required for the manifest to\r\n   * reflect what THIS build's Gate B pass actually saw. Defaults to a\r\n   * private, unshared tracker (always empty) if omitted, which is only ever\r\n   * correct when Gate C runs standalone in a test.\r\n   */\r\n  tracker?: PublicEnvTracker;\r\n  /** Defaults to `\"warlock-env-manifest.json\"` (Suki's suggested name). */\r\n  manifestFileName?: string;\r\n}\r\n\r\n/**\r\n * The client-build Vite plugin. Runs only at `generateBundle` — Gate C has\r\n * nothing to say about source, only about the bundle Rollup actually wrote.\r\n * Skipped for the SSR/server build, same as Gate B (`gate-b-secrets.ts`):\r\n * a page's server exports are meant to survive in that build; only the\r\n * client build is judged.\r\n */\r\nexport function gateCVerify(options: GateCOptions = {}): Plugin {\r\n  const classifier = createEnvironmentClassifier(options);\r\n  const tracker = options.tracker ?? createPublicEnvTracker();\r\n  const manifestFileName = options.manifestFileName ?? \"warlock-env-manifest.json\";\r\n\r\n  return {\r\n    name: \"warlock:gate-c-verify\",\r\n    generateBundle(_outputOptions, bundle) {\r\n      if (this.environment?.config?.consumer === \"server\") return;\r\n\r\n      const exportLeak = findLeakedServerExports(bundle)[0];\r\n      if (exportLeak) {\r\n        this.error(\r\n          [\r\n            `Gate C refused a build: a server export survived into the emitted client bundle.`,\r\n            ``,\r\n            `File: ${exportLeak.fileName}${exportLeak.line ? `:${exportLeak.line}` : \"\"}`,\r\n            `Export: ${exportLeak.exportName}`,\r\n            `Cause: \"${exportLeak.exportName}\" is one of the five server exports (route, middleware, validation, loader, metadata) and is still present as a top-level binding in the EMITTED client chunk — projection and/or Gate A should have removed or refused it before the bundle was written.`,\r\n            `Fix: this should already be impossible if projection and Gate A ran correctly — investigate why \"${exportLeak.exportName}\" reached the emitted output (a projection bug, a build config that bypasses these plugins, or a plugin ordering change) rather than assuming this build is a one-off; Gate C is defense in depth, not the primary fence.`,\r\n          ].join(\"\\n\"),\r\n        );\r\n      }\r\n\r\n      const importEdgeLeak = findLeakedServerImportEdges(bundle, classifier)[0];\r\n      if (importEdgeLeak) {\r\n        this.error(\r\n          [\r\n            `Gate C refused a build: a server-only import edge survived into the emitted client bundle's module graph.`,\r\n            ``,\r\n            `File: ${importEdgeLeak.fileName}`,\r\n            `Module: ${importEdgeLeak.moduleId}`,\r\n            `Cause: \"${importEdgeLeak.moduleId}\" belongs to ${importEdgeLeak.packageName}, a server-only package (it declares \"warlock\": { \"environment\": \"server\" } in its package.json), and is present among the bundled modules of the emitted client chunk \"${importEdgeLeak.fileName}\" — Gate A's resolveId should have refused this import before it ever reached the bundle.`,\r\n            `Fix: this should already be impossible if Gate A ran on this build — investigate why ${importEdgeLeak.packageName} reached the emitted output (a Gate A bypass, a custom resolveId/external override, or a plugin ordering change) rather than assuming this build is a one-off; Gate C is defense in depth, not the primary fence.`,\r\n          ].join(\"\\n\"),\r\n        );\r\n      }\r\n\r\n      const manifest = buildPublicEnvManifest(tracker);\r\n\r\n      // EMITTED through `this.emitFile`, not written into `bundle` by hand.\r\n      //\r\n      // This used to assign a hand-built record directly:\r\n      //\r\n      //     bundle[manifestFileName] = { type: \"asset\", fileName, name, source } as any;\r\n      //\r\n      // and the `as any` was load-bearing, which was the warning sign. A Rollup\r\n      // asset record carries `names` and `originalFileNames` ARRAYS; that object\r\n      // had neither, so it was not the shape Rollup produces — it merely\r\n      // type-asserted its way into the bundle.\r\n      //\r\n      // Nothing noticed until the production build got far enough to render\r\n      // chunks, at which point Vite's own `vite:manifest` plugin read\r\n      // `chunk.names.length` on every asset and died on `undefined`:\r\n      //\r\n      //     [vite:manifest] Cannot read properties of undefined (reading 'length')\r\n      //\r\n      // `emitFile` makes Rollup construct the record, so the shape is correct by\r\n      // construction and stays correct when Rollup adds fields. Hand-building a\r\n      // bundle entry is signing up to track someone else's internal type forever.\r\n      this.emitFile({\r\n        type: \"asset\",\r\n        fileName: manifestFileName,\r\n        source: JSON.stringify(manifest, null, 2),\r\n      });\r\n    },\r\n  };\r\n}\r\n"],"mappings":"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"}

package/esm/vite/hydration-entries.d.mts

@@ -0,0 +1,17 @@
+//#region ../web/src/vite/hydration-entries.d.ts
+/** Stable Rollup/Vite entry name shared by development and production wiring. */
+declare const HYDRATION_CLIENT_ENTRY_NAME = "hydration";
+type HydrationClientEntry = Readonly<{
+  name: typeof HYDRATION_CLIENT_ENTRY_NAME;
+  sourcePath: string;
+  devUrl: string;
+}>;
+/**
+ * Describes the single framework hydration entry without importing Vite.
+ * Vite's `/@fs/` prefix accepts an absolute normalized file-system path;
+ * keeping the drive colon produces `/@fs/D:/...` consistently on Windows.
+ */
+declare function createHydrationClientEntry(webRoot: string): HydrationClientEntry;
+//#endregion
+export { HYDRATION_CLIENT_ENTRY_NAME, HydrationClientEntry, createHydrationClientEntry };
+//# sourceMappingURL=hydration-entries.d.mts.map

package/esm/vite/hydration-entries.mjs

@@ -0,0 +1,45 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+
+//#region ../web/src/vite/hydration-entries.ts
+/** Stable Rollup/Vite entry name shared by development and production wiring. */
+const HYDRATION_CLIENT_ENTRY_NAME = "hydration";
+function normalizeFileSystemPath(filePath) {
+	return filePath.replace(/\\/g, "/");
+}
+/**
+* Where the hydration entry lives inside an INSTALLED `@warlock.js/web`, and
+* where it lives inside this checkout — in that order of preference.
+*
+* The published package declares `"files": ["esm"]`, so `src/` is absent from
+* every real install. Resolving the entry to `<webRoot>/src/hydration/index.ts`
+* unconditionally therefore worked in this monorepo and failed for every
+* consumer, with `warlock build` unable to emit a client bundle at all.
+*
+* The built artifact is preferred rather than the source being published,
+* because shipping `src/` beside `esm/` would put TWO instances of
+* `routing/route-table` in one client bundle — the app's own imports resolve
+* through `esm/`, the hydration entry's relative imports through `src/`.
+* `publishRouteTable()` would write to one and `<Link>` would read the other.
+*/
+const PACKAGED_ENTRY = "esm/hydration/index.mjs";
+const CHECKOUT_ENTRY = "src/hydration/index.ts";
+/**
+* Describes the single framework hydration entry without importing Vite.
+* Vite's `/@fs/` prefix accepts an absolute normalized file-system path;
+* keeping the drive colon produces `/@fs/D:/...` consistently on Windows.
+*/
+function createHydrationClientEntry(webRoot) {
+	if (typeof webRoot !== "string" || webRoot.trim().length === 0) throw new TypeError("Cannot create the hydration client entry: webRoot must be a non-empty path.");
+	const packagedPath = path.resolve(webRoot, PACKAGED_ENTRY);
+	const sourcePath = normalizeFileSystemPath(existsSync(packagedPath) ? packagedPath : path.resolve(webRoot, CHECKOUT_ENTRY));
+	return {
+		name: HYDRATION_CLIENT_ENTRY_NAME,
+		sourcePath,
+		devUrl: `/@fs/${sourcePath}`
+	};
+}
+
+//#endregion
+export { HYDRATION_CLIENT_ENTRY_NAME, createHydrationClientEntry };
+//# sourceMappingURL=hydration-entries.mjs.map

package/esm/vite/hydration-entries.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"hydration-entries.mjs","names":[],"sources":["../../../../../../../web/src/vite/hydration-entries.ts"],"sourcesContent":["import { existsSync } from \"node:fs\";\nimport path from \"node:path\";\n\n/** Stable Rollup/Vite entry name shared by development and production wiring. */\nexport const HYDRATION_CLIENT_ENTRY_NAME = \"hydration\";\n\nexport type HydrationClientEntry = Readonly<{\n  name: typeof HYDRATION_CLIENT_ENTRY_NAME;\n  sourcePath: string;\n  devUrl: string;\n}>;\n\nfunction normalizeFileSystemPath(filePath: string): string {\n  return filePath.replace(/\\\\/g, \"/\");\n}\n\n/**\n * Where the hydration entry lives inside an INSTALLED `@warlock.js/web`, and\n * where it lives inside this checkout — in that order of preference.\n *\n * The published package declares `\"files\": [\"esm\"]`, so `src/` is absent from\n * every real install. Resolving the entry to `<webRoot>/src/hydration/index.ts`\n * unconditionally therefore worked in this monorepo and failed for every\n * consumer, with `warlock build` unable to emit a client bundle at all.\n *\n * The built artifact is preferred rather than the source being published,\n * because shipping `src/` beside `esm/` would put TWO instances of\n * `routing/route-table` in one client bundle — the app's own imports resolve\n * through `esm/`, the hydration entry's relative imports through `src/`.\n * `publishRouteTable()` would write to one and `<Link>` would read the other.\n */\nconst PACKAGED_ENTRY = \"esm/hydration/index.mjs\";\nconst CHECKOUT_ENTRY = \"src/hydration/index.ts\";\n\n/**\n * Describes the single framework hydration entry without importing Vite.\n * Vite's `/@fs/` prefix accepts an absolute normalized file-system path;\n * keeping the drive colon produces `/@fs/D:/...` consistently on Windows.\n */\nexport function createHydrationClientEntry(webRoot: string): HydrationClientEntry {\n  if (typeof webRoot !== \"string\" || webRoot.trim().length === 0) {\n    throw new TypeError(\"Cannot create the hydration client entry: webRoot must be a non-empty path.\");\n  }\n\n  const packagedPath = path.resolve(webRoot, PACKAGED_ENTRY);\n  const sourcePath = normalizeFileSystemPath(\n    existsSync(packagedPath) ? packagedPath : path.resolve(webRoot, CHECKOUT_ENTRY),\n  );\n\n  return {\n    name: HYDRATION_CLIENT_ENTRY_NAME,\n    sourcePath,\n    devUrl: `/@fs/${sourcePath}`,\n  };\n}\n"],"mappings":";;;;;AAIA,MAAa,8BAA8B;AAQ3C,SAAS,wBAAwB,UAA0B;CACzD,OAAO,SAAS,QAAQ,OAAO,GAAG;AACpC;;;;;;;;;;;;;;;;AAiBA,MAAM,iBAAiB;AACvB,MAAM,iBAAiB;;;;;;AAOvB,SAAgB,2BAA2B,SAAuC;CAChF,IAAI,OAAO,YAAY,YAAY,QAAQ,KAAK,CAAC,CAAC,WAAW,GAC3D,MAAM,IAAI,UAAU,6EAA6E;CAGnG,MAAM,eAAe,KAAK,QAAQ,SAAS,cAAc;CACzD,MAAM,aAAa,wBACjB,WAAW,YAAY,IAAI,eAAe,KAAK,QAAQ,SAAS,cAAc,CAChF;CAEA,OAAO;EACL,MAAM;EACN;EACA,QAAQ,QAAQ;CAClB;AACF"}

package/esm/vite/index.d.mts

@@ -0,0 +1,126 @@
+import { HYDRATION_CLIENT_ENTRY_NAME, HydrationClientEntry, createHydrationClientEntry } from "./hydration-entries.mjs";
+import { BuildHydrationClientOptions, BuildHydrationClientResult, HydrationClientBuildOutput, buildHydrationClient } from "./build-client.mjs";
+import { EnvironmentClassifier, EnvironmentClassifierOptions, WarlockEnvironment, gateAResolve } from "./gate-a-resolve.mjs";
+import { PublicEnvTracker, createPublicEnvTracker, gateBSecrets } from "./gate-b-secrets.mjs";
+import { GateCOptions, PublicEnvManifestEntry, ServerExportLeak, ServerImportEdgeLeak, buildPublicEnvManifest, findLeakedServerExports, findLeakedServerImportEdges, gateCVerify } from "./gate-c-verify.mjs";
+import { CLIENT_PAGE_REGISTRY_ID, ClientPageRegistryPluginOptions, RESOLVED_CLIENT_PAGE_REGISTRY_ID, clientPageRegistry } from "./page-registry-plugin.mjs";
+import { ProjectionAmbiguityError, ProjectionResult, projection } from "./projection.mjs";
+import { Plugin } from "vite";
+
+//#region ../web/src/vite/index.d.ts
+type WarlockClientBoundaryOptions = Parameters<typeof gateAResolve>[0];
+type BuildWarlockHydrationClientOptions = Readonly<{
+  appRoot: string;
+  webRoot: string; /** Absolute client output dir — threaded to `buildHydrationClient` (`<outdir>/client`). */
+  outDir: string;
+  resolveAliases: BuildHydrationClientOptions["resolveAliases"];
+  external?: BuildHydrationClientOptions["external"];
+}>;
+/**
+ * The composed client-build pipeline: projection
+ * strips the 5 server exports first, THEN Gate B's `transform` checks
+ * whatever source remains for inline secret reads, THEN Gate A's
+ * `resolveId` judges whatever imports remain. Array order here is
+ * `[projection(), gateBSecrets(), gateAResolve()]` to match Vite's own
+ * pipeline shape (`transform` before `resolveId`), but array order alone
+ * does not guarantee this — see the hook-ordering fact below, which is what
+ * actually makes the composition correct.
+ *
+ * Empirically observed fact (via an instrumented real `vite.build()`, not
+ * assumed from plugin array order): for a given module M, Vite/Rollup calls
+ * `transform(M)` BEFORE it calls `resolveId` for any of M's own import
+ * specifiers — because Rollup must parse M's post-transform source to even
+ * discover which specifiers to resolve next. Concretely: `transform` ran on
+ * `entry.page.tsx` first, and only after that did `resolveId("./dep", ...)`
+ * fire for the import statement still present in the transformed code. A
+ * consequence follows directly: if projection's `transform` removes an
+ * import statement from a page module entirely (e.g. `loader`'s
+ * `@warlock.js/core` import, stripped because `loader` itself is removed),
+ * `resolveId` is never invoked for that specifier at all — Gate A doesn't
+ * "let it pass", it never sees it. Gate A's `resolveId` only fires for
+ * imports that survive projection's `transform`, which is exactly why a
+ * component-level `@warlock.js/core` import (never touched by projection)
+ * still reaches and is refused by Gate A.
+ *
+ * This is OBSERVED Rollup behavior, not a documented contract — a future
+ * Vite/Rollup upgrade could invert it. Pinned by a
+ * regression test (`index.spec.ts`, "D.3 hook ordering pin") that fails
+ * loudly if the ordering ever inverts, and by the `vite` peer floor in
+ * `web/package.json` (`>=7.3.5`, the version this was verified against). If
+ * that test ever fails after a Vite bump: the failure mode of the ordering
+ * assumption breaking is SAFE — projection would stop removing an import
+ * statement Gate A still sees, so Gate A would refuse an import it used to
+ * silently let a stripped server export take with it. That is a loud build
+ * failure ("Gate A refused an import"), never a silent client-bundle leak.
+ * Do NOT "fix" an apparent Gate A false-positive after a Vite upgrade by
+ * weakening Gate A (e.g. widening what it lets through) — investigate
+ * whether this ordering assumption broke instead; loosening Gate A to work
+ * around it would turn a loud failure into the exact silent leak this
+ * pipeline exists to prevent.
+ *
+ * Gate B is placed between the two for the same reason, but for a `transform`
+ * hook rather than `resolveId`: within a plugin array, Rollup runs each
+ * module's registered `transform` hooks in array order, each one receiving
+ * the PREVIOUS plugin's output. Running Gate B after projection means it
+ * inspects the POST-projection source — a `process.env.SECRET` read inside
+ * `loader` (a server export, legitimately reading a real secret server-side)
+ * is invisible to Gate B once projection has already removed `loader`
+ * entirely, exactly as it should be: Gate B's job is to fence client-bound
+ * code, and projection is what decides what counts as client-bound. A
+ * component-level secret read is untouched by projection and still reaches
+ * Gate B, which refuses it. Gate B does not depend on Gate A's `resolveId`
+ * output at all (orthogonal concern, raw source vs. import paths), so its
+ * position relative to Gate A is not load-bearing — it is placed before Gate
+ * A only to keep both `transform` hooks adjacent in the array.
+ *
+ * Gate C (`gate-c-verify.ts`) runs last and only at `generateBundle` — after
+ * the entire `transform`/`resolveId` build phase has completed for every
+ * plugin, regardless of array position (a Rollup lifecycle fact, not
+ * something this array order enforces). It verifies the EMITTED output the
+ * other three produced: no server export survived as a top-level binding, no
+ * import edge into a server-only package survived into the module graph, and
+ * it emits the reviewable `PUBLIC_*` inlined-value manifest. `gateBSecrets` and `gateCVerify` share
+ * one `PublicEnvTracker` instance so the manifest and Gate B's own unread-key
+ * exclusion check agree by construction, not by coincidence.
+ *
+ * `clientPageRegistry()` is FIRST, ahead of projection. It contributes no
+ * `transform` at all — only a `resolveId`/`load` pair for one synthetic id —
+ * so it cannot displace or pre-empt any gate's inspection of any real file.
+ * Two reasons for the position, one of which is not load-bearing and is
+ * labelled as such:
+ *
+ * 1. Load-bearing: it must own `virtual:warlock/pages` before Gate A's
+ *    `resolveId` (also `enforce: "pre"`) reaches its `this.resolve(...)` call
+ *    for that specifier. Gate A's nested resolve would find it anyway, but
+ *    routing the id through Gate A's importer-chain bookkeeping only to have
+ *    it come back means a synthetic id can surface in a user-facing "Import
+ *    chain:" message. Resolving it first keeps ownership of the id in one
+ *    place.
+ * 2. NOT load-bearing: the position relative to `projection()`. Projection is
+ *    `enforce: "pre"` and selects by file BASENAME (`projection.ts:242-248`),
+ *    so it transforms every `*.page.tsx` / `layout.tsx` / `root.tsx` that
+ *    enters the graph regardless of who imported it or where this plugin sits.
+ *    The registry emits absolute POSIX specifiers that Rollup resolves and
+ *    loads as ORDINARY file modules — they are not inlined into the virtual
+ *    module — so each one is transformed exactly as a page imported from a
+ *    real file would be. Projection declines the virtual module itself
+ *    (`\0virtual:warlock/pages` has no matching basename), which is correct:
+ *    generated code has no server exports to strip.
+ *
+ * Point 2 is asserted, not assumed, by a real `vite.build()` in
+ * `page-registry-plugin.spec.ts`: a fixture page whose `loader` — and only its
+ * `loader` — imports a marker module that Gate A independently PERMITS, built
+ * through this exact array, with the marker proven absent from every emitted
+ * chunk while the page's own component text is proven present. Inspecting this
+ * array's order would prove nothing about what reaches the browser.
+ */
+declare function warlockClientBoundary(options?: Parameters<typeof gateAResolve>[0]): Plugin[];
+/**
+ * Callable production seam: callers own their exact source aliases and the
+ * app-root classification boundary, while this module owns the one canonical
+ * projection/Gate B/Gate A/Gate C composition.
+ */
+declare function buildWarlockHydrationClient(options: BuildWarlockHydrationClientOptions): Promise<BuildHydrationClientResult>;
+//#endregion
+export { type BuildHydrationClientOptions, type BuildHydrationClientResult, BuildWarlockHydrationClientOptions, CLIENT_PAGE_REGISTRY_ID, type ClientPageRegistryPluginOptions, type EnvironmentClassifier, type EnvironmentClassifierOptions, type GateCOptions, HYDRATION_CLIENT_ENTRY_NAME, type HydrationClientBuildOutput, type HydrationClientEntry, ProjectionAmbiguityError, type ProjectionResult, type PublicEnvManifestEntry, type PublicEnvTracker, RESOLVED_CLIENT_PAGE_REGISTRY_ID, type ServerExportLeak, type ServerImportEdgeLeak, WarlockClientBoundaryOptions, type WarlockEnvironment, buildHydrationClient, buildPublicEnvManifest, buildWarlockHydrationClient, clientPageRegistry, createHydrationClientEntry, createPublicEnvTracker, findLeakedServerExports, findLeakedServerImportEdges, gateAResolve, gateBSecrets, gateCVerify, projection, warlockClientBoundary };
+//# sourceMappingURL=index.d.mts.map