@presolve/vite 0.2.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2026 Presolve contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@presolve/vite",
+  "version": "0.2.0-beta.1",
+  "description": "Vite adapter boundary for compiler-owned Presolve products.",
+  "license": "MIT OR Apache-2.0",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fierstdev/presolve.git",
+    "directory": "packages/vite"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "beta"
+  },
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "peerDependencies": {
+    "vite": "^7.0.0"
+  },
+  "scripts": {
+    "test": "node test/smoke.mjs"
+  }
+}

package/src/index.js

@@ -0,0 +1,610 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+
+/** V1 shape of the compiler manifest consumed by this external adapter. */
+export const PRESOLVE_VITE_ADAPTER_SCHEMA_VERSION = 1;
+export const PRESOLVE_APPLICATION_PUBLICATION_CONTRACT_V1 = "presolve-application-publication:1";
+export const PRESOLVE_VIRTUAL_MODULE_SCHEMA_VERSION = 1;
+export const PRESOLVE_VIRTUAL_MODULE_PREFIX = "virtual:presolve/v1/";
+export const PRESOLVE_ENVIRONMENT_PUBLICATION_ARTIFACT = "environment.browser.json";
+export const PRESOLVE_ENVIRONMENT_PUBLICATION_SCHEMA_VERSION = 1;
+export const PRESOLVE_DEVELOPMENT_DIAGNOSTICS_SCHEMA_VERSION = 1;
+export const PRESOLVE_VITE_PRODUCTION_SCHEMA_VERSION = 1;
+export const PRESOLVE_HMR_UPDATE_SCHEMA_VERSION = 1;
+export const PRESOLVE_HMR_EVENT = "presolve:hmr";
+export const PRESOLVE_PRODUCTION_AUDIT_SCHEMA_VERSION = 1;
+export const PRESOLVE_PRODUCTION_AUDIT_ARTIFACT = "production-audit.json";
+export const PRESOLVE_SOURCE_MAP_TRANSLATION_SCHEMA_VERSION = 1;
+
+const PRESOLVE_HMR_MESSAGE_CLASSES = new Set([
+  "template-update",
+  "action-update",
+  "computed-update",
+  "style-update",
+  "server-only-update",
+  "component-instance-reload",
+  "route-reload",
+  "full-reload",
+]);
+
+/**
+ * Creates the Vite transport boundary over an already-produced compiler product.
+ *
+ * The compiler owns parsing, TypeScript semantics, lowering, and artifact
+ * contents. This package owns only Vite integration and its transport hooks.
+ */
+export function createPresolveVitePlugin({ compilerProduct, readArtifact, requestHost, hmr } = {}) {
+  const manifest = validateCompilerProduct(compilerProduct);
+  let hmrTransport;
+  const plugin = {
+    name: "presolve:compiler-products",
+    enforce: "pre",
+    api: Object.freeze({
+      schemaVersion: PRESOLVE_VITE_ADAPTER_SCHEMA_VERSION,
+      compilerContract: manifest.compiler_contract,
+      workspaceSnapshotId: manifest.workspace_snapshot_id,
+    }),
+  };
+  if (readArtifact) {
+    const registry = createPresolveVirtualModuleRegistry({ compilerProduct, readArtifact });
+    plugin.resolveId = registry.resolveId;
+    plugin.load = async resolvedId => {
+      const code = await registry.load(resolvedId);
+      if (code === undefined) return undefined;
+      return {
+        code,
+        // This is a transport map for the virtual compiler artifact, not an
+        // authored-source map. Vite may retain it in physical output maps.
+        map: {
+          version: 3,
+          sources: [resolvedId.replace(/^\0/, "")],
+          sourcesContent: [code],
+          names: [],
+          mappings: "AAAA",
+        },
+      };
+    };
+  }
+  if (requestHost !== undefined && typeof requestHost !== "function") {
+    throw new TypeError("@presolve/vite requestHost must be a function");
+  }
+  if (hmr !== undefined && typeof hmr !== "function") {
+    throw new TypeError("@presolve/vite hmr must be a compiler-owned function");
+  }
+  if (hmr) {
+    plugin.handleHotUpdate = async context => {
+      if (!hmrTransport) {
+        throw new Error("Presolve HMR transport is unavailable before Vite configures the server");
+      }
+      return hmrTransport.publish(
+        await hmr(Object.freeze({ file: context.file, timestamp: context.timestamp })),
+        context.modules,
+      );
+    };
+  }
+  if (requestHost || hmr) {
+    plugin.configureServer = server => {
+      if (requestHost) {
+        server.middlewares.use((request, response, next) => {
+          Promise.resolve(requestHost(request)).then(hostResponse => {
+            if (hostResponse === undefined) {
+              next();
+              return;
+            }
+            writeHostResponse(response, hostResponse);
+          }).catch(next);
+        });
+      }
+      if (hmr) {
+        hmrTransport = createPresolveHmrTransport({
+          workspaceSnapshotId: manifest.workspace_snapshot_id,
+          send: message => server.ws.send(message),
+        });
+      }
+    };
+  }
+  return Object.freeze(plugin);
+}
+
+/**
+ * Validates and transports one compiler-selected HMR update without deriving
+ * semantics from Vite modules, source text, or filenames.
+ */
+export function createPresolveHmrTransport({ workspaceSnapshotId, send } = {}) {
+  if (typeof workspaceSnapshotId !== "string" || !workspaceSnapshotId) {
+    throw new TypeError("Presolve HMR transport requires a workspaceSnapshotId");
+  }
+  if (typeof send !== "function") {
+    throw new TypeError("Presolve HMR transport requires a Vite send function");
+  }
+  return Object.freeze({
+    schemaVersion: PRESOLVE_HMR_UPDATE_SCHEMA_VERSION,
+    publish(update, viteModules = []) {
+      const canonical = validateHmrUpdate(update, workspaceSnapshotId);
+      if (!Array.isArray(viteModules)) {
+        throw new TypeError("Vite HMR modules must be an array");
+      }
+      if (canonical.messageClass === "style-update") return viteModules;
+      if (canonical.messageClass === "full-reload") {
+        send({ type: "full-reload", path: "*" });
+        return [];
+      }
+      send({ type: "custom", event: PRESOLVE_HMR_EVENT, data: canonical });
+      return [];
+    },
+  });
+}
+
+/**
+ * Starts the Vite development server owned by the `presolve dev` boundary.
+ *
+ * The request host decides document, route, loader, and action routing from
+ * compiler products; returning `undefined` delegates JS, CSS, and assets to
+ * Vite middleware. Vite types are intentionally not exposed from this API.
+ */
+export async function startPresolveDevServer({
+  compilerProduct,
+  readArtifact,
+  requestHost,
+  hmr,
+  diagnostics = () => ({}),
+  vite = {},
+} = {}) {
+  if (typeof requestHost !== "function") {
+    throw new TypeError("presolve dev requires a compiler-owned requestHost");
+  }
+  if (typeof diagnostics !== "function") {
+    throw new TypeError("presolve dev diagnostics must be a function");
+  }
+  const { createServer } = await import("vite");
+  const plugin = createPresolveVitePlugin({ compilerProduct, readArtifact, requestHost, hmr });
+  const configuredPlugins = vite.plugins === undefined
+    ? []
+    : Array.isArray(vite.plugins) ? vite.plugins : [vite.plugins];
+  const server = await createServer({
+    ...vite,
+    appType: "custom",
+    plugins: [...configuredPlugins, plugin],
+  });
+  let currentDiagnostics = composeDevelopmentDiagnostics(await diagnostics());
+  const publishDiagnostics = async () => {
+    currentDiagnostics = composeDevelopmentDiagnostics(await diagnostics());
+    server.ws.send({
+      type: "custom",
+      event: "presolve:diagnostics",
+      data: currentDiagnostics,
+    });
+    return currentDiagnostics;
+  };
+  await server.listen();
+  await publishDiagnostics();
+  return Object.freeze({
+    server,
+    diagnostics: () => currentDiagnostics,
+    publishDiagnostics,
+    close: () => server.close(),
+  });
+}
+
+/** Merges TypeScript and Presolve diagnostics without changing their meaning. */
+export function composeDevelopmentDiagnostics({ typescript = [], presolve = [] } = {}) {
+  const diagnostics = [
+    ...normalizeDiagnostics("typescript", typescript),
+    ...normalizeDiagnostics("presolve", presolve),
+  ].sort(compareDevelopmentDiagnostics);
+  return Object.freeze({
+    schemaVersion: PRESOLVE_DEVELOPMENT_DIAGNOSTICS_SCHEMA_VERSION,
+    diagnostics: Object.freeze(diagnostics),
+  });
+}
+
+/**
+ * Runs Vite's production build for one compiler-selected logical entry.
+ *
+ * The Vite manifest is read after physical output is written and then mapped
+ * back to the stable compiler entry-component ID. No Vite filename becomes a
+ * compiler semantic identity.
+ */
+export async function buildPresolveProduction({
+  compilerProduct,
+  readArtifact,
+  entryArtifactPath,
+  viteEntries = [],
+  vite = {},
+} = {}) {
+  const manifest = validateCompilerProduct(compilerProduct);
+  if (typeof entryArtifactPath !== "string" || !entryArtifactPath) {
+    throw new TypeError("Presolve production build requires an entryArtifactPath");
+  }
+  if (!manifest.artifacts.some(artifact => artifact.path === entryArtifactPath)) {
+    throw new TypeError(`Presolve production entry is not a compiler artifact: ${entryArtifactPath}`);
+  }
+  if (typeof manifest.entry_component_id !== "string" || !manifest.entry_component_id) {
+    throw new TypeError("Presolve production build requires manifest.entry_component_id");
+  }
+  if (!Array.isArray(viteEntries)) {
+    throw new TypeError("Presolve Vite entries must be an array");
+  }
+  const outDir = vite.build?.outDir;
+  if (typeof outDir !== "string" || !outDir) {
+    throw new TypeError("Presolve production build requires an explicit Vite build.outDir");
+  }
+  const manifestName = "presolve-vite-manifest.json";
+  const virtualEntryId = `${PRESOLVE_VIRTUAL_MODULE_PREFIX}${entryArtifactPath}`;
+  const viteRoot = typeof vite.root === "string" && vite.root ? vite.root : process.cwd();
+  const additionalInputs = viteEntries
+    .map(validateViteEntry)
+    .map(entry => Object.freeze({ ...entry, path: resolve(viteRoot, entry.path) }));
+  if (new Set(additionalInputs.map(entry => entry.name)).size !== additionalInputs.length) {
+    throw new TypeError("Presolve Vite entry names must be unique");
+  }
+  const input = Object.fromEntries([
+    ["presolve-compiler-entry", virtualEntryId],
+    ...additionalInputs.map(entry => [entry.name, entry.path]),
+  ]);
+  const plugin = createPresolveVitePlugin({ compilerProduct, readArtifact });
+  const configuredPlugins = vite.plugins === undefined
+    ? []
+    : Array.isArray(vite.plugins) ? vite.plugins : [vite.plugins];
+  const { build } = await import("vite");
+  await build({
+    ...vite,
+    configFile: false,
+    plugins: [...configuredPlugins, plugin],
+    build: {
+      ...vite.build,
+      outDir,
+      emptyOutDir: false,
+      manifest: manifestName,
+      sourcemap: true,
+      rollupOptions: {
+        ...vite.build?.rollupOptions,
+        input,
+      },
+    },
+  });
+  const viteManifestPath = join(outDir, manifestName);
+  const viteManifest = JSON.parse(await readFile(viteManifestPath, "utf8"));
+  const isCompilerEntry = input => input === virtualEntryId
+    || input === "presolve-compiler-entry"
+    || input.endsWith(`${PRESOLVE_VIRTUAL_MODULE_PREFIX}${entryArtifactPath}`);
+  const entries = Object.entries(viteManifest)
+    .filter(([, output]) => output.isEntry)
+    .map(([input, output]) => Object.freeze({
+      input,
+      file: output.file,
+      css: Object.freeze([...(output.css ?? [])].sort()),
+      assets: Object.freeze([...(output.assets ?? [])].sort()),
+      imports: Object.freeze([...(output.imports ?? [])].sort()),
+      compilerArtifactPath: isCompilerEntry(input)
+        ? entryArtifactPath
+        : undefined,
+      componentId: isCompilerEntry(input)
+        ? manifest.entry_component_id
+        : undefined,
+    }))
+    .sort((left, right) => left.input.localeCompare(right.input));
+  if (!entries.some(entry => entry.compilerArtifactPath === entryArtifactPath)) {
+    throw new Error("Vite production manifest did not retain the compiler-selected virtual entry");
+  }
+  const sourceMaps = await Promise.all(entries
+    .filter(entry => entry.compilerArtifactPath !== undefined)
+    .map(async entry => {
+    const mapPath = join(outDir, `${entry.file}.map`);
+    let map;
+    try {
+      map = JSON.parse(await readFile(mapPath, "utf8"));
+    } catch {
+      throw new Error(`Vite did not emit a source map for ${entry.file}`);
+    }
+    return Object.freeze({
+      file: entry.file,
+      mapPath,
+      translation: translatePresolveSourceMap({ compilerProduct, sourceMap: map }),
+    });
+    }));
+  return Object.freeze({
+    schemaVersion: PRESOLVE_VITE_PRODUCTION_SCHEMA_VERSION,
+    compilerContract: manifest.compiler_contract,
+    workspaceSnapshotId: manifest.workspace_snapshot_id,
+    entryComponentId: manifest.entry_component_id,
+    viteManifestPath,
+    entries: Object.freeze(entries),
+    sourceMaps: Object.freeze(sourceMaps),
+  });
+}
+
+function validateViteEntry(entry) {
+  if (!entry || typeof entry !== "object" || Array.isArray(entry)
+    || typeof entry.name !== "string" || !entry.name
+    || typeof entry.path !== "string" || !entry.path
+    || entry.name === "presolve-compiler-entry") {
+    throw new TypeError("Presolve Vite entries require a non-empty name and path");
+  }
+  return Object.freeze({ name: entry.name, path: entry.path });
+}
+
+/**
+ * Associates Vite map sources with exact compiler publication artifacts. This
+ * does not decode mappings or fabricate authored locations: Vite owns map
+ * generation and the compiler manifest owns the logical source identity.
+ */
+export function translatePresolveSourceMap({ compilerProduct, sourceMap } = {}) {
+  const manifest = validateCompilerProduct(compilerProduct);
+  if (!sourceMap || typeof sourceMap !== "object" || !Array.isArray(sourceMap.sources)) {
+    throw new TypeError("Vite source map requires a sources array");
+  }
+  const artifactPaths = new Set(manifest.artifacts.map(artifact => {
+    validateArtifact(artifact);
+    return artifact.path;
+  }));
+  const sources = sourceMap.sources.map(source => {
+    if (typeof source !== "string" || !source) {
+      throw new TypeError("Vite source map sources must be non-empty strings");
+    }
+    const index = source.indexOf(PRESOLVE_VIRTUAL_MODULE_PREFIX);
+    const artifactPath = index < 0 ? undefined : source.slice(index + PRESOLVE_VIRTUAL_MODULE_PREFIX.length);
+    return Object.freeze({
+      viteSource: source,
+      compilerArtifactPath: artifactPaths.has(artifactPath) ? artifactPath : undefined,
+    });
+  });
+  return Object.freeze({
+    schemaVersion: PRESOLVE_SOURCE_MAP_TRANSLATION_SCHEMA_VERSION,
+    workspaceSnapshotId: manifest.workspace_snapshot_id,
+    sources: Object.freeze(sources),
+  });
+}
+
+/**
+ * Reads the compiler-produced production audit after verifying its publication
+ * digest. The adapter validates transport shape only; audit policy remains in
+ * the compiler artifact.
+ */
+export async function readPresolveProductionAudit({ compilerProduct, readArtifact } = {}) {
+  const manifest = validateCompilerProduct(compilerProduct);
+  if (typeof readArtifact !== "function") {
+    throw new TypeError("Presolve production audit requires a readArtifact function");
+  }
+  const artifact = manifest.artifacts.find(candidate => candidate.path === PRESOLVE_PRODUCTION_AUDIT_ARTIFACT);
+  if (!artifact) {
+    throw new TypeError("compiler product does not publish a production audit artifact");
+  }
+  validateArtifact(artifact);
+  const bytes = toBytes(await readArtifact(artifact.path));
+  const digest = createHash("sha256").update(bytes).digest("hex");
+  if (digest !== artifact.digest) {
+    throw new Error("compiler production audit digest mismatch");
+  }
+  let audit;
+  try {
+    audit = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+  } catch {
+    throw new TypeError("compiler production audit must be UTF-8 JSON");
+  }
+  if (!audit || typeof audit !== "object" || Array.isArray(audit)
+    || audit.schemaVersion !== PRESOLVE_PRODUCTION_AUDIT_SCHEMA_VERSION
+    || audit.status !== "passed"
+    || typeof audit.buildId !== "string" || !audit.buildId
+    || !Array.isArray(audit.checks) || audit.checks.some(check => typeof check !== "string" || !check)) {
+    throw new TypeError("compiler production audit is not a passing schema-v1 product");
+  }
+  return Object.freeze({
+    schemaVersion: audit.schemaVersion,
+    buildId: audit.buildId,
+    optimizationReportSchemaVersion: audit.optimizationReportSchemaVersion,
+    runtimeCostReportSchemaVersion: audit.runtimeCostReportSchemaVersion,
+    runtimeTableCount: audit.runtimeTableCount,
+    authorityCount: audit.authorityCount,
+    invariantCount: audit.invariantCount,
+    checks: Object.freeze([...audit.checks]),
+    status: audit.status,
+  });
+}
+
+/**
+ * Builds versioned Vite module names from one digest-bound compiler product.
+ *
+ * `readArtifact` is a host bridge over exact compiler bytes. Content is
+ * re-digested before Vite sees it, so the manifest remains the source of truth.
+ */
+export function createPresolveVirtualModuleRegistry({ compilerProduct, readArtifact }) {
+  const manifest = validateCompilerProduct(compilerProduct);
+  if (typeof readArtifact !== "function") {
+    throw new TypeError("@presolve/vite virtual modules require a readArtifact function");
+  }
+  const modules = new Map();
+  for (const artifact of manifest.artifacts) {
+    validateArtifact(artifact);
+    const id = `${PRESOLVE_VIRTUAL_MODULE_PREFIX}${artifact.path}`;
+    if (modules.has(id)) {
+      throw new TypeError(`duplicate Presolve publication artifact ${artifact.path}`);
+    }
+    modules.set(id, Object.freeze({
+      id,
+      resolvedId: `\0${id}`,
+      artifactPath: artifact.path,
+      digest: artifact.digest,
+    }));
+  }
+  const entries = Object.freeze([...modules.values()].sort((left, right) => left.id.localeCompare(right.id)));
+  return Object.freeze({
+    schemaVersion: PRESOLVE_VIRTUAL_MODULE_SCHEMA_VERSION,
+    entries,
+    resolveId(id) {
+      return modules.get(id)?.resolvedId;
+    },
+    async load(resolvedId) {
+      const entry = entries.find(candidate => candidate.resolvedId === resolvedId);
+      if (!entry) return undefined;
+      const bytes = toBytes(await readArtifact(entry.artifactPath));
+      const digest = createHash("sha256").update(bytes).digest("hex");
+      if (digest !== entry.digest) {
+        throw new Error(`compiler artifact digest mismatch for ${entry.artifactPath}`);
+      }
+      return virtualModuleSource(entry.artifactPath, new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    },
+  });
+}
+
+function validateCompilerProduct(product) {
+  if (!product || typeof product !== "object") {
+    throw new TypeError("@presolve/vite requires a compiler product object");
+  }
+  const { manifest } = product;
+  if (!manifest || typeof manifest !== "object") {
+    throw new TypeError("@presolve/vite requires compilerProduct.manifest");
+  }
+  if (manifest.schema_version !== 1) {
+    throw new TypeError(`unsupported Presolve publication manifest schema ${manifest.schema_version}`);
+  }
+  if (manifest.compiler_contract !== PRESOLVE_APPLICATION_PUBLICATION_CONTRACT_V1) {
+    throw new TypeError(`unsupported Presolve compiler contract ${manifest.compiler_contract}`);
+  }
+  if (!Array.isArray(manifest.artifacts)) {
+    throw new TypeError("Presolve publication manifest must contain artifacts");
+  }
+  return manifest;
+}
+
+function validateHmrUpdate(update, workspaceSnapshotId) {
+  if (!update || typeof update !== "object" || Array.isArray(update)) {
+    throw new TypeError("Presolve HMR update must be an object");
+  }
+  if (update.schemaVersion !== PRESOLVE_HMR_UPDATE_SCHEMA_VERSION) {
+    throw new TypeError(`unsupported Presolve HMR update schema ${update.schemaVersion}`);
+  }
+  if (update.workspaceSnapshotId !== workspaceSnapshotId) {
+    throw new TypeError("Presolve HMR update workspace snapshot does not match the compiler product");
+  }
+  if (typeof update.updateId !== "string" || !update.updateId) {
+    throw new TypeError("Presolve HMR update requires a stable updateId");
+  }
+  if (!PRESOLVE_HMR_MESSAGE_CLASSES.has(update.messageClass)) {
+    throw new TypeError("Presolve HMR update has an unsupported messageClass");
+  }
+  if (!Array.isArray(update.affectedModuleIds)
+    || update.affectedModuleIds.some(id => typeof id !== "string" || !id)
+    || [...new Set(update.affectedModuleIds)].length !== update.affectedModuleIds.length
+    || [...update.affectedModuleIds].sort().some((id, index) => id !== update.affectedModuleIds[index])) {
+    throw new TypeError("Presolve HMR update requires sorted unique affectedModuleIds");
+  }
+  if (!matchesStateCompatibility(update)) {
+    throw new TypeError("Presolve HMR state preservation must be explicitly compiler-proven");
+  }
+  return Object.freeze({
+    schemaVersion: update.schemaVersion,
+    workspaceSnapshotId: update.workspaceSnapshotId,
+    updateId: update.updateId,
+    messageClass: update.messageClass,
+    affectedModuleIds: Object.freeze([...update.affectedModuleIds]),
+    stateCompatibility: update.stateCompatibility,
+    preserveState: update.preserveState,
+  });
+}
+
+function matchesStateCompatibility(update) {
+  return (update.stateCompatibility === "proven-compatible" && update.preserveState === true)
+    || (update.stateCompatibility === "reload-required" && update.preserveState === false);
+}
+
+function validateArtifact(artifact) {
+  if (!artifact || typeof artifact.path !== "string" || !artifact.path || artifact.path.startsWith("/")
+    || artifact.path.split("/").includes("..")) {
+    throw new TypeError("Presolve publication artifact paths must be non-escaping relative paths");
+  }
+  if (!/^[a-f0-9]{64}$/.test(artifact.digest)) {
+    throw new TypeError(`Presolve publication artifact ${artifact.path} requires a SHA-256 digest`);
+  }
+}
+
+function toBytes(value) {
+  if (value instanceof Uint8Array) return value;
+  if (typeof value === "string") return new TextEncoder().encode(value);
+  throw new TypeError("readArtifact must return a string or Uint8Array");
+}
+
+function virtualModuleSource(artifactPath, content) {
+  if (artifactPath === PRESOLVE_ENVIRONMENT_PUBLICATION_ARTIFACT) {
+    return environmentVirtualModuleSource(artifactPath, content);
+  }
+  return [
+    `export const artifactPath = ${JSON.stringify(artifactPath)};`,
+    `export const content = ${JSON.stringify(content)};`,
+    "export default content;",
+    "",
+  ].join("\n");
+}
+
+/**
+ * Projects the compiler-published browser environment artifact into one Vite
+ * virtual module. This validates only the immutable compiler product: it never
+ * reads dotenv files, process state, or Vite's environment object.
+ */
+function environmentVirtualModuleSource(artifactPath, content) {
+  let artifact;
+  try {
+    artifact = JSON.parse(content);
+  } catch {
+    throw new TypeError("Presolve browser environment artifact must be UTF-8 JSON");
+  }
+  if (!artifact || typeof artifact !== "object" || Array.isArray(artifact)
+    || artifact.schemaVersion !== PRESOLVE_ENVIRONMENT_PUBLICATION_SCHEMA_VERSION
+    || !artifact.browserValues || typeof artifact.browserValues !== "object"
+    || Array.isArray(artifact.browserValues)) {
+    throw new TypeError("Presolve browser environment artifact must be a schema-v1 compiler product");
+  }
+  for (const [name, value] of Object.entries(artifact.browserValues)) {
+    if (!name.startsWith("PRESOLVE_PUBLIC_") || name.length === "PRESOLVE_PUBLIC_".length
+      || typeof value !== "string" || value.includes("\0")) {
+      throw new TypeError("Presolve browser environment artifact contained an invalid public value");
+    }
+  }
+  const browserValues = Object.fromEntries(Object.entries(artifact.browserValues).sort(
+    ([left], [right]) => left.localeCompare(right),
+  ));
+  return [
+    `export const artifactPath = ${JSON.stringify(artifactPath)};`,
+    `export const schemaVersion = ${PRESOLVE_ENVIRONMENT_PUBLICATION_SCHEMA_VERSION};`,
+    `export const browserValues = Object.freeze(${JSON.stringify(browserValues)});`,
+    "export default browserValues;",
+    "",
+  ].join("\n");
+}
+
+function writeHostResponse(response, hostResponse) {
+  if (!hostResponse || typeof hostResponse !== "object") {
+    throw new TypeError("Presolve requestHost must return undefined or a response object");
+  }
+  const { status = 200, headers = {}, body = "" } = hostResponse;
+  if (!Number.isInteger(status) || status < 100 || status > 599) {
+    throw new TypeError("Presolve requestHost response status must be an HTTP status code");
+  }
+  if (!headers || typeof headers !== "object" || Array.isArray(headers)) {
+    throw new TypeError("Presolve requestHost response headers must be an object");
+  }
+  response.statusCode = status;
+  for (const [name, value] of Object.entries(headers)) response.setHeader(name, value);
+  response.end(toBytes(body));
+}
+
+function normalizeDiagnostics(authority, diagnostics) {
+  if (!Array.isArray(diagnostics)) {
+    throw new TypeError(`${authority} diagnostics must be an array`);
+  }
+  return diagnostics.map(diagnostic => {
+    if (!diagnostic || typeof diagnostic !== "object" || diagnostic.code === undefined
+      || typeof diagnostic.message !== "string") {
+      throw new TypeError(`${authority} diagnostics require code and message`);
+    }
+    return Object.freeze({ authority, ...diagnostic });
+  });
+}
+
+function compareDevelopmentDiagnostics(left, right) {
+  return String(left.file ?? "").localeCompare(String(right.file ?? ""))
+    || (left.start ?? -1) - (right.start ?? -1)
+    || String(left.code).localeCompare(String(right.code))
+    || left.authority.localeCompare(right.authority);
+}

package/test/smoke.mjs

@@ -0,0 +1,357 @@
+import { createHash } from "node:crypto";
+import { mkdtemp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  buildPresolveProduction,
+  createPresolveHmrTransport,
+  createPresolveVitePlugin,
+  createPresolveVirtualModuleRegistry,
+  composeDevelopmentDiagnostics,
+  PRESOLVE_HMR_EVENT,
+  PRESOLVE_ENVIRONMENT_PUBLICATION_ARTIFACT,
+  readPresolveProductionAudit,
+  translatePresolveSourceMap,
+  PRESOLVE_VITE_ADAPTER_SCHEMA_VERSION,
+  PRESOLVE_VIRTUAL_MODULE_PREFIX,
+  startPresolveDevServer,
+} from "../src/index.js";
+
+const runtime = "export const runtime = 1;\n";
+const digest = createHash("sha256").update(runtime).digest("hex");
+const environmentArtifact = JSON.stringify({
+  schemaVersion: 1,
+  browserValues: { PRESOLVE_PUBLIC_NAME: "Presolve" },
+});
+const environmentDigest = createHash("sha256").update(environmentArtifact).digest("hex");
+const auditJson = JSON.stringify({
+  schemaVersion: 1,
+  buildId: "resume-build:fixture",
+  optimizationReportSchemaVersion: 1,
+  runtimeCostReportSchemaVersion: 1,
+  runtimeTableCount: 0,
+  authorityCount: 8,
+  invariantCount: 13,
+  checks: ["report-schema"],
+  status: "passed",
+});
+const auditDigest = createHash("sha256").update(auditJson).digest("hex");
+const plugin = createPresolveVitePlugin({
+  compilerProduct: {
+    manifest: {
+      schema_version: 1,
+      compiler_contract: "presolve-application-publication:1",
+      workspace_snapshot_id: "fixture-snapshot",
+      artifacts: [{ path: "runtime.js", digest }],
+    },
+  },
+});
+
+if (plugin.name !== "presolve:compiler-products" || plugin.enforce !== "pre") {
+  throw new Error("adapter must expose its stable Vite plugin identity");
+}
+if (plugin.api.schemaVersion !== PRESOLVE_VITE_ADAPTER_SCHEMA_VERSION) {
+  throw new Error("adapter must expose its schema version");
+}
+if ("resolveId" in plugin || "load" in plugin || "configureServer" in plugin) {
+  throw new Error("the skeleton must not publish virtual modules or dev-server hooks");
+}
+assertRejects(
+  () => createPresolveVitePlugin({ compilerProduct: { manifest: { schema_version: 2 } } }),
+  "unsupported manifest schemas must not enter Vite",
+);
+
+const registry = createPresolveVirtualModuleRegistry({
+  compilerProduct: {
+    manifest: {
+      schema_version: 1,
+      compiler_contract: "presolve-application-publication:1",
+      workspace_snapshot_id: "fixture-snapshot",
+      artifacts: [{ path: "runtime.js", digest }],
+    },
+  },
+  readArtifact: path => path === "runtime.js" ? runtime : undefined,
+});
+const virtualId = `${PRESOLVE_VIRTUAL_MODULE_PREFIX}runtime.js`;
+const resolvedId = registry.resolveId(virtualId);
+if (resolvedId !== `\0${virtualId}`) throw new Error("registry must resolve a versioned virtual module id");
+const source = await registry.load(resolvedId);
+const expected = [
+  "export const artifactPath = \"runtime.js\";",
+  "export const content = \"export const runtime = 1;\\n\";",
+  "export default content;",
+  "",
+].join("\n");
+if (source !== expected) throw new Error("registry must expose the golden compiler artifact content");
+await assertAsyncRejects(
+  () => createPresolveVirtualModuleRegistry({
+    compilerProduct: { manifest: { schema_version: 1, compiler_contract: "presolve-application-publication:1", artifacts: [{ path: "runtime.js", digest: "0".repeat(64) }] } },
+    readArtifact: () => runtime,
+  }).load(`\0${virtualId}`),
+  "registry must reject artifact content that differs from its compiler digest",
+);
+
+const environmentRegistry = createPresolveVirtualModuleRegistry({
+  compilerProduct: {
+    manifest: {
+      schema_version: 1,
+      compiler_contract: "presolve-application-publication:1",
+      workspace_snapshot_id: "fixture-snapshot",
+      artifacts: [{ path: PRESOLVE_ENVIRONMENT_PUBLICATION_ARTIFACT, digest: environmentDigest }],
+    },
+  },
+  readArtifact: path => path === PRESOLVE_ENVIRONMENT_PUBLICATION_ARTIFACT ? environmentArtifact : undefined,
+});
+const environmentSource = await environmentRegistry.load(
+  environmentRegistry.resolveId(`${PRESOLVE_VIRTUAL_MODULE_PREFIX}${PRESOLVE_ENVIRONMENT_PUBLICATION_ARTIFACT}`),
+);
+if (!environmentSource.includes('export const browserValues = Object.freeze({"PRESOLVE_PUBLIC_NAME":"Presolve"});')
+  || environmentSource.includes("process.env") || environmentSource.includes("import.meta.env")) {
+  throw new Error("Vite must expose only the compiler-published browser environment map");
+}
+await assertAsyncRejects(
+  () => createPresolveVirtualModuleRegistry({
+    compilerProduct: {
+      manifest: {
+        schema_version: 1,
+        compiler_contract: "presolve-application-publication:1",
+        workspace_snapshot_id: "fixture-snapshot",
+        artifacts: [{ path: PRESOLVE_ENVIRONMENT_PUBLICATION_ARTIFACT, digest: createHash("sha256").update('{"schemaVersion":1,"browserValues":{"DATABASE_URL":"secret"}}').digest("hex") }],
+      },
+    },
+    readArtifact: () => '{"schemaVersion":1,"browserValues":{"DATABASE_URL":"secret"}}',
+  }).load(`\0${PRESOLVE_VIRTUAL_MODULE_PREFIX}${PRESOLVE_ENVIRONMENT_PUBLICATION_ARTIFACT}`),
+  "Vite must reject server-owned values in a compiler environment artifact",
+);
+
+const audit = await readPresolveProductionAudit({
+  compilerProduct: {
+    manifest: {
+      schema_version: 1,
+      compiler_contract: "presolve-application-publication:1",
+      workspace_snapshot_id: "fixture-snapshot",
+      artifacts: [{ path: "production-audit.json", digest: auditDigest }],
+    },
+  },
+  readArtifact: () => auditJson,
+});
+if (audit.status !== "passed" || audit.buildId !== "resume-build:fixture") {
+  throw new Error("Vite must expose the digest-verified compiler production audit");
+}
+await assertAsyncRejects(
+  () => readPresolveProductionAudit({
+    compilerProduct: {
+      manifest: {
+        schema_version: 1,
+        compiler_contract: "presolve-application-publication:1",
+        workspace_snapshot_id: "fixture-snapshot",
+        artifacts: [{ path: "production-audit.json", digest: "0".repeat(64) }],
+      },
+    },
+    readArtifact: () => auditJson,
+  }),
+  "Vite must reject a production audit whose bytes differ from the compiler manifest",
+);
+
+const sourceMapTranslation = translatePresolveSourceMap({
+  compilerProduct: {
+    manifest: {
+      schema_version: 1,
+      compiler_contract: "presolve-application-publication:1",
+      workspace_snapshot_id: "fixture-snapshot",
+      artifacts: [{ path: "runtime.js", digest }],
+    },
+  },
+  sourceMap: { version: 3, sources: [`\0${PRESOLVE_VIRTUAL_MODULE_PREFIX}runtime.js`, "node_modules/dependency.js"] },
+});
+if (sourceMapTranslation.sources[0].compilerArtifactPath !== "runtime.js"
+  || sourceMapTranslation.sources[1].compilerArtifactPath !== undefined) {
+  throw new Error("source-map translation must retain only manifest-bound compiler identities");
+}
+
+const diagnostics = composeDevelopmentDiagnostics({
+  typescript: [{ code: 2322, message: "Type mismatch", file: "src/App.tsx", start: 12 }],
+  presolve: [{ code: "PSV1001", message: "Unsupported construct", file: "src/App.tsx", start: 3 }],
+});
+if (diagnostics.diagnostics.map(diagnostic => diagnostic.authority).join(",") !== "presolve,typescript") {
+  throw new Error("development diagnostics must compose and order both authorities");
+}
+
+const hmrMessages = [];
+const hmr = createPresolveHmrTransport({
+  workspaceSnapshotId: "fixture-snapshot",
+  send: message => hmrMessages.push(message),
+});
+const actionUpdate = {
+  schemaVersion: 1,
+  workspaceSnapshotId: "fixture-snapshot",
+  updateId: "hmr-action-1",
+  messageClass: "action-update",
+  affectedModuleIds: ["virtual:presolve/v1/runtime.js"],
+  stateCompatibility: "proven-compatible",
+  preserveState: true,
+};
+if (hmr.publish(actionUpdate, [{ id: "vite-runtime" }]).length !== 0) {
+  throw new Error("semantic HMR must suppress Vite module replacement");
+}
+if (hmrMessages.length !== 1 || hmrMessages[0].event !== PRESOLVE_HMR_EVENT
+  || hmrMessages[0].data.preserveState !== true) {
+  throw new Error("semantic HMR must transport the compiler-selected update unchanged");
+}
+const viteModules = [{ id: "vite-style" }];
+if (hmr.publish({ ...actionUpdate, updateId: "hmr-style-1", messageClass: "style-update" }, viteModules) !== viteModules) {
+  throw new Error("style updates must remain under Vite native CSS HMR");
+}
+hmr.publish({
+  ...actionUpdate,
+  updateId: "hmr-full-1",
+  messageClass: "full-reload",
+  stateCompatibility: "reload-required",
+  preserveState: false,
+});
+if (hmrMessages.at(-1).type !== "full-reload") {
+  throw new Error("full reload must use Vite's native transport");
+}
+assertRejects(
+  () => hmr.publish({ ...actionUpdate, updateId: "hmr-unsafe-1", preserveState: false }),
+  "the adapter must reject state preservation that was not compiler-proven",
+);
+const hmrPlugin = createPresolveVitePlugin({
+  compilerProduct: {
+    manifest: {
+      schema_version: 1,
+      compiler_contract: "presolve-application-publication:1",
+      workspace_snapshot_id: "fixture-snapshot",
+      artifacts: [{ path: "runtime.js", digest }],
+    },
+  },
+  hmr: observation => ({ ...actionUpdate, updateId: `hmr-hook-${observation.timestamp}` }),
+});
+const hmrPluginMessages = [];
+hmrPlugin.configureServer({ ws: { send: message => hmrPluginMessages.push(message) }, middlewares: { use() {} } });
+const hmrResult = await hmrPlugin.handleHotUpdate({ file: "/work/runtime.ts", timestamp: 10, modules: viteModules });
+if (hmrResult.length !== 0 || hmrPluginMessages[0].data.updateId !== "hmr-hook-10") {
+  throw new Error("Vite's hot-update hook must only forward the compiler HMR product");
+}
+
+const dev = await startPresolveDevServer({
+  compilerProduct: {
+    manifest: {
+      schema_version: 1,
+      compiler_contract: "presolve-application-publication:1",
+      workspace_snapshot_id: "fixture-snapshot",
+      artifacts: [{ path: "runtime.js", digest }],
+    },
+  },
+  readArtifact: () => runtime,
+  requestHost: request => request.url === "/route"
+    ? { status: 200, headers: { "content-type": "text/plain" }, body: "Presolve route" }
+    : undefined,
+  diagnostics: () => ({ typescript: [{ code: 2322, message: "Type mismatch" }], presolve: [] }),
+  vite: { logLevel: "silent", server: { host: "127.0.0.1", port: 0 } },
+});
+try {
+  const address = dev.server.httpServer.address();
+  const response = await fetch(`http://127.0.0.1:${address.port}/route`, {
+    headers: { connection: "close" },
+  });
+  if (response.status !== 200 || await response.text() !== "Presolve route") {
+    throw new Error("presolve dev must route compiler-owned requests without restarting Vite");
+  }
+  const viteAsset = await fetch(`http://127.0.0.1:${address.port}/@vite/client`, {
+    headers: { connection: "close" },
+  });
+  if (viteAsset.status !== 200 || !(await viteAsset.text()).includes("createHotContext")) {
+    throw new Error("unclaimed JS assets must continue through Vite middleware");
+  }
+  const published = await dev.publishDiagnostics();
+  if (published.diagnostics.length !== 1 || published.diagnostics[0].authority !== "typescript") {
+    throw new Error("presolve dev must republish the composed diagnostics product");
+  }
+} finally {
+  dev.server.httpServer.closeAllConnections?.();
+  await dev.close();
+}
+
+const outputDirectory = await mkdtemp(join(tmpdir(), "presolve-vite-build-"));
+const applicationDirectory = await mkdtemp(join(tmpdir(), "presolve-vite-assets-"));
+try {
+  await mkdir(join(applicationDirectory, "styles"));
+  await mkdir(join(applicationDirectory, "assets"));
+  await mkdir(join(applicationDirectory, "public"));
+  await writeFile(join(applicationDirectory, "assets", "mark.svg"), "<svg xmlns=\"http://www.w3.org/2000/svg\"/>\n");
+  await writeFile(join(applicationDirectory, "public", "robots.txt"), "User-agent: *\n");
+  await writeFile(join(applicationDirectory, "styles", "app.css"), ".app { background-image: url('../assets/mark.svg'); }\n");
+  await writeFile(join(applicationDirectory, "styles", "card.module.css"), ".card { --presolve-card-color: 43; color: var(--presolve-card-color); }\n");
+  await writeFile(
+    join(applicationDirectory, "ui-entry.js"),
+    "import './styles/app.css'; import styles from './styles/card.module.css'; document.documentElement.className = styles.card;\n",
+  );
+  const production = await buildPresolveProduction({
+    compilerProduct: {
+      manifest: {
+        schema_version: 1,
+        compiler_contract: "presolve-application-publication:1",
+        workspace_snapshot_id: "fixture-snapshot",
+        entry_component_id: "component:x-app",
+        artifacts: [{ path: "runtime.js", digest }],
+      },
+    },
+    readArtifact: () => runtime,
+    entryArtifactPath: "runtime.js",
+    viteEntries: [{ name: "application-ui", path: "ui-entry.js" }],
+    vite: {
+      root: applicationDirectory,
+      publicDir: "public",
+      logLevel: "silent",
+      build: { outDir: outputDirectory, assetsInlineLimit: 0 },
+    },
+  });
+  if (production.entryComponentId !== "component:x-app" || production.entries.length !== 2) {
+    throw new Error("production build must retain the compiler entry and explicit Vite entries");
+  }
+  if (production.sourceMaps.length !== 1 || !production.sourceMaps[0].mapPath.endsWith(".map")) {
+    throw new Error("production builds must emit and report Vite source maps");
+  }
+  const entry = production.entries.find(candidate => candidate.compilerArtifactPath === "runtime.js");
+  if (entry.compilerArtifactPath !== "runtime.js" || entry.componentId !== "component:x-app") {
+    throw new Error("production entry mapping must retain compiler identities");
+  }
+  const physicalManifest = JSON.parse(await readFile(production.viteManifestPath, "utf8"));
+  if (!Object.values(physicalManifest).some(output => output.file === entry.file)) {
+    throw new Error("production product must describe a file from Vite's written manifest");
+  }
+  const ui = production.entries.find(candidate => candidate.input.endsWith("ui-entry.js"));
+  if (!ui || ui.compilerArtifactPath !== undefined || ui.css.length === 0) {
+    throw new Error("Vite-owned CSS module entries must stay outside compiler identity mapping");
+  }
+  const css = (await Promise.all(ui.css.map(path => readFile(join(outputDirectory, path), "utf8")))).join("\n");
+  if (!css.includes("--presolve-card-color") || !css.includes("mark-")) {
+    throw new Error("Vite must package CSS modules and imported asset URLs");
+  }
+  if (await readFile(join(outputDirectory, "robots.txt"), "utf8") !== "User-agent: *\n") {
+    throw new Error("Vite must copy caller-declared public assets");
+  }
+} finally {
+  await rm(outputDirectory, { recursive: true, force: true });
+  await rm(applicationDirectory, { recursive: true, force: true });
+}
+process.exit(0);
+
+function assertRejects(action, message) {
+  try {
+    action();
+  } catch {
+    return;
+  }
+  throw new Error(message);
+}
+
+async function assertAsyncRejects(action, message) {
+  try {
+    await action();
+  } catch {
+    return;
+  }
+  throw new Error(message);
+}