vector-framework 1.2.2 → 1.2.3

package/dist/cli.js

@@ -1,9 +1,1807 @@
 #!/usr/bin/env bun
 // @bun
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+
+// src/checkpoint/types.ts
+var CHECKPOINT_FORMAT_VERSION = 1;
+
+// src/checkpoint/artifacts/compressor.ts
+function compressBytes(input, codec = DEFAULT_ASSET_CODEC) {
+  const normalized = new Uint8Array(input);
+  switch (codec) {
+    case "none":
+      return normalized;
+    case "gzip":
+      return Bun.gzipSync(normalized);
+    default:
+      throw new Error(`Unsupported compression codec: ${codec}`);
+  }
+}
+var DEFAULT_ASSET_CODEC = "gzip";
+
+// src/checkpoint/artifacts/hasher.ts
+function sha256Hex(content) {
+  const bytes = content instanceof Uint8Array ? content : new Uint8Array(content);
+  const hashBuffer = Bun.SHA256.hash(bytes);
+  const hashBytes = new Uint8Array(hashBuffer.buffer, hashBuffer.byteOffset, hashBuffer.byteLength);
+  return Buffer.from(hashBytes).toString("hex");
+}
+
+// src/checkpoint/artifacts/manifest.ts
+import { basename, isAbsolute as isAbsolute2, relative as relative3 } from "path";
+function normalizeLogicalPath(input) {
+  const normalizedInput = normalizeSlashes(input).trim();
+  const rel = isAbsolutePathPortable(normalizedInput) ? toPortableRelativePath(normalizedInput) : normalizedInput;
+  const cleaned = rel.split("/").filter((segment) => segment.length > 0 && segment !== "." && segment !== "..").join("/");
+  const sanitized = cleaned.replace(UNSAFE_SEGMENT_PATTERN, "_").replace(/^\/+/, "");
+  if (sanitized.length > 0) {
+    return sanitized;
+  }
+  const fallback = basename(normalizedInput).replace(UNSAFE_SEGMENT_PATTERN, "_");
+  return fallback.length > 0 ? `external/${fallback}` : "external/asset.bin";
+}
+function normalizeRelativePath(input) {
+  return normalizeSlashes(input).replace(/^\/+/, "");
+}
+function isAbsolutePathPortable(input) {
+  const normalized = normalizeSlashes(input).trim();
+  return isAbsolute2(normalized) || WINDOWS_DRIVE_ABS_PATTERN.test(normalized) || WINDOWS_UNC_ABS_PATTERN.test(input);
+}
+function computeAssetFingerprint(assets) {
+  const stable = assets.map((asset) => ({
+    type: asset.type,
+    logicalPath: asset.logicalPath,
+    contentHash: asset.contentHash ?? asset.hash,
+    blobHash: asset.blobHash ?? "",
+    blobPath: asset.blobPath ?? asset.storedPath,
+    codec: asset.codec ?? "none",
+    size: asset.contentSize ?? asset.size
+  })).sort((a, b) => `${a.type}:${a.logicalPath}:${a.contentHash}:${a.blobHash}`.localeCompare(`${b.type}:${b.logicalPath}:${b.contentHash}:${b.blobHash}`));
+  return JSON.stringify(stable);
+}
+function normalizeSlashes(value) {
+  return value.replace(/\\/g, "/");
+}
+function toPortableRelativePath(input) {
+  const normalized = normalizeSlashes(input);
+  if (WINDOWS_DRIVE_ABS_PATTERN.test(normalized)) {
+    return normalized.replace(/^[a-zA-Z]:/, "").replace(/^\/+/, "");
+  }
+  if (WINDOWS_UNC_ABS_PATTERN.test(input)) {
+    return normalizeSlashes(input).replace(/^\\\\[^\\]+\\[^\\]+/, "").replace(/^\/+/, "");
+  }
+  return normalizeSlashes(relative3(process.cwd(), normalized));
+}
+var UNSAFE_SEGMENT_PATTERN, WINDOWS_DRIVE_ABS_PATTERN, WINDOWS_UNC_ABS_PATTERN;
+var init_manifest = __esm(() => {
+  UNSAFE_SEGMENT_PATTERN = /[^a-zA-Z0-9._/-]/g;
+  WINDOWS_DRIVE_ABS_PATTERN = /^[a-zA-Z]:[\\/]/;
+  WINDOWS_UNC_ABS_PATTERN = /^\\\\[^\\]+\\[^\\]+/;
+});
+
+// src/checkpoint/artifacts/store.ts
+import { existsSync as existsSync4, promises as fs3 } from "fs";
+import { join as join3 } from "path";
+
+class CheckpointArtifactStore {
+  storageDir;
+  codec;
+  constructor(storageDir, options = {}) {
+    this.storageDir = storageDir;
+    this.codec = options.assetCodec ?? DEFAULT_ASSET_CODEC;
+  }
+  async addEmbedded(logicalPath, sourcePath) {
+    return this.addAsset("embedded", logicalPath, sourcePath);
+  }
+  async addSidecar(logicalPath, sourcePath) {
+    return this.addAsset("sidecar", logicalPath, sourcePath);
+  }
+  async collect(embeddedPaths, sidecarPaths) {
+    const records = [];
+    for (const sourcePath of embeddedPaths) {
+      records.push(await this.addEmbedded(sourcePath, sourcePath));
+    }
+    for (const sourcePath of sidecarPaths) {
+      records.push(await this.addSidecar(sourcePath, sourcePath));
+    }
+    return records;
+  }
+  async addAsset(type, logicalPath, sourcePath) {
+    const content = await fs3.readFile(sourcePath);
+    const contentBytes = new Uint8Array(content.buffer, content.byteOffset, content.byteLength);
+    const contentHash = sha256Hex(contentBytes);
+    const compressed = compressBytes(contentBytes, this.codec);
+    const blobHash = sha256Hex(compressed);
+    const blobPath = normalizeRelativePath(join3(BLOB_DIR, `${blobHash}${this.codec === "gzip" ? ".gz" : ""}`));
+    const storedPath = join3(this.storageDir, blobPath);
+    await fs3.mkdir(join3(this.storageDir, BLOB_DIR), { recursive: true });
+    if (!existsSync4(storedPath)) {
+      await this.writeAtomically(storedPath, compressed);
+    } else {
+      const existing = await fs3.readFile(storedPath);
+      const existingBytes = new Uint8Array(existing.buffer, existing.byteOffset, existing.byteLength);
+      if (sha256Hex(existingBytes) !== blobHash) {
+        await this.writeAtomically(storedPath, compressed);
+      }
+    }
+    return {
+      type,
+      logicalPath: normalizeLogicalPath(logicalPath),
+      storedPath,
+      hash: contentHash,
+      size: content.byteLength,
+      contentHash,
+      contentSize: content.byteLength,
+      blobHash,
+      blobSize: compressed.byteLength,
+      blobPath,
+      codec: this.codec
+    };
+  }
+  async writeAtomically(path, bytes) {
+    const tempPath = `${path}.tmp.${process.pid}.${Date.now()}`;
+    await fs3.writeFile(tempPath, bytes);
+    try {
+      await fs3.rename(tempPath, path);
+    } catch (error) {
+      if (!isAlreadyExists(error)) {
+        throw error;
+      }
+      await fs3.rm(path, { force: true });
+      await fs3.rename(tempPath, path);
+    }
+  }
+}
+function isAlreadyExists(error) {
+  if (typeof error !== "object" || error === null || !("code" in error)) {
+    return false;
+  }
+  const code = error.code;
+  return code === "EEXIST" || code === "EPERM";
+}
+var BLOB_DIR = "_assets/blobs";
+var init_store = __esm(() => {
+  init_manifest();
+});
+
+// src/checkpoint/asset-store.ts
+import { promises as fs4 } from "fs";
+
+class AssetStore {
+  artifactStore;
+  constructor(storageDir) {
+    this.artifactStore = new CheckpointArtifactStore(storageDir);
+  }
+  async addEmbedded(logicalPath, sourcePath) {
+    const content = await fs4.readFile(sourcePath);
+    if (content.byteLength > EMBEDDED_PER_FILE_BUDGET) {
+      throw new Error(`Embedded asset "${logicalPath}" is ${formatBytes(content.byteLength)} \u2014 exceeds ${formatBytes(EMBEDDED_PER_FILE_BUDGET)} per-file budget. Use sidecar instead.`);
+    }
+    return await this.artifactStore.addEmbedded(logicalPath, sourcePath);
+  }
+  async addSidecar(logicalPath, sourcePath) {
+    return await this.artifactStore.addSidecar(logicalPath, sourcePath);
+  }
+  async collect(embeddedPaths, sidecarPaths) {
+    const records = [];
+    for (const p of embeddedPaths) {
+      records.push(await this.addEmbedded(p, p));
+    }
+    for (const p of sidecarPaths) {
+      records.push(await this.addSidecar(p, p));
+    }
+    return records;
+  }
+  validateBudgets(records) {
+    const embeddedTotal = records.filter((r) => r.type === "embedded").reduce((acc, r) => acc + (r.contentSize ?? r.size), 0);
+    if (embeddedTotal > EMBEDDED_TOTAL_BUDGET) {
+      throw new Error(`Total embedded asset size ${formatBytes(embeddedTotal)} exceeds ${formatBytes(EMBEDDED_TOTAL_BUDGET)} budget.`);
+    }
+  }
+}
+function formatBytes(bytes) {
+  if (bytes < 1024)
+    return `${bytes} B`;
+  if (bytes < 1024 * 1024)
+    return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+var EMBEDDED_PER_FILE_BUDGET, EMBEDDED_TOTAL_BUDGET;
+var init_asset_store = __esm(() => {
+  init_store();
+  EMBEDDED_PER_FILE_BUDGET = 64 * 1024;
+  EMBEDDED_TOTAL_BUDGET = 512 * 1024;
+});
+
+// src/checkpoint/bundler.ts
+import { existsSync as existsSync5 } from "fs";
+import { join as join4 } from "path";
+
+class CheckpointBundler {
+  async bundle(options) {
+    const outfile = options.outputFile ?? "checkpoint.js";
+    const result = await Bun.build({
+      entrypoints: [options.entrypointPath],
+      outdir: options.outputDir,
+      target: "bun",
+      format: "esm",
+      minify: true,
+      naming: { entry: outfile }
+    });
+    if (!result.success) {
+      const messages = result.logs.map((l) => l.message ?? String(l)).join(`
+`);
+      throw new Error(`Checkpoint bundle failed:
+${messages}`);
+    }
+    const outputPath = join4(options.outputDir, outfile);
+    if (!existsSync5(outputPath)) {
+      const actualOutput = result.outputs.find((o) => o.kind === "entry-point");
+      if (actualOutput) {
+        const actualPath = actualOutput.path;
+        if (existsSync5(actualPath)) {
+          return this.hashFile(actualPath);
+        }
+      }
+      throw new Error(`Bundle output not found at expected path: ${outputPath}`);
+    }
+    return this.hashFile(outputPath);
+  }
+  async hashFile(path) {
+    const file = Bun.file(path);
+    const content = await file.arrayBuffer();
+    const hashBuffer = Bun.SHA256.hash(new Uint8Array(content));
+    const hashBytes = new Uint8Array(hashBuffer.buffer, hashBuffer.byteOffset, hashBuffer.byteLength);
+    const hash = Buffer.from(hashBytes).toString("hex");
+    return {
+      outputPath: path,
+      hash,
+      size: content.byteLength
+    };
+  }
+}
+var init_bundler = () => {};
+
+// src/checkpoint/entrypoint-generator.ts
+import { existsSync as existsSync6, promises as fs5 } from "fs";
+import { join as join5, relative as relative4, sep as sep2 } from "path";
+
+class CheckpointEntrypointGenerator {
+  discoveredRoutes = [];
+  async generate(options) {
+    const routeFiles = await this.scanRouteFiles(options.routesDir);
+    const source = this.buildSource(routeFiles, options);
+    const outputPath = join5(options.outputDir, "entrypoint.ts");
+    await fs5.writeFile(outputPath, source, "utf-8");
+    return outputPath;
+  }
+  getDiscoveredRoutes() {
+    return this.discoveredRoutes;
+  }
+  async scanRouteFiles(routesDir) {
+    if (!existsSync6(routesDir)) {
+      return [];
+    }
+    const files = [];
+    await this.walkDir(routesDir, files);
+    return files;
+  }
+  async walkDir(dir, files) {
+    const entries = await fs5.readdir(dir);
+    for (const entry of entries) {
+      const fullPath = join5(dir, entry);
+      const stats = await fs5.stat(fullPath);
+      if (stats.isDirectory()) {
+        await this.walkDir(fullPath, files);
+      } else if ((entry.endsWith(".ts") || entry.endsWith(".js")) && !entry.endsWith(".test.ts") && !entry.endsWith(".test.js") && !entry.endsWith(".spec.ts") && !entry.endsWith(".spec.js") && !entry.endsWith(".d.ts")) {
+        files.push(fullPath);
+      }
+    }
+  }
+  buildSource(routeFiles, options) {
+    this.discoveredRoutes = [];
+    const imports = [];
+    const registrations = [];
+    for (const [i, file] of routeFiles.entries()) {
+      const varName = `routeModule_${i}`;
+      const importSpecifier = this.toImportSpecifier(file, options.outputDir);
+      imports.push(`import * as ${varName} from ${JSON.stringify(importSpecifier)};`);
+      registrations.push(`  registerModule(${varName});`);
+      const routePath = relative4(options.routesDir, file).replace(/\.(ts|js)$/, "").split(sep2).join("/");
+      this.discoveredRoutes.push({
+        method: "*",
+        path: `/${routePath}`
+      });
+    }
+    return `// Checkpoint entrypoint \u2014 auto-generated for version ${options.version}
+// DO NOT EDIT: This file is generated by Vector checkpoint publish.
+
+${imports.join(`
+`)}
+
+const socketPath = process.env.VECTOR_CHECKPOINT_SOCKET ?? '${options.socketPath}';
+const checkpointContextHeader = 'x-vector-checkpoint-context';
+
+// Route registration helper
+type RouteDefinition = {
+  entry: { method: string; path: string };
+  options: { method: string; path: string; [key: string]: any };
+  handler: (ctx: any) => any;
+};
+
+function isRouteDefinition(value: unknown): value is RouteDefinition {
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    'entry' in value &&
+    'options' in value &&
+    'handler' in value &&
+    typeof (value as any).handler === 'function'
+  );
+}
+
+const routeTable: Record<string, Record<string, (req: Request) => Response | Promise<Response>>> = {};
+
+function parseCheckpointContext(req: Request): Record<string, unknown> {
+  const encoded = req.headers.get(checkpointContextHeader);
+  if (!encoded) {
+    return {};
+  }
+
+  try {
+    const json = Buffer.from(encoded, 'base64url').toString('utf-8');
+    const parsed = JSON.parse(json);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      return {};
+    }
+    return parsed as Record<string, unknown>;
+  } catch {
+    return {};
+  }
+}
+
+function parseQuery(url: URL): Record<string, string | string[]> {
+  const query: Record<string, string | string[]> = {};
+  for (const [key, value] of url.searchParams) {
+    if (key in query) {
+      const existing = query[key];
+      if (Array.isArray(existing)) {
+        existing.push(value);
+      } else {
+        query[key] = [existing as string, value];
+      }
+    } else {
+      query[key] = value;
+    }
+  }
+  return query;
+}
+
+function parseCookies(cookieHeader: string | null): Record<string, string> {
+  const cookies: Record<string, string> = {};
+  if (!cookieHeader) {
+    return cookies;
+  }
+  for (const pair of cookieHeader.split(';')) {
+    const idx = pair.indexOf('=');
+    if (idx > 0) {
+      cookies[pair.slice(0, idx).trim()] = pair.slice(idx + 1).trim();
+    }
+  }
+  return cookies;
+}
+
+function extractRouteParams(req: Request): Record<string, string> {
+  const nativeParams = (req as Request & { params?: Record<string, string> }).params;
+  if (nativeParams && typeof nativeParams === 'object' && !Array.isArray(nativeParams)) {
+    return nativeParams;
+  }
+  return {};
+}
+
+function createContext(req: Request): Record<string, unknown> {
+  const ctx: Record<string, unknown> = Object.create(null);
+  setContextField(ctx, 'request', req);
+
+  // Initialize always-present VectorContext fields with defaults derived from the request
+  setContextField(ctx, 'params', extractRouteParams(req));
+
+  try {
+    setContextField(ctx, 'query', parseQuery(new URL(req.url)));
+  } catch {
+    setContextField(ctx, 'query', {});
+  }
+
+  setContextField(ctx, 'cookies', parseCookies(req.headers.get('cookie')));
+  setContextField(ctx, 'metadata', {});
+
+  const checkpointContext = parseCheckpointContext(req);
+  const allowedCheckpointKeys = ['metadata', 'content', 'validatedInput', 'authUser'] as const;
+  for (const key of allowedCheckpointKeys) {
+    if (!Object.prototype.hasOwnProperty.call(checkpointContext, key)) {
+      continue;
+    }
+    const value = checkpointContext[key];
+    setContextField(ctx, key, value);
+  }
+
+  return ctx;
+}
+
+function setContextField(target: Record<string, unknown>, key: string, value: unknown) {
+  const ownDescriptor = Object.getOwnPropertyDescriptor(target as object, key);
+  if (ownDescriptor && ownDescriptor.writable === false && typeof ownDescriptor.set !== 'function') {
+    return;
+  }
+
+  try {
+    target[key] = value;
+    return;
+  } catch {
+    // Fall back to own-property define when inherited Request field is readonly.
+  }
+
+  try {
+    Object.defineProperty(target, key, {
+      value,
+      writable: true,
+      configurable: true,
+      enumerable: true,
+    });
+  } catch {
+    // Ignore non-extensible context edge cases.
+  }
+}
+
+function addToRouteTable(method: string, path: string, handler: (ctx: any) => any) {
+  if (!routeTable[path]) {
+    routeTable[path] = Object.create(null);
+  }
+  routeTable[path][method.toUpperCase()] = async (req: Request) => {
+    const ctx = createContext(req);
+    const result = await handler(ctx);
+    if (result instanceof Response) return result;
+    return Response.json(result);
+  };
+}
+
+function registerModule(mod: Record<string, unknown>) {
+  for (const [name, value] of Object.entries(mod)) {
+    if (isRouteDefinition(value)) {
+      addToRouteTable(value.options.method, value.options.path, value.handler);
+    } else if (name === 'default' && typeof value === 'function') {
+      // Default export functions need path context \u2014 skip for now
+    }
+  }
+}
+
+${registrations.join(`
+`)}
+
+// Health check endpoint for parent process
+routeTable['/_vector/health'] = {
+  GET: () => Response.json({ status: 'ok', version: '${options.version}' }),
+};
+
+const server = Bun.serve({
+  unix: socketPath,
+  routes: routeTable,
+  fetch(req: Request) {
+    return Response.json(
+      { error: true, message: 'Not Found', statusCode: 404 },
+      { status: 404 }
+    );
+  },
+});
+
+// Signal readiness to parent process
+process.stdout.write('READY\\n');
+`;
+  }
+  toImportSpecifier(filePath, outputDir) {
+    const normalized = relative4(outputDir, filePath).split(sep2).join("/");
+    if (normalized.startsWith(".") || normalized.startsWith("/")) {
+      return normalized;
+    }
+    return `./${normalized}`;
+  }
+}
+var init_entrypoint_generator = () => {};
+
+// src/checkpoint/artifacts/packager.ts
+import { promises as fs6 } from "fs";
+import { join as join6, relative as relative5 } from "path";
+
+class CheckpointPackager {
+  storageDir;
+  codec;
+  constructor(storageDir, codec = "gzip") {
+    this.storageDir = storageDir;
+    this.codec = codec;
+  }
+  async packageVersion(version) {
+    const versionDir = join6(this.storageDir, version);
+    const archiveRelPath = join6(ARCHIVE_DIR, `${version}${this.archiveSuffix()}`).replace(/\\/g, "/");
+    const archivePath = join6(this.storageDir, archiveRelPath);
+    await fs6.mkdir(join6(this.storageDir, ARCHIVE_DIR), { recursive: true });
+    const files = await collectFiles(versionDir);
+    const archiveBytes = await this.buildArchiveBytes(versionDir, archivePath, files);
+    return {
+      archivePath: archiveRelPath,
+      archiveHash: sha256Hex(archiveBytes),
+      archiveSize: archiveBytes.byteLength,
+      codec: this.codec
+    };
+  }
+  async buildArchiveBytes(versionDir, archivePath, files) {
+    const ArchiveCtor = Bun.Archive;
+    if (typeof ArchiveCtor === "function") {
+      const archiveEntries = Object.fromEntries(files.map((filePath) => {
+        const rel = relative5(versionDir, filePath).replace(/\\/g, "/");
+        return [rel, Bun.file(filePath)];
+      }));
+      const archive = new ArchiveCtor(archiveEntries);
+      const tarBytes = new Uint8Array(await archive.bytes());
+      const archiveBytes = this.codec === "gzip" ? Bun.gzipSync(tarBytes) : tarBytes;
+      await Bun.write(archivePath, archiveBytes);
+      return archiveBytes;
+    }
+    await this.buildArchiveWithTar(versionDir, archivePath, files);
+    const bytes = await fs6.readFile(archivePath);
+    return new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  }
+  async buildArchiveWithTar(versionDir, archivePath, files) {
+    const relFiles = files.map((filePath) => relative5(versionDir, filePath));
+    if (relFiles.length === 0) {
+      throw new Error(`Cannot package checkpoint: no files found in "${versionDir}"`);
+    }
+    const tarArgs = this.codec === "gzip" ? ["-czf", archivePath] : ["-cf", archivePath];
+    const proc = Bun.spawn(["tar", ...tarArgs, "-C", versionDir, ...relFiles], {
+      stdout: "pipe",
+      stderr: "pipe"
+    });
+    const exitCode = await proc.exited;
+    if (exitCode === 0) {
+      return;
+    }
+    const stderr = await new Response(proc.stderr).text();
+    throw new Error(`Failed to package checkpoint archive with tar (exit ${exitCode}): ${stderr.trim()}`);
+  }
+  archiveSuffix() {
+    return this.codec === "gzip" ? ".tar.gz" : ".tar";
+  }
+}
+async function collectFiles(root) {
+  const files = [];
+  await walk(root, files);
+  return files.filter((filePath) => relative5(root, filePath).replace(/\\/g, "/") !== "manifest.json");
+}
+async function walk(dir, files) {
+  const entries = await fs6.readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = join6(dir, entry.name);
+    if (entry.isDirectory()) {
+      await walk(fullPath, files);
+      continue;
+    }
+    if (entry.isFile()) {
+      files.push(fullPath);
+    }
+  }
+}
+var ARCHIVE_DIR = "_archives";
+var init_packager = () => {};
+
+// src/checkpoint/socket-path.ts
+import { createHash } from "crypto";
+import { tmpdir } from "os";
+import { isAbsolute as isAbsolute3, join as join7, resolve as resolve3 } from "path";
+function toAbsolute(dir) {
+  return isAbsolute3(dir) ? dir : resolve3(dir);
+}
+function unixSocketWithinLimit(path) {
+  return Buffer.byteLength(path, "utf8") <= UNIX_SOCKET_PATH_MAX_BYTES;
+}
+function socketFileName(storageDir, version) {
+  const versionLabel = version.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/(^-+|-+$)/g, "").slice(0, 12);
+  const digest = createHash("sha256").update(storageDir).update("\x00").update(version).digest("hex").slice(0, 16);
+  const label = versionLabel.length > 0 ? `${versionLabel}-` : "";
+  return `vector-${label}${digest}.sock`;
+}
+function candidateSocketRoots() {
+  const roots = new Set;
+  const override = process.env.VECTOR_CHECKPOINT_SOCKET_DIR?.trim();
+  if (override) {
+    roots.add(toAbsolute(override));
+  }
+  if (process.platform !== "win32") {
+    roots.add("/tmp");
+    roots.add("/private/tmp");
+  }
+  roots.add(toAbsolute(tmpdir()));
+  return [...roots];
+}
+function resolveCheckpointSocketPath(storageDir, version) {
+  const defaultPath = join7(storageDir, version, CHECKPOINT_SOCKET_FILE);
+  if (process.platform === "win32" || unixSocketWithinLimit(defaultPath)) {
+    return defaultPath;
+  }
+  const fileName = socketFileName(storageDir, version);
+  for (const root of candidateSocketRoots()) {
+    const candidate = join7(root, fileName);
+    if (unixSocketWithinLimit(candidate)) {
+      return candidate;
+    }
+  }
+  return join7("/tmp", fileName);
+}
+var CHECKPOINT_SOCKET_FILE = "run.sock", UNIX_SOCKET_PATH_MAX_BYTES = 103;
+var init_socket_path = () => {};
+
+// src/checkpoint/manager.ts
+var exports_manager = {};
+__export(exports_manager, {
+  CheckpointManager: () => CheckpointManager
+});
+import { existsSync as existsSync7, promises as fs7 } from "fs";
+import { join as join8, resolve as resolve4 } from "path";
+function inferLegacyAssetCodec(asset) {
+  if (asset.codec) {
+    return asset.codec;
+  }
+  const rawPath = (asset.blobPath ?? asset.storedPath ?? "").trim().toLowerCase();
+  return rawPath.endsWith(".gz") ? "gzip" : "none";
+}
+
+class CheckpointManager {
+  storageDir;
+  maxCheckpoints;
+  constructor(config = {}) {
+    this.storageDir = resolve4(process.cwd(), config.storageDir ?? DEFAULT_STORAGE_DIR);
+    this.maxCheckpoints = config.maxCheckpoints ?? 10;
+  }
+  getStorageDir() {
+    return this.storageDir;
+  }
+  versionDir(version) {
+    return join8(this.storageDir, version);
+  }
+  socketPath(version) {
+    return resolveCheckpointSocketPath(this.storageDir, version);
+  }
+  async ensureStorageDir() {
+    await fs7.mkdir(this.storageDir, { recursive: true });
+  }
+  async publish(options) {
+    await this.ensureStorageDir();
+    const versionDir = this.versionDir(options.version);
+    await fs7.mkdir(versionDir, { recursive: true });
+    const generator = new CheckpointEntrypointGenerator;
+    const entrypointPath = await generator.generate({
+      version: options.version,
+      outputDir: versionDir,
+      routesDir: resolve4(process.cwd(), options.routesDir),
+      socketPath: this.socketPath(options.version)
+    });
+    const bundler = new CheckpointBundler;
+    const bundleResult = await bundler.bundle({
+      entrypointPath,
+      outputDir: versionDir
+    });
+    const assetStore = new AssetStore(this.storageDir);
+    const assets = await assetStore.collect(options.embeddedAssetPaths ?? [], options.sidecarAssetPaths ?? []);
+    assetStore.validateBudgets(assets);
+    const manifest = {
+      formatVersion: CHECKPOINT_FORMAT_VERSION,
+      version: options.version,
+      createdAt: new Date().toISOString(),
+      entrypoint: "checkpoint.js",
+      routes: generator.getDiscoveredRoutes(),
+      assets,
+      bundleHash: bundleResult.hash,
+      bundleSize: bundleResult.size,
+      checkpointArchivePath: undefined,
+      checkpointArchiveHash: undefined,
+      checkpointArchiveSize: undefined,
+      checkpointArchiveCodec: undefined
+    };
+    await this.writeManifest(options.version, manifest);
+    try {
+      await fs7.unlink(entrypointPath);
+    } catch {}
+    const packager = new CheckpointPackager(this.storageDir);
+    const archive = await packager.packageVersion(options.version);
+    manifest.checkpointArchivePath = archive.archivePath;
+    manifest.checkpointArchiveHash = archive.archiveHash;
+    manifest.checkpointArchiveSize = archive.archiveSize;
+    manifest.checkpointArchiveCodec = archive.codec;
+    await this.writeManifest(options.version, manifest);
+    await this.pruneOld();
+    return manifest;
+  }
+  async readManifest(version) {
+    const manifestPath = join8(this.versionDir(version), "manifest.json");
+    const content = await fs7.readFile(manifestPath, "utf-8");
+    return this.normalizeManifest(JSON.parse(content));
+  }
+  async writeManifest(version, manifest) {
+    const manifestPath = join8(this.versionDir(version), "manifest.json");
+    await fs7.writeFile(manifestPath, JSON.stringify(manifest, null, 2), "utf-8");
+  }
+  async listVersions() {
+    if (!existsSync7(this.storageDir)) {
+      return [];
+    }
+    const entries = await fs7.readdir(this.storageDir);
+    const manifests = [];
+    for (const entry of entries) {
+      const manifestPath = join8(this.storageDir, entry, "manifest.json");
+      if (existsSync7(manifestPath)) {
+        try {
+          const content = await fs7.readFile(manifestPath, "utf-8");
+          manifests.push(this.normalizeManifest(JSON.parse(content)));
+        } catch {}
+      }
+    }
+    manifests.sort((a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime());
+    return manifests;
+  }
+  async getActive() {
+    const pointerPath = join8(this.storageDir, ACTIVE_POINTER_FILE);
+    if (!existsSync7(pointerPath)) {
+      return null;
+    }
+    try {
+      const content = await fs7.readFile(pointerPath, "utf-8");
+      return JSON.parse(content);
+    } catch {
+      return null;
+    }
+  }
+  async setActive(version) {
+    const versionDir = this.versionDir(version);
+    if (!existsSync7(versionDir)) {
+      throw new Error(`Checkpoint version ${version} does not exist`);
+    }
+    const manifestPath = join8(versionDir, "manifest.json");
+    if (!existsSync7(manifestPath)) {
+      throw new Error(`Checkpoint version ${version} has no manifest`);
+    }
+    await this.ensureStorageDir();
+    const pointer = {
+      version,
+      activatedAt: new Date().toISOString()
+    };
+    const pointerPath = join8(this.storageDir, ACTIVE_POINTER_FILE);
+    await fs7.writeFile(pointerPath, JSON.stringify(pointer, null, 2), "utf-8");
+  }
+  async remove(version) {
+    const active = await this.getActive();
+    if (active?.version === version) {
+      throw new Error(`Cannot remove active checkpoint version ${version}. Rollback to a different version first.`);
+    }
+    const versionDir = this.versionDir(version);
+    if (!existsSync7(versionDir)) {
+      throw new Error(`Checkpoint version ${version} does not exist`);
+    }
+    await fs7.rm(versionDir, { recursive: true, force: true });
+  }
+  async pruneOld() {
+    if (this.maxCheckpoints <= 0)
+      return;
+    const manifests = await this.listVersions();
+    if (manifests.length <= this.maxCheckpoints)
+      return;
+    const active = await this.getActive();
+    const toRemove = manifests.slice(this.maxCheckpoints);
+    for (const manifest of toRemove) {
+      if (active?.version === manifest.version)
+        continue;
+      try {
+        const versionDir = this.versionDir(manifest.version);
+        await fs7.rm(versionDir, { recursive: true, force: true });
+      } catch {}
+    }
+  }
+  normalizeManifest(manifest) {
+    const normalizedAssets = (manifest.assets ?? []).map((asset) => ({
+      ...asset,
+      contentHash: asset.contentHash ?? asset.hash,
+      contentSize: asset.contentSize ?? asset.size,
+      blobPath: asset.blobPath ?? asset.storedPath,
+      blobHash: asset.blobHash,
+      blobSize: asset.blobSize,
+      codec: inferLegacyAssetCodec(asset)
+    }));
+    return {
+      formatVersion: manifest.formatVersion ?? CHECKPOINT_FORMAT_VERSION,
+      version: manifest.version ?? "unknown",
+      createdAt: manifest.createdAt ?? new Date(0).toISOString(),
+      entrypoint: manifest.entrypoint ?? "checkpoint.js",
+      routes: manifest.routes ?? [],
+      assets: normalizedAssets,
+      bundleHash: manifest.bundleHash ?? "",
+      bundleSize: manifest.bundleSize ?? 0,
+      checkpointArchivePath: manifest.checkpointArchivePath,
+      checkpointArchiveHash: manifest.checkpointArchiveHash,
+      checkpointArchiveSize: manifest.checkpointArchiveSize,
+      checkpointArchiveCodec: manifest.checkpointArchiveCodec
+    };
+  }
+}
+var DEFAULT_STORAGE_DIR = ".vector/checkpoints", ACTIVE_POINTER_FILE = "active.json";
+var init_manager = __esm(() => {
+  init_asset_store();
+  init_bundler();
+  init_entrypoint_generator();
+  init_packager();
+  init_socket_path();
+});
+
+// src/checkpoint/ipc.ts
+function parseIpcLine(line) {
+  const trimmed = line.trim();
+  if (!trimmed)
+    return null;
+  if (trimmed === "READY")
+    return { type: "ready" };
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    return null;
+  }
+}
+async function waitForReady(stdout, timeoutMs = 1e4) {
+  return new Promise((resolve5, reject) => {
+    let settled = false;
+    const reader = stdout.getReader();
+    const decoder = new TextDecoder;
+    let buffer = "";
+    function settle(fn) {
+      if (settled)
+        return;
+      settled = true;
+      clearTimeout(timer);
+      try {
+        reader.releaseLock();
+      } catch {}
+      fn();
+    }
+    const timer = setTimeout(() => {
+      settle(() => reject(new Error(`Checkpoint process did not become ready within ${timeoutMs}ms`)));
+    }, timeoutMs);
+    const processLine = (line) => {
+      const msg = parseIpcLine(line);
+      if (msg?.type === "ready") {
+        settle(() => resolve5());
+        return "ready";
+      }
+      if (msg?.type === "error") {
+        settle(() => reject(new Error(`Checkpoint process error: ${msg.message}`)));
+        return "error";
+      }
+      return "continue";
+    };
+    const processBufferLines = () => {
+      let lineEnd = buffer.indexOf(`
+`);
+      while (lineEnd !== -1) {
+        const line = buffer.slice(0, lineEnd);
+        buffer = buffer.slice(lineEnd + 1);
+        const result = processLine(line);
+        if (result !== "continue") {
+          return result;
+        }
+        lineEnd = buffer.indexOf(`
+`);
+      }
+      return "continue";
+    };
+    (async () => {
+      try {
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) {
+            buffer += decoder.decode();
+            const lastLine = buffer.trim();
+            if (lastLine.length > 0) {
+              const result2 = processLine(lastLine);
+              if (result2 !== "continue") {
+                return;
+              }
+            }
+            settle(() => reject(new Error("Checkpoint process stdout closed before READY signal")));
+            return;
+          }
+          buffer += decoder.decode(value, { stream: true });
+          if (buffer.length > MAX_PENDING_STDOUT_CHARS) {
+            settle(() => reject(new Error(`Checkpoint process stdout exceeded ${MAX_PENDING_STDOUT_CHARS} chars before READY`)));
+            return;
+          }
+          const result = processBufferLines();
+          if (result !== "continue") {
+            return;
+          }
+        }
+      } catch (err) {
+        settle(() => reject(err));
+      }
+    })();
+  });
+}
+var MAX_PENDING_STDOUT_CHARS = 1048576;
+
+// src/checkpoint/artifacts/worker-decompressor.ts
+import { availableParallelism, cpus } from "os";
+
+class CheckpointWorkerDecompressor {
+  workers = [];
+  idleWorkers = [];
+  queue = [];
+  activeJobsByWorker = new Map;
+  nextJobId = 1;
+  disposed = false;
+  constructor(workerCount = resolveDefaultWorkerCount()) {
+    const normalizedCount = normalizeWorkerCount(workerCount);
+    const workerUrl = resolveWorkerModuleUrl();
+    for (let i = 0;i < normalizedCount; i++) {
+      const worker = new Worker(workerUrl.href);
+      worker.onmessage = (event) => this.handleWorkerMessage(worker, event);
+      worker.onerror = (event) => this.handleWorkerError(worker, event);
+      this.workers.push(worker);
+      this.idleWorkers.push(worker);
+    }
+  }
+  async decompress(input, codec) {
+    if (codec === "none") {
+      return new Uint8Array(input);
+    }
+    if (this.disposed) {
+      throw new Error("Checkpoint worker decompressor is disposed");
+    }
+    const copied = new Uint8Array(input);
+    return await new Promise((resolve5, reject) => {
+      const id = this.nextJobId++;
+      this.queue.push({
+        id,
+        request: {
+          id,
+          codec,
+          input: copied.buffer
+        },
+        resolve: resolve5,
+        reject
+      });
+      this.pump();
+    });
+  }
+  async dispose() {
+    if (this.disposed) {
+      return;
+    }
+    this.disposed = true;
+    const error = new Error("Checkpoint worker decompressor disposed");
+    this.failAll(error);
+    for (const worker of this.workers) {
+      try {
+        worker.terminate();
+      } catch {}
+    }
+    this.workers = [];
+    this.idleWorkers = [];
+    this.activeJobsByWorker.clear();
+  }
+  pump() {
+    while (this.idleWorkers.length > 0 && this.queue.length > 0) {
+      const worker = this.idleWorkers.pop();
+      const job = this.queue.shift();
+      this.activeJobsByWorker.set(worker, job);
+      worker.postMessage(job.request, [job.request.input]);
+    }
+  }
+  handleWorkerMessage(worker, event) {
+    const job = this.activeJobsByWorker.get(worker);
+    this.activeJobsByWorker.delete(worker);
+    if (!this.disposed) {
+      this.idleWorkers.push(worker);
+    }
+    if (!job) {
+      this.pump();
+      return;
+    }
+    const message = event.data;
+    if (message.error) {
+      job.reject(new Error(message.error));
+    } else if (message.output instanceof ArrayBuffer) {
+      job.resolve(new Uint8Array(message.output));
+    } else {
+      job.reject(new Error("Worker returned no output"));
+    }
+    this.pump();
+  }
+  handleWorkerError(worker, event) {
+    const job = this.activeJobsByWorker.get(worker);
+    this.activeJobsByWorker.delete(worker);
+    this.idleWorkers = this.idleWorkers.filter((candidate) => candidate !== worker);
+    const message = event.message?.trim() || "Checkpoint decompression worker crashed";
+    const error = new Error(message);
+    if (job) {
+      job.reject(error);
+    }
+    this.failAll(error);
+    this.dispose().catch(() => {});
+  }
+  failAll(error) {
+    const queued = this.queue.splice(0, this.queue.length);
+    for (const job of queued) {
+      job.reject(error);
+    }
+    for (const job of this.activeJobsByWorker.values()) {
+      job.reject(error);
+    }
+    this.activeJobsByWorker.clear();
+  }
+}
+function resolveDefaultWorkerCount() {
+  const cores = resolveCoreCount();
+  const reserveForMainThread = Math.max(1, cores - 1);
+  return Math.max(1, Math.min(DEFAULT_MAX_WORKERS, reserveForMainThread));
+}
+function resolveCoreCount() {
+  try {
+    const parallelism = availableParallelism();
+    if (Number.isFinite(parallelism) && parallelism > 0) {
+      return parallelism;
+    }
+  } catch {}
+  const cpuCount = cpus().length;
+  return Number.isFinite(cpuCount) && cpuCount > 0 ? cpuCount : 1;
+}
+function normalizeWorkerCount(value) {
+  if (!Number.isFinite(value) || value <= 0) {
+    return 1;
+  }
+  return Math.max(1, Math.floor(value));
+}
+function resolveWorkerModuleUrl() {
+  if (import.meta.url.endsWith(".ts")) {
+    return new URL("./decompress-worker.ts", import.meta.url);
+  }
+  return new URL("./decompress-worker.js", import.meta.url);
+}
+var DEFAULT_MAX_WORKERS = 4;
+var init_worker_decompressor = () => {};
+
+// src/checkpoint/artifacts/materializer.ts
+import { existsSync as existsSync8, promises as fs8 } from "fs";
+import { dirname as dirname2, extname, join as join9, relative as relative6 } from "path";
+
+class CheckpointArtifactMaterializer {
+  verifyChecksums;
+  materializedDirName;
+  lockTimeoutMs;
+  constructor(options = {}) {
+    this.verifyChecksums = options.verifyChecksums ?? true;
+    this.materializedDirName = options.materializedDirName ?? DEFAULT_MATERIALIZED_DIR;
+    this.lockTimeoutMs = options.lockTimeoutMs ?? DEFAULT_LOCK_TIMEOUT_MS;
+  }
+  async materialize(manifest, storageDir) {
+    const versionDir = join9(storageDir, manifest.version);
+    const markerPath = join9(versionDir, ".assets.ready.json");
+    const lockPath = join9(versionDir, ".assets.lock");
+    const fingerprint = computeAssetFingerprint(manifest.assets);
+    if (await this.isReady(markerPath, fingerprint, manifest.assets, join9(versionDir, this.materializedDirName))) {
+      return;
+    }
+    await this.acquireLock(lockPath);
+    try {
+      if (await this.isReady(markerPath, fingerprint, manifest.assets, join9(versionDir, this.materializedDirName))) {
+        return;
+      }
+      const materializedRoot = join9(versionDir, this.materializedDirName);
+      await fs8.rm(materializedRoot, { recursive: true, force: true });
+      await fs8.mkdir(materializedRoot, { recursive: true });
+      const decompressor = new CheckpointWorkerDecompressor;
+      try {
+        for (const asset of manifest.assets) {
+          const result = await this.materializeAsset(asset, storageDir, versionDir, materializedRoot, decompressor);
+          asset.materializedPath = result;
+        }
+      } finally {
+        await decompressor.dispose();
+      }
+      const marker = {
+        fingerprint,
+        createdAt: new Date().toISOString()
+      };
+      await fs8.writeFile(markerPath, JSON.stringify(marker, null, 2), "utf-8");
+    } finally {
+      await fs8.rm(lockPath, { recursive: true, force: true });
+    }
+  }
+  async materializeAsset(asset, storageDir, versionDir, root, decompressor) {
+    const sourcePath = this.resolveSourcePath(asset, storageDir);
+    if (!existsSync8(sourcePath)) {
+      throw new Error(`Checkpoint asset blob not found: ${sourcePath}`);
+    }
+    const blob = await fs8.readFile(sourcePath);
+    const blobBytes = new Uint8Array(blob.buffer, blob.byteOffset, blob.byteLength);
+    const expectedBlobHash = asset.blobHash;
+    if (this.verifyChecksums && expectedBlobHash && sha256Hex(blobBytes) !== expectedBlobHash) {
+      throw new Error(`Checkpoint asset blob checksum mismatch for ${asset.logicalPath}`);
+    }
+    const codec = asset.codec ?? (asset.blobHash ? "gzip" : "none");
+    const contentBytes = await decompressor.decompress(blobBytes, codec);
+    const expectedContentHash = asset.contentHash ?? asset.hash;
+    if (this.verifyChecksums && expectedContentHash && sha256Hex(contentBytes) !== expectedContentHash) {
+      throw new Error(`Checkpoint asset content checksum mismatch for ${asset.logicalPath}`);
+    }
+    const cachedFile = await this.writeDecompressedCache(asset, storageDir, contentBytes);
+    const safeLogicalPath = normalizeLogicalPath(asset.logicalPath);
+    const destinationPath = join9(root, safeLogicalPath);
+    await fs8.mkdir(dirname2(destinationPath), { recursive: true });
+    await fs8.rm(destinationPath, { force: true });
+    await this.linkWithFallback(cachedFile, destinationPath);
+    return normalizePath2(relative6(versionDir, destinationPath));
+  }
+  async writeDecompressedCache(asset, storageDir, bytes) {
+    const hash = asset.contentHash ?? asset.hash;
+    const extension = extname(asset.logicalPath) || ".bin";
+    const cacheFile = join9(storageDir, "_assets/cache", `${hash}${extension}`);
+    await fs8.mkdir(dirname2(cacheFile), { recursive: true });
+    if (existsSync8(cacheFile)) {
+      if (!this.verifyChecksums) {
+        return cacheFile;
+      }
+      const existing = await fs8.readFile(cacheFile);
+      const existingBytes = new Uint8Array(existing.buffer, existing.byteOffset, existing.byteLength);
+      if (sha256Hex(existingBytes) === hash) {
+        return cacheFile;
+      }
+    }
+    await fs8.writeFile(cacheFile, bytes);
+    return cacheFile;
+  }
+  resolveSourcePath(asset, storageDir) {
+    const rawPath = asset.blobPath ?? asset.storedPath;
+    if (isAbsolutePathPortable(rawPath)) {
+      return rawPath;
+    }
+    return join9(storageDir, rawPath);
+  }
+  async linkWithFallback(sourcePath, destinationPath) {
+    try {
+      await fs8.link(sourcePath, destinationPath);
+      return;
+    } catch {}
+    try {
+      await fs8.symlink(sourcePath, destinationPath);
+      return;
+    } catch {}
+    await fs8.copyFile(sourcePath, destinationPath);
+  }
+  async acquireLock(lockPath) {
+    const deadline = Date.now() + this.lockTimeoutMs;
+    while (Date.now() < deadline) {
+      try {
+        await fs8.mkdir(lockPath);
+        return;
+      } catch (error) {
+        if (!isAlreadyExists2(error)) {
+          throw error;
+        }
+      }
+      await sleep(DEFAULT_LOCK_POLL_MS);
+    }
+    throw new Error(`Timed out waiting for checkpoint asset lock: ${lockPath}`);
+  }
+  async isReady(markerPath, fingerprint, assets, materializedRoot) {
+    if (!existsSync8(markerPath)) {
+      return false;
+    }
+    try {
+      const marker = JSON.parse(await fs8.readFile(markerPath, "utf-8"));
+      if (marker.fingerprint !== fingerprint) {
+        return false;
+      }
+      for (const asset of assets) {
+        const expectedPath = join9(materializedRoot, normalizeLogicalPath(asset.logicalPath));
+        if (!existsSync8(expectedPath)) {
+          return false;
+        }
+      }
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+function normalizePath2(path) {
+  return path.replace(/\\/g, "/");
+}
+function isAlreadyExists2(error) {
+  return typeof error === "object" && error !== null && "code" in error && error.code === "EEXIST";
+}
+function sleep(ms) {
+  return new Promise((resolve5) => setTimeout(resolve5, ms));
+}
+var DEFAULT_MATERIALIZED_DIR = "_materialized", DEFAULT_LOCK_TIMEOUT_MS = 15000, DEFAULT_LOCK_POLL_MS = 50;
+var init_materializer = __esm(() => {
+  init_manifest();
+  init_worker_decompressor();
+});
+
+// src/checkpoint/process-manager.ts
+var exports_process_manager = {};
+__export(exports_process_manager, {
+  CheckpointProcessManager: () => CheckpointProcessManager
+});
+import { existsSync as existsSync9, promises as fs9, unlinkSync } from "fs";
+import { dirname as dirname3, join as join10 } from "path";
+
+class CheckpointProcessManager {
+  running = new Map;
+  pending = new Map;
+  readyTimeoutMs;
+  idleTimeoutMs;
+  idleTimers = new Map;
+  lastUsedAt = new Map;
+  materializer;
+  constructor(options = DEFAULT_READY_TIMEOUT_MS) {
+    if (typeof options === "number") {
+      this.readyTimeoutMs = options;
+      this.idleTimeoutMs = DEFAULT_IDLE_TIMEOUT_MS;
+    } else {
+      this.readyTimeoutMs = options.readyTimeoutMs ?? DEFAULT_READY_TIMEOUT_MS;
+      this.idleTimeoutMs = options.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS;
+    }
+    this.materializer = new CheckpointArtifactMaterializer;
+  }
+  async spawn(manifest, storageDir) {
+    if (this.running.has(manifest.version)) {
+      return this.running.get(manifest.version);
+    }
+    if (this.pending.has(manifest.version)) {
+      return this.pending.get(manifest.version);
+    }
+    const promise = this.doSpawn(manifest, storageDir);
+    this.pending.set(manifest.version, promise);
+    try {
+      const result = await promise;
+      return result;
+    } finally {
+      this.pending.delete(manifest.version);
+    }
+  }
+  async doSpawn(manifest, storageDir) {
+    const versionDir = join10(storageDir, manifest.version);
+    const bundlePath = join10(versionDir, manifest.entrypoint);
+    const socketPath = resolveCheckpointSocketPath(storageDir, manifest.version);
+    if (!existsSync9(bundlePath)) {
+      throw new Error(`Checkpoint bundle not found: ${bundlePath}`);
+    }
+    await this.materializer.materialize(manifest, storageDir);
+    await fs9.mkdir(dirname3(socketPath), { recursive: true });
+    this.tryUnlinkSocket(socketPath);
+    const proc = Bun.spawn(["bun", "run", bundlePath], {
+      env: {
+        ...process.env,
+        VECTOR_CHECKPOINT_SOCKET: socketPath,
+        VECTOR_CHECKPOINT_VERSION: manifest.version
+      },
+      stdout: "pipe",
+      stderr: "inherit"
+    });
+    if (!proc.stdout) {
+      proc.kill("SIGTERM");
+      throw new Error(`Checkpoint process for ${manifest.version} did not provide stdout`);
+    }
+    try {
+      await waitForReady(proc.stdout, this.readyTimeoutMs);
+    } catch (err) {
+      proc.kill("SIGTERM");
+      throw err;
+    }
+    const spawned = {
+      version: manifest.version,
+      socketPath,
+      process: proc,
+      pid: proc.pid
+    };
+    this.running.set(manifest.version, spawned);
+    this.lastUsedAt.set(manifest.version, Date.now());
+    this.scheduleIdleCheck(manifest.version);
+    return spawned;
+  }
+  markUsed(version) {
+    if (!this.running.has(version)) {
+      return;
+    }
+    this.lastUsedAt.set(version, Date.now());
+  }
+  async stop(version) {
+    const snap = this.running.get(version);
+    if (!snap)
+      return;
+    this.running.delete(version);
+    this.clearIdleTimer(version);
+    this.lastUsedAt.delete(version);
+    snap.process.kill("SIGTERM");
+    const exited = await Promise.race([
+      snap.process.exited.then(() => true),
+      new Promise((resolve5) => setTimeout(() => resolve5(false), STOP_TIMEOUT_MS))
+    ]);
+    if (!exited) {
+      try {
+        snap.process.kill("SIGKILL");
+        await snap.process.exited;
+      } catch {}
+    }
+    this.tryUnlinkSocket(snap.socketPath);
+  }
+  async stopAll() {
+    const versions = [...this.running.keys()];
+    for (const version of versions) {
+      await this.stop(version);
+    }
+  }
+  isRunning(version) {
+    return this.running.has(version);
+  }
+  getRunning(version) {
+    return this.running.get(version);
+  }
+  async health(version) {
+    const snap = this.running.get(version);
+    if (!snap)
+      return false;
+    try {
+      const response = await fetch("http://localhost/_vector/health", {
+        unix: snap.socketPath,
+        signal: AbortSignal.timeout(2000)
+      });
+      return response.ok;
+    } catch {
+      return false;
+    }
+  }
+  getRunningVersions() {
+    return [...this.running.keys()];
+  }
+  scheduleIdleCheck(version, delayMs = this.idleTimeoutMs) {
+    this.clearIdleTimer(version);
+    if (this.idleTimeoutMs <= 0) {
+      return;
+    }
+    const timer = setTimeout(() => {
+      this.handleIdleCheck(version);
+    }, Math.max(1, delayMs));
+    if (typeof timer.unref === "function") {
+      timer.unref();
+    }
+    this.idleTimers.set(version, timer);
+  }
+  async handleIdleCheck(version) {
+    if (!this.running.has(version)) {
+      return;
+    }
+    const lastUsedAt = this.lastUsedAt.get(version) ?? 0;
+    const idleForMs = Date.now() - lastUsedAt;
+    const remainingMs = this.idleTimeoutMs - idleForMs;
+    if (remainingMs > 0) {
+      this.scheduleIdleCheck(version, remainingMs);
+      return;
+    }
+    try {
+      await this.stop(version);
+    } catch (error) {
+      console.error(`[CheckpointProcessManager] Failed to stop idle checkpoint ${version}:`, error);
+    }
+  }
+  clearIdleTimer(version) {
+    const timer = this.idleTimers.get(version);
+    if (!timer) {
+      return;
+    }
+    clearTimeout(timer);
+    this.idleTimers.delete(version);
+  }
+  tryUnlinkSocket(socketPath) {
+    try {
+      if (existsSync9(socketPath)) {
+        unlinkSync(socketPath);
+      }
+    } catch {}
+  }
+}
+var DEFAULT_READY_TIMEOUT_MS = 1e4, DEFAULT_IDLE_TIMEOUT_MS, STOP_TIMEOUT_MS = 5000;
+var init_process_manager = __esm(() => {
+  init_materializer();
+  init_socket_path();
+  DEFAULT_IDLE_TIMEOUT_MS = 10 * 60 * 1000;
+});
+
+// src/checkpoint/resolver.ts
+var exports_resolver = {};
+__export(exports_resolver, {
+  CheckpointResolver: () => CheckpointResolver
+});
+
+class CheckpointResolver {
+  manager;
+  processManager;
+  versionHeader;
+  cacheKeyOverride;
+  allowFallbackVersionHeader;
+  pendingVersionResolves = new Map;
+  constructor(manager, processManager, options = {}) {
+    this.manager = manager;
+    this.processManager = processManager;
+    this.versionHeader = normalizeHeaderName(options.versionHeader ?? DEFAULT_VERSION_HEADER);
+    this.cacheKeyOverride = options.cacheKeyOverride === true;
+    this.allowFallbackVersionHeader = options.versionHeader === undefined;
+  }
+  async resolve(request) {
+    const requestedVersion = this.getRequestedVersion(request);
+    if (!requestedVersion) {
+      return null;
+    }
+    return await this.resolveVersion(requestedVersion);
+  }
+  getRequestedVersion(request) {
+    return this.getRequestedHeader(request)?.value ?? null;
+  }
+  getCacheKeyOverrideValue(request) {
+    if (!this.cacheKeyOverride) {
+      return null;
+    }
+    const requestedHeader = this.getRequestedHeader(request);
+    if (!requestedHeader) {
+      return null;
+    }
+    return `${requestedHeader.name}:${requestedHeader.value}`;
+  }
+  getRequestedHeader(request) {
+    const primary = request.headers.get(this.versionHeader);
+    if (primary && primary.trim().length > 0) {
+      return { name: this.versionHeader, value: primary.trim() };
+    }
+    if (this.allowFallbackVersionHeader && this.versionHeader !== FALLBACK_VERSION_HEADER) {
+      const fallback = request.headers.get(FALLBACK_VERSION_HEADER);
+      if (fallback && fallback.trim().length > 0) {
+        return { name: FALLBACK_VERSION_HEADER, value: fallback.trim() };
+      }
+    }
+    return null;
+  }
+  async resolveVersion(version) {
+    let running = this.processManager.getRunning(version);
+    if (!running) {
+      const pending = this.pendingVersionResolves.get(version);
+      if (pending) {
+        const socketPath2 = await pending;
+        if (!socketPath2) {
+          return null;
+        }
+        this.processManager.markUsed(version);
+        return socketPath2;
+      }
+      const pendingResolve = (async () => {
+        try {
+          const manifest = await this.manager.readManifest(version);
+          const spawned = await this.processManager.spawn(manifest, this.manager.getStorageDir());
+          return spawned.socketPath;
+        } catch {
+          return null;
+        }
+      })();
+      this.pendingVersionResolves.set(version, pendingResolve);
+      const socketPath = await pendingResolve;
+      this.pendingVersionResolves.delete(version);
+      if (!socketPath) {
+        return null;
+      }
+      this.processManager.markUsed(version);
+      return socketPath;
+    }
+    this.processManager.markUsed(version);
+    return running.socketPath;
+  }
+  invalidateCache() {}
+}
+function normalizeHeaderName(value) {
+  const normalized = value.trim().toLowerCase();
+  return normalized.length > 0 ? normalized : DEFAULT_VERSION_HEADER;
+}
+var DEFAULT_VERSION_HEADER = "x-vector-checkpoint-version", FALLBACK_VERSION_HEADER = "x-vector-checkpoint";
+
+// src/checkpoint/forwarder.ts
+var exports_forwarder = {};
+__export(exports_forwarder, {
+  CheckpointForwarder: () => CheckpointForwarder,
+  CHECKPOINT_CONTEXT_HEADER: () => CHECKPOINT_CONTEXT_HEADER
+});
+
+class CheckpointForwarder {
+  async forward(request, socketPath, contextPayload) {
+    try {
+      const encodedContext = encodeCheckpointContext(contextPayload);
+      const headers = buildForwardHeaders(request.headers, encodedContext);
+      const response = await fetch(request.url, {
+        method: request.method,
+        headers,
+        body: request.body,
+        unix: socketPath,
+        duplex: request.body ? "half" : undefined
+      });
+      return new Response(response.body, {
+        status: response.status,
+        statusText: response.statusText,
+        headers: new Headers(response.headers)
+      });
+    } catch (error) {
+      console.error("[CheckpointForwarder] Forward failed:", error);
+      return new Response(JSON.stringify({ error: true, message: "Checkpoint unavailable", statusCode: 503 }), {
+        status: 503,
+        headers: { "content-type": "application/json" }
+      });
+    }
+  }
+}
+function buildForwardHeaders(source, encodedContext) {
+  const headers = new Headers(source);
+  stripHopByHopHeaders(headers);
+  if (encodedContext) {
+    headers.set(CHECKPOINT_CONTEXT_HEADER, encodedContext);
+  }
+  return headers;
+}
+function stripHopByHopHeaders(headers) {
+  const connectionValue = headers.get("connection");
+  if (connectionValue) {
+    for (const token of connectionValue.split(",")) {
+      const normalized = token.trim().toLowerCase();
+      if (normalized) {
+        headers.delete(normalized);
+      }
+    }
+  }
+  headers.delete("connection");
+  headers.delete("keep-alive");
+  headers.delete("proxy-authenticate");
+  headers.delete("proxy-authorization");
+  headers.delete("te");
+  headers.delete("trailer");
+  headers.delete("transfer-encoding");
+  headers.delete("upgrade");
+}
+function encodeCheckpointContext(contextPayload) {
+  if (!contextPayload) {
+    return null;
+  }
+  const keys = Object.keys(contextPayload);
+  if (keys.length === 0) {
+    return null;
+  }
+  try {
+    return Buffer.from(JSON.stringify(contextPayload), "utf-8").toString("base64url");
+  } catch {
+    return null;
+  }
+}
+var CHECKPOINT_CONTEXT_HEADER = "x-vector-checkpoint-context";
+
+// src/checkpoint/gateway.ts
+var exports_gateway = {};
+__export(exports_gateway, {
+  CheckpointGateway: () => CheckpointGateway
+});
+
+class CheckpointGateway {
+  resolver;
+  forwarder;
+  constructor(resolver, forwarder) {
+    this.resolver = resolver;
+    this.forwarder = forwarder;
+  }
+  getRequestedVersion(request) {
+    return this.resolver.getRequestedVersion(request);
+  }
+  getCacheKeyOverrideValue(request) {
+    return this.resolver.getCacheKeyOverrideValue(request);
+  }
+  async handle(request, contextPayload) {
+    const requestedVersion = this.getRequestedVersion(request);
+    const socketPath = await this.resolver.resolve(request);
+    if (!socketPath) {
+      if (requestedVersion) {
+        return new Response(JSON.stringify({
+          error: true,
+          message: `Requested checkpoint version "${requestedVersion}" is unavailable`,
+          statusCode: 503
+        }), { status: 503, headers: { "content-type": "application/json" } });
+      }
+      return null;
+    }
+    return await this.forwarder.forward(request, socketPath, contextPayload);
+  }
+}
+
+// src/checkpoint/cli.ts
+var exports_cli = {};
+__export(exports_cli, {
+  runCheckpointCli: () => runCheckpointCli
+});
+import { parseArgs } from "util";
+async function runCheckpointCli(argv) {
+  const subcommand = argv[0];
+  switch (subcommand) {
+    case "publish":
+      return await cliPublish(argv.slice(1));
+    case "list":
+      return await cliList(argv.slice(1));
+    case "rollback":
+      return await cliRollback(argv.slice(1));
+    case "remove":
+      return await cliRemove(argv.slice(1));
+    default:
+      printCheckpointHelp();
+      if (subcommand) {
+        console.error(`
+Unknown checkpoint command: ${subcommand}`);
+      }
+      process.exit(1);
+  }
+}
+async function cliPublish(args) {
+  const { values } = parseArgs({
+    args,
+    options: {
+      version: { type: "string", short: "v" },
+      routes: { type: "string", short: "r", default: "./routes" },
+      storage: { type: "string", short: "s" }
+    },
+    strict: true
+  });
+  if (!values.version) {
+    console.error("Error: --version is required for publish");
+    console.error("Usage: vector checkpoint publish --version <ver> [--routes <dir>]");
+    process.exit(1);
+  }
+  const manager = new CheckpointManager(values.storage ? { storageDir: values.storage } : undefined);
+  try {
+    console.log(`Publishing checkpoint ${values.version}...`);
+    const manifest = await manager.publish({
+      version: values.version,
+      routesDir: values.routes
+    });
+    console.log(`Checkpoint ${manifest.version} published successfully.`);
+    console.log(`  Bundle hash: ${manifest.bundleHash.slice(0, 12)}...`);
+    console.log(`  Bundle size: ${formatBytes2(manifest.bundleSize)}`);
+    console.log(`  Routes: ${manifest.routes.length}`);
+    console.log(`  Assets: ${manifest.assets.length}`);
+  } catch (err) {
+    console.error(`Failed to publish checkpoint: ${err.message}`);
+    process.exit(1);
+  }
+}
+async function cliList(args) {
+  const { values } = parseArgs({
+    args,
+    options: {
+      storage: { type: "string", short: "s" }
+    },
+    strict: true
+  });
+  const manager = new CheckpointManager(values.storage ? { storageDir: values.storage } : undefined);
+  const manifests = await manager.listVersions();
+  const active = await manager.getActive();
+  if (manifests.length === 0) {
+    console.log("No checkpoints found.");
+    return;
+  }
+  console.log("");
+  console.log("  Version      Created                    Bundle Hash     Size       Status");
+  console.log("  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
+  for (const m of manifests) {
+    const isActive = active?.version === m.version;
+    const status = isActive ? "\u25CF active" : "  ";
+    const hash = m.bundleHash.slice(0, 12);
+    const size = formatBytes2(m.bundleSize).padEnd(10);
+    const created = new Date(m.createdAt).toISOString().replace("T", " ").slice(0, 19);
+    console.log(`  ${m.version.padEnd(12)} ${created}   ${hash}...   ${size} ${status}`);
+  }
+  console.log("");
+}
+async function cliRollback(args) {
+  const { positionals, values } = parseArgs({
+    args,
+    options: {
+      storage: { type: "string", short: "s" }
+    },
+    strict: true,
+    allowPositionals: true
+  });
+  const version = positionals[0];
+  if (!version) {
+    console.error("Error: version argument is required");
+    console.error("Usage: vector checkpoint rollback <version>");
+    process.exit(1);
+  }
+  const manager = new CheckpointManager(values.storage ? { storageDir: values.storage } : undefined);
+  try {
+    await manager.setActive(version);
+    console.log(`Active checkpoint set to ${version}.`);
+    console.log("Note: Restart the server for the change to take effect.");
+  } catch (err) {
+    console.error(`Failed to rollback: ${err.message}`);
+    process.exit(1);
+  }
+}
+async function cliRemove(args) {
+  const { positionals, values } = parseArgs({
+    args,
+    options: {
+      storage: { type: "string", short: "s" }
+    },
+    strict: true,
+    allowPositionals: true
+  });
+  const version = positionals[0];
+  if (!version) {
+    console.error("Error: version argument is required");
+    console.error("Usage: vector checkpoint remove <version>");
+    process.exit(1);
+  }
+  const manager = new CheckpointManager(values.storage ? { storageDir: values.storage } : undefined);
+  try {
+    await manager.remove(version);
+    console.log(`Checkpoint ${version} removed.`);
+  } catch (err) {
+    console.error(`Failed to remove checkpoint: ${err.message}`);
+    process.exit(1);
+  }
+}
+function printCheckpointHelp() {
+  console.log(`
+Usage: vector checkpoint <command>
+
+Commands:
+  publish   --version <ver> [--routes <dir>]   Build and store a checkpoint
+  list                                          List all stored checkpoints
+  rollback  <version>                           Activate a specific checkpoint
+  remove    <version>                           Delete a checkpoint
+
+Options:
+  -v, --version   Semver version string (e.g. 1.2.0)
+  -r, --routes    Routes directory (default: ./routes)
+  -s, --storage   Checkpoint storage dir (default: .vector/checkpoints)
+`);
+}
+function formatBytes2(bytes) {
+  if (bytes < 1024)
+    return `${bytes} B`;
+  if (bytes < 1024 * 1024)
+    return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+var init_cli = __esm(() => {
+  init_manager();
+});
 
 // src/cli/index.ts
 import { watch } from "fs";
-import { parseArgs } from "util";
+import { parseArgs as parseArgs2 } from "util";
 
 // src/cli/option-resolution.ts
 function resolveRoutesDir(configRoutesDir, hasRoutesOption, cliRoutes) {
@@ -100,7 +1898,7 @@ class ConfigLoader {
     if (existsSync(this.configPath)) {
       try {
         const userConfigPath = toFileUrl(this.configPath);
-        const userConfig = await import(userConfigPath);
+        const userConfig = await import(`${userConfigPath}?t=${Date.now()}`);
         this.config = userConfig.default || userConfig;
         this.configSource = "user";
       } catch (error) {
@@ -120,7 +1918,7 @@ class ConfigLoader {
   async buildLegacyConfig() {
     const config = {};
     if (this.config) {
-      config.port = this.config.port;
+      config.port = this.normalizePort(this.config.port);
       config.hostname = this.config.hostname;
       config.reusePort = this.config.reusePort;
       config.development = this.config.development;
@@ -131,6 +1929,7 @@ class ConfigLoader {
       config.openapi = this.config.openapi;
       config.startup = this.config.startup;
       config.shutdown = this.config.shutdown;
+      config.checkpoint = this.config.checkpoint;
     }
     config.autoDiscover = true;
     if (this.config?.cors) {
@@ -155,6 +1954,12 @@ class ConfigLoader {
     }
     return config;
   }
+  normalizePort(port) {
+    if (port === undefined) {
+      return;
+    }
+    return Number(port);
+  }
   async loadAuthHandler() {
     return this.config?.auth || null;
   }
@@ -257,23 +2062,26 @@ class AuthManager {
   clearProtectedHandler() {
     this.protectedHandler = null;
   }
-  async authenticate(request) {
+  async authenticate(context) {
     if (!this.protectedHandler) {
       throw new Error("Protected handler not configured. Use vector.protected() to set authentication handler.");
     }
+    if (!context || typeof context !== "object" || !context.request) {
+      throw new Error("Authentication context is invalid: missing request");
+    }
     try {
-      const authUser = await this.protectedHandler(request);
-      request.authUser = authUser;
+      const authUser = await this.protectedHandler(context);
+      context.authUser = authUser;
       return authUser;
     } catch (error) {
       throw new Error(`Authentication failed: ${error instanceof Error ? error.message : String(error)}`);
     }
   }
-  isAuthenticated(request) {
-    return !!request.authUser;
+  isAuthenticated(context) {
+    return !!context.authUser;
   }
-  getUser(request) {
-    return request.authUser || null;
+  getUser(context) {
+    return context.authUser || null;
   }
 }
 
@@ -302,10 +2110,11 @@ class CacheManager {
     const now = Date.now();
     const cached = this.memoryCache.get(key);
     if (this.isCacheValid(cached, now)) {
-      return cached.value;
+      return this.cloneCachedValue(cached.value);
     }
     if (this.inflight.has(key)) {
-      return await this.inflight.get(key);
+      const inflightValue = await this.inflight.get(key);
+      return this.cloneCachedValue(inflightValue);
     }
     const promise = (async () => {
       const value = await factory();
@@ -324,15 +2133,31 @@ class CacheManager {
   }
   setInMemoryCache(key, value, ttl) {
     const expires = Date.now() + ttl * 1000;
-    this.memoryCache.set(key, { value, expires });
+    this.memoryCache.set(key, { value: this.cloneForStore(value), expires });
     this.scheduleCleanup();
   }
+  cloneForStore(value) {
+    if (value instanceof Response) {
+      return value.clone();
+    }
+    return value;
+  }
+  cloneCachedValue(value) {
+    if (value instanceof Response) {
+      return value.clone();
+    }
+    return value;
+  }
   scheduleCleanup() {
     if (this.cleanupInterval)
       return;
-    this.cleanupInterval = setInterval(() => {
+    const timer = setInterval(() => {
       this.cleanupExpired();
     }, 60000);
+    if (typeof timer.unref === "function") {
+      timer.unref();
+    }
+    this.cleanupInterval = timer;
   }
   cleanupExpired() {
     const now = Date.now();
@@ -530,7 +2355,7 @@ class RouteScanner {
         const routePath = relative2(this.routesDir, fullPath).replace(/\.(ts|js)$/, "").split(sep).join("/");
         try {
           const importPath = process.platform === "win32" ? `file:///${fullPath.replace(/\\/g, "/")}` : fullPath;
-          const module = await import(importPath);
+          const module = await import(`${importPath}?t=${Date.now()}`);
           if (module.default && typeof module.default === "function") {
             routes.push({
               name: "default",
@@ -594,26 +2419,27 @@ class MiddlewareManager {
   addFinally(...handlers) {
     this.finallyHandlers.push(...handlers);
   }
-  async executeBefore(request) {
+  async executeBefore(context) {
     if (this.beforeHandlers.length === 0)
-      return request;
-    let currentRequest = request;
+      return null;
     for (const handler of this.beforeHandlers) {
-      const result = await handler(currentRequest);
+      const result = await handler(context);
       if (result instanceof Response) {
         return result;
       }
-      currentRequest = result;
+      if (result !== undefined) {
+        throw new TypeError("Before middleware must return void or Response");
+      }
     }
-    return currentRequest;
+    return null;
   }
-  async executeFinally(response, request) {
+  async executeFinally(response, context) {
     if (this.finallyHandlers.length === 0)
       return response;
     let currentResponse = response;
     for (const handler of this.finallyHandlers) {
       try {
-        currentResponse = await handler(currentResponse, request);
+        currentResponse = await handler(currentResponse, context);
       } catch (error) {
         console.error("After middleware error:", error);
       }
@@ -644,6 +2470,52 @@ function stringifyData(data) {
     throw e;
   }
 }
+function isJsonContentType(contentType) {
+  const mimeType = contentType.split(";", 1)[0] ?? contentType;
+  return mimeType.trim().toLowerCase() === CONTENT_TYPES.JSON;
+}
+function serializeCookie(cookie) {
+  const segments = [`${cookie.name}=${cookie.value}`];
+  if (cookie.maxAge !== undefined && Number.isFinite(cookie.maxAge)) {
+    segments.push(`Max-Age=${Math.trunc(cookie.maxAge)}`);
+  }
+  if (cookie.domain) {
+    segments.push(`Domain=${cookie.domain}`);
+  }
+  if (cookie.path) {
+    segments.push(`Path=${cookie.path}`);
+  }
+  if (cookie.expires !== undefined) {
+    const expiresAt = cookie.expires instanceof Date ? cookie.expires : new Date(cookie.expires);
+    if (!Number.isNaN(expiresAt.getTime())) {
+      segments.push(`Expires=${expiresAt.toUTCString()}`);
+    }
+  }
+  if (cookie.httpOnly) {
+    segments.push("HttpOnly");
+  }
+  if (cookie.secure) {
+    segments.push("Secure");
+  }
+  if (cookie.sameSite) {
+    segments.push(`SameSite=${cookie.sameSite}`);
+  }
+  if (cookie.partitioned) {
+    segments.push("Partitioned");
+  }
+  if (cookie.priority) {
+    segments.push(`Priority=${cookie.priority}`);
+  }
+  return segments.join("; ");
+}
+function appendSetCookieHeaders(headers, cookies) {
+  if (!cookies || cookies.length === 0) {
+    return;
+  }
+  for (const cookie of cookies) {
+    headers.append("set-cookie", typeof cookie === "string" ? cookie : serializeCookie(cookie));
+  }
+}
 function createErrorResponse(code, message, contentType) {
   const errorBody = {
     error: true,
@@ -698,14 +2570,34 @@ var APIError = {
   maintenance: (msg = "Service Under Maintenance", contentType) => createErrorResponse(503, msg, contentType),
   custom: (statusCode, msg, contentType) => createErrorResponse(statusCode, msg, contentType)
 };
-function createResponse(statusCode, data, contentType = CONTENT_TYPES.JSON) {
-  const body = contentType === CONTENT_TYPES.JSON ? stringifyData(data) : data;
+function createResponse(statusCode, data, optionsOrContentType = CONTENT_TYPES.JSON) {
+  const options = typeof optionsOrContentType === "string" ? { contentType: optionsOrContentType } : optionsOrContentType ?? {};
+  const headers = new Headers(options.headers);
+  const contentType = options.contentType ?? headers.get("content-type") ?? CONTENT_TYPES.JSON;
+  if (options.contentType || !headers.has("content-type")) {
+    headers.set("content-type", contentType);
+  }
+  appendSetCookieHeaders(headers, options.cookies);
+  const body = isJsonContentType(contentType) ? stringifyData(data) : data;
   return new Response(body, {
     status: statusCode,
-    headers: { "content-type": contentType }
+    statusText: options.statusText,
+    headers
   });
 }
 
+// src/types/index.ts
+var AuthKind;
+((AuthKind2) => {
+  AuthKind2["ApiKey"] = "ApiKey";
+  AuthKind2["HttpBasic"] = "HttpBasic";
+  AuthKind2["HttpBearer"] = "HttpBearer";
+  AuthKind2["HttpDigest"] = "HttpDigest";
+  AuthKind2["OAuth2"] = "OAuth2";
+  AuthKind2["OpenIdConnect"] = "OpenIdConnect";
+  AuthKind2["MutualTls"] = "MutualTls";
+})(AuthKind ||= {});
+
 // src/utils/schema-validation.ts
 function isStandardRouteSchema(schema) {
   const standard = schema?.["~standard"];
@@ -783,6 +2675,11 @@ function createValidationErrorPayload(target, issues) {
 }
 
 // src/core/router.ts
+var AUTH_KIND_VALUES = new Set(Object.values(AuthKind));
+function isAuthKindValue(value) {
+  return typeof value === "string" && AUTH_KIND_VALUES.has(value);
+}
+
 class VectorRouter {
   middlewareManager;
   authManager;
@@ -794,6 +2691,7 @@ class VectorRouter {
   routeMatchers = [];
   corsHeadersEntries = null;
   corsHandler = null;
+  checkpointGateway = null;
   constructor(middlewareManager, authManager, cacheManager) {
     this.middlewareManager = middlewareManager;
     this.authManager = authManager;
@@ -805,6 +2703,9 @@ class VectorRouter {
   setCorsHandler(handler) {
     this.corsHandler = handler;
   }
+  setCheckpointGateway(gateway) {
+    this.checkpointGateway = gateway;
+  }
   setRouteBooleanDefaults(defaults) {
     this.routeBooleanDefaults = { ...defaults };
   }
@@ -820,6 +2721,9 @@ class VectorRouter {
         resolved[key] = defaults[key];
       }
     }
+    if (resolved.auth === true && isAuthKindValue(defaults.auth)) {
+      resolved.auth = defaults.auth;
+    }
     return resolved;
   }
   route(options, handler) {
@@ -896,218 +2800,279 @@ class VectorRouter {
     } catch {
       return APIError.badRequest("Malformed request URL");
     }
-    request._parsedUrl = url;
     const pathname = url.pathname;
+    const exactPathRoute = this.routeTable[pathname];
+    if (exactPathRoute) {
+      if (exactPathRoute instanceof Response) {
+        return this.applyCorsResponse(exactPathRoute.clone(), request);
+      }
+      const exactPathMethodMap = exactPathRoute;
+      const handler = exactPathMethodMap[request.method] ?? (request.method === "HEAD" ? exactPathMethodMap["GET"] : undefined);
+      if (handler) {
+        const response = await handler(request);
+        if (response) {
+          return response;
+        }
+      }
+    }
     for (const matcher of this.routeMatchers) {
       const path = matcher.path;
-      const value = this.routeTable[path];
-      if (!value)
+      const routeEntry = this.routeTable[path];
+      if (!routeEntry)
         continue;
-      if (value instanceof Response)
-        continue;
-      const methodMap = value;
-      if (request.method === "OPTIONS" || request.method in methodMap) {
-        const match = pathname.match(matcher.regex);
-        if (match) {
-          try {
-            request.params = match.groups ?? {};
-          } catch {}
-          const handler = methodMap[request.method] ?? methodMap["GET"];
-          if (handler) {
-            const response = await handler(request);
-            if (response)
-              return response;
-          }
+      if (routeEntry instanceof Response) {
+        if (pathname === path) {
+          return this.applyCorsResponse(routeEntry.clone(), request);
         }
+        continue;
+      }
+      const methodMap = routeEntry;
+      const handler = methodMap[request.method] ?? (request.method === "HEAD" ? methodMap["GET"] : undefined);
+      if (!handler) {
+        continue;
+      }
+      const match = pathname.match(matcher.regex);
+      if (!match) {
+        continue;
       }
+      const response = await handler(request);
+      if (response)
+        return response;
     }
-    return STATIC_RESPONSES.NOT_FOUND.clone();
+    return this.applyCorsResponse(STATIC_RESPONSES.NOT_FOUND.clone(), request);
   }
-  prepareRequest(request, options) {
-    if (!request.context) {
-      request.context = {};
-    }
-    const hasEmptyParamsObject = !!request.params && typeof request.params === "object" && !Array.isArray(request.params) && Object.keys(request.params).length === 0;
-    if (options?.params !== undefined && (request.params === undefined || hasEmptyParamsObject)) {
-      try {
-        request.params = options.params;
-      } catch {}
+  cloneMetadata(value) {
+    if (Array.isArray(value)) {
+      return [...value];
     }
-    if (options?.route !== undefined) {
-      request.route = options.route;
+    if (value && typeof value === "object") {
+      return { ...value };
     }
-    if (options?.metadata !== undefined) {
-      request.metadata = options.metadata;
-    }
-    if (request.query == null && request.url) {
-      try {
-        Object.defineProperty(request, "query", {
-          get() {
-            const url = this._parsedUrl ?? new URL(this.url);
-            const query = VectorRouter.parseQuery(url);
-            Object.defineProperty(this, "query", {
-              value: query,
-              writable: true,
-              configurable: true,
-              enumerable: true
-            });
-            return query;
-          },
-          set(value) {
-            Object.defineProperty(this, "query", {
-              value,
-              writable: true,
-              configurable: true,
-              enumerable: true
-            });
-          },
-          configurable: true,
-          enumerable: true
-        });
-      } catch {
-        const url = request._parsedUrl ?? new URL(request.url);
-        try {
-          request.query = VectorRouter.parseQuery(url);
-        } catch {}
+    return value;
+  }
+  createContext(request, options) {
+    const context = {
+      request
+    };
+    this.setContextField(context, "metadata", options?.metadata !== undefined ? this.cloneMetadata(options.metadata) : {});
+    this.setContextField(context, "params", options?.params ?? {});
+    this.setContextField(context, "query", options?.query ?? {});
+    this.setContextField(context, "cookies", options?.cookies ?? {});
+    return context;
+  }
+  setContextField(context, key, value) {
+    context[key] = value;
+  }
+  hasOwnContextField(context, key) {
+    return Object.prototype.hasOwnProperty.call(context, key);
+  }
+  buildCheckpointContextPayload(context) {
+    const payload = {};
+    const allowedKeys = ["metadata", "content", "validatedInput", "authUser"];
+    for (const key of allowedKeys) {
+      if (!this.hasOwnContextField(context, key)) {
+        continue;
       }
+      const value = context[key];
+      if (typeof value === "function" || typeof value === "symbol" || value === undefined) {
+        continue;
+      }
+      payload[key] = value;
     }
-    if (!Object.getOwnPropertyDescriptor(request, "cookies")) {
-      Object.defineProperty(request, "cookies", {
-        get() {
-          const cookieHeader = this.headers.get("cookie") ?? "";
-          const cookies = {};
-          if (cookieHeader) {
-            for (const pair of cookieHeader.split(";")) {
-              const idx = pair.indexOf("=");
-              if (idx > 0) {
-                cookies[pair.slice(0, idx).trim()] = pair.slice(idx + 1).trim();
-              }
-            }
-          }
-          Object.defineProperty(this, "cookies", {
-            value: cookies,
-            writable: true,
-            configurable: true,
-            enumerable: true
-          });
-          return cookies;
-        },
-        configurable: true,
-        enumerable: true
-      });
-    }
+    return payload;
   }
-  resolveFallbackParams(request, routeMatcher) {
+  resolveFallbackParams(pathname, routeMatcher) {
     if (!routeMatcher) {
       return;
     }
-    const currentParams = request.params;
-    if (currentParams && typeof currentParams === "object" && !Array.isArray(currentParams) && Object.keys(currentParams).length > 0) {
+    const matched = pathname.match(routeMatcher);
+    if (!matched?.groups) {
       return;
     }
-    let pathname;
+    return matched.groups;
+  }
+  getRequestedCheckpointVersion(request) {
+    if (!this.checkpointGateway) {
+      return null;
+    }
+    const gateway = this.checkpointGateway;
+    if (gateway?.getRequestedVersion) {
+      return gateway.getRequestedVersion(request);
+    }
+    const primary = request.headers.get("x-vector-checkpoint-version");
+    if (primary && primary.trim().length > 0) {
+      return primary.trim();
+    }
+    const fallback = request.headers.get("x-vector-checkpoint");
+    if (fallback && fallback.trim().length > 0) {
+      return fallback.trim();
+    }
+    return null;
+  }
+  getCheckpointCacheKeyOverrideValue(request) {
+    if (!this.checkpointGateway) {
+      return null;
+    }
+    const gateway = this.checkpointGateway;
+    if (gateway?.getCacheKeyOverrideValue) {
+      return gateway.getCacheKeyOverrideValue(request);
+    }
+    const primary = request.headers.get("x-vector-checkpoint-version");
+    if (primary && primary.trim().length > 0) {
+      return `x-vector-checkpoint-version:${primary.trim()}`;
+    }
+    const fallback = request.headers.get("x-vector-checkpoint");
+    if (fallback && fallback.trim().length > 0) {
+      return `x-vector-checkpoint:${fallback.trim()}`;
+    }
+    return null;
+  }
+  applyCheckpointCacheNamespace(cacheKey, request) {
+    const checkpointVersion = this.getRequestedCheckpointVersion(request);
+    if (!checkpointVersion) {
+      return cacheKey;
+    }
+    return `${cacheKey}:checkpoint=${checkpointVersion}`;
+  }
+  applyCheckpointRouteKeyOverride(cacheKey, request) {
+    const override = this.getCheckpointCacheKeyOverrideValue(request);
+    if (!override) {
+      return cacheKey;
+    }
+    return override;
+  }
+  async parseRequestBodyForContext(context, request, checkpointRequested) {
+    let parsedContent = null;
     try {
-      pathname = (request._parsedUrl ?? new URL(request.url)).pathname;
+      const bodyReadRequest = checkpointRequested ? request.clone() : request;
+      const contentType = bodyReadRequest.headers.get("content-type");
+      if (contentType?.startsWith("application/json")) {
+        parsedContent = await bodyReadRequest.json();
+      } else if (contentType?.startsWith("application/x-www-form-urlencoded")) {
+        parsedContent = Object.fromEntries(await bodyReadRequest.formData());
+      } else if (contentType?.startsWith("multipart/form-data")) {
+        parsedContent = await bodyReadRequest.formData();
+      } else {
+        parsedContent = await bodyReadRequest.text();
+      }
     } catch {
-      return;
+      parsedContent = null;
     }
-    const matched = pathname.match(routeMatcher);
-    if (!matched?.groups) {
-      return;
+    this.setContextField(context, "content", parsedContent);
+  }
+  isLikelyStreamingBodyRequest(request) {
+    if (request.method === "GET" || request.method === "HEAD") {
+      return false;
     }
-    return matched.groups;
+    if (!request.body) {
+      return false;
+    }
+    if (request.duplex === "half") {
+      return true;
+    }
+    const transferEncoding = request.headers.get("transfer-encoding");
+    if (transferEncoding) {
+      const hasChunked = transferEncoding.split(",").some((value) => value.trim().toLowerCase() === "chunked");
+      if (hasChunked) {
+        return true;
+      }
+    }
+    return false;
   }
   wrapHandler(options, handler) {
     const routePath = options.path;
     const routeMatcher = routePath.includes(":") ? buildRouteRegex(routePath) : null;
     return async (request) => {
       const vectorRequest = request;
-      const fallbackParams = this.resolveFallbackParams(request, routeMatcher);
-      this.prepareRequest(vectorRequest, {
-        params: fallbackParams,
-        route: routePath,
-        metadata: options.metadata
+      let pathname = "";
+      try {
+        pathname = new URL(request.url).pathname;
+      } catch {}
+      const fallbackParams = this.resolveFallbackParams(pathname, routeMatcher);
+      const context = this.createContext(vectorRequest, {
+        metadata: options.metadata,
+        params: this.getRequestParams(request, fallbackParams),
+        query: this.getRequestQuery(request),
+        cookies: this.getRequestCookies(request)
       });
       try {
         if (options.expose === false) {
           return APIError.forbidden("Forbidden");
         }
-        const beforeResult = await this.middlewareManager.executeBefore(vectorRequest);
-        if (beforeResult instanceof Response) {
-          return beforeResult;
+        const beforeResponse = await this.middlewareManager.executeBefore(context);
+        if (beforeResponse instanceof Response) {
+          return beforeResponse;
         }
-        const req = beforeResult;
         if (options.auth) {
           try {
-            await this.authManager.authenticate(req);
+            await this.authManager.authenticate(context);
           } catch (error) {
             return APIError.unauthorized(error instanceof Error ? error.message : "Authentication failed", options.responseContentType);
           }
         }
-        if (!options.rawRequest && req.method !== "GET" && req.method !== "HEAD") {
-          let parsedContent = null;
-          try {
-            const contentType = req.headers.get("content-type");
-            if (contentType?.startsWith("application/json")) {
-              parsedContent = await req.json();
-            } else if (contentType?.startsWith("application/x-www-form-urlencoded")) {
-              parsedContent = Object.fromEntries(await req.formData());
-            } else if (contentType?.startsWith("multipart/form-data")) {
-              parsedContent = await req.formData();
-            } else {
-              parsedContent = await req.text();
+        const executeRoute = async () => {
+          const req = context.request;
+          const requestForRoute = req;
+          const checkpointRequested = this.getRequestedCheckpointVersion(requestForRoute) !== null;
+          const shouldDeferStreamingValidation = this.isLikelyStreamingBodyRequest(requestForRoute) && options.schema?.input !== undefined && options.validate !== false;
+          if (!options.rawRequest && req.method !== "GET" && req.method !== "HEAD" && !shouldDeferStreamingValidation) {
+            await this.parseRequestBodyForContext(context, requestForRoute, checkpointRequested);
+          }
+          if (shouldDeferStreamingValidation) {
+            const validationWithoutBody = await this.validateInputSchema(context, options, fallbackParams, {
+              includeBody: false,
+              allowBodyDeferral: true
+            });
+            if (validationWithoutBody.response) {
+              return validationWithoutBody.response;
+            }
+            if (validationWithoutBody.requiresBody) {
+              if (!options.rawRequest && req.method !== "GET" && req.method !== "HEAD") {
+                await this.parseRequestBodyForContext(context, requestForRoute, checkpointRequested);
+              }
+              const fullValidation = await this.validateInputSchema(context, options, fallbackParams);
+              if (fullValidation.response) {
+                return fullValidation.response;
+              }
+            }
+          } else {
+            const inputValidation = await this.validateInputSchema(context, options, fallbackParams);
+            if (inputValidation.response) {
+              return inputValidation.response;
             }
-          } catch {
-            parsedContent = null;
           }
-          this.setContentAndBodyAlias(req, parsedContent);
-        }
-        const inputValidationResponse = await this.validateInputSchema(req, options);
-        if (inputValidationResponse) {
-          return inputValidationResponse;
-        }
+          if (this.checkpointGateway) {
+            const checkpointResponse = await this.checkpointGateway.handle(req, this.buildCheckpointContextPayload(context));
+            if (checkpointResponse) {
+              return checkpointResponse;
+            }
+          }
+          return await handler(context);
+        };
         let result;
         const cacheOptions = options.cache;
         if (cacheOptions && typeof cacheOptions === "number" && cacheOptions > 0) {
-          const cacheKey = this.cacheManager.generateKey(req, {
-            authUser: req.authUser
-          });
-          result = await this.cacheManager.get(cacheKey, async () => {
-            const res = await handler(req);
-            if (res instanceof Response) {
-              return {
-                _isResponse: true,
-                body: await res.text(),
-                status: res.status,
-                headers: Object.fromEntries(res.headers.entries())
-              };
-            }
-            return res;
-          }, cacheOptions);
+          const cacheKey = this.applyCheckpointCacheNamespace(this.cacheManager.generateKey(context.request, {
+            authUser: context.authUser
+          }), context.request);
+          result = await this.cacheManager.get(cacheKey, async () => await executeRoute(), cacheOptions);
         } else if (cacheOptions && typeof cacheOptions === "object" && cacheOptions.ttl) {
-          const cacheKey = cacheOptions.key || this.cacheManager.generateKey(req, {
-            authUser: req.authUser
-          });
-          result = await this.cacheManager.get(cacheKey, async () => {
-            const res = await handler(req);
-            if (res instanceof Response) {
-              return {
-                _isResponse: true,
-                body: await res.text(),
-                status: res.status,
-                headers: Object.fromEntries(res.headers.entries())
-              };
-            }
-            return res;
-          }, cacheOptions.ttl);
+          const hasRouteCacheKey = typeof cacheOptions.key === "string" && cacheOptions.key.length > 0;
+          let cacheKey;
+          if (hasRouteCacheKey) {
+            cacheKey = this.applyCheckpointRouteKeyOverride(cacheOptions.key, context.request);
+          } else {
+            const generatedKey = this.cacheManager.generateKey(context.request, {
+              authUser: context.authUser
+            });
+            cacheKey = this.applyCheckpointCacheNamespace(generatedKey, context.request);
+          }
+          result = await this.cacheManager.get(cacheKey, async () => await executeRoute(), cacheOptions.ttl);
         } else {
-          result = await handler(req);
+          result = await executeRoute();
         }
-        if (result && typeof result === "object" && result._isResponse === true) {
-          result = new Response(result.body, {
-            status: result.status,
-            headers: result.headers
-          });
+        if (result instanceof Response && !!cacheOptions) {
+          result = result.clone();
         }
         let response;
         if (options.rawResponse || result instanceof Response) {
@@ -1115,19 +3080,8 @@ class VectorRouter {
         } else {
           response = createResponse(200, result, options.responseContentType);
         }
-        response = await this.middlewareManager.executeFinally(response, req);
-        const entries = this.corsHeadersEntries;
-        if (entries) {
-          for (const [k, v] of entries) {
-            response.headers.set(k, v);
-          }
-        } else {
-          const dynamicCors = this.corsHandler;
-          if (dynamicCors) {
-            response = dynamicCors(response, req);
-          }
-        }
-        return response;
+        response = await this.middlewareManager.executeFinally(response, context);
+        return this.applyCorsResponse(response, context.request);
       } catch (error) {
         if (error instanceof Response) {
           return error;
@@ -1144,9 +3098,11 @@ class VectorRouter {
     const nodeEnv = typeof Bun !== "undefined" ? Bun.env.NODE_ENV : "development";
     return nodeEnv !== "production";
   }
-  async buildInputValidationPayload(request, options) {
-    let body = request.content;
-    if (options.rawRequest && request.method !== "GET" && request.method !== "HEAD") {
+  async buildInputValidationPayload(context, options, fallbackParams, validationOptions) {
+    const request = context.request;
+    const includeBody = validationOptions?.includeBody !== false;
+    let body = includeBody && this.hasOwnContextField(context, "content") ? context.content : undefined;
+    if (includeBody && options.rawRequest && request.method !== "GET" && request.method !== "HEAD") {
       try {
         body = await request.clone().text();
       } catch {
@@ -1154,79 +3110,150 @@ class VectorRouter {
       }
     }
     return {
-      params: request.params ?? {},
-      query: request.query ?? {},
+      params: this.getRequestParams(request, fallbackParams),
+      query: this.getRequestQuery(request),
       headers: Object.fromEntries(request.headers.entries()),
-      cookies: request.cookies ?? {},
+      cookies: this.getRequestCookies(request),
       body
     };
   }
-  applyValidatedInput(request, validatedValue) {
-    request.validatedInput = validatedValue;
-    if (!validatedValue || typeof validatedValue !== "object") {
+  getRequestParams(request, fallbackParams) {
+    const nativeParams = this.readRequestObjectField(request, "params");
+    if (nativeParams && Object.keys(nativeParams).length > 0) {
+      return nativeParams;
+    }
+    return fallbackParams ?? {};
+  }
+  getRequestQuery(request) {
+    const nativeQuery = this.readRequestObjectField(request, "query");
+    if (nativeQuery) {
+      return nativeQuery;
+    }
+    try {
+      return VectorRouter.parseQuery(new URL(request.url));
+    } catch {
+      return {};
+    }
+  }
+  getRequestCookies(request) {
+    const nativeCookies = this.readRequestObjectField(request, "cookies");
+    if (nativeCookies) {
+      return nativeCookies;
+    }
+    return VectorRouter.parseCookies(request.headers.get("cookie"));
+  }
+  readRequestObjectField(request, key) {
+    const value = request[key];
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
       return;
     }
-    const validated = validatedValue;
-    if ("params" in validated) {
-      try {
-        request.params = validated.params;
-      } catch {}
+    return value;
+  }
+  applyValidatedInput(context, validatedValue) {
+    this.setContextField(context, "validatedInput", validatedValue);
+  }
+  issueHasBodyPath(issue) {
+    if (!issue || typeof issue !== "object" || !("path" in issue)) {
+      return false;
     }
-    if ("query" in validated) {
-      try {
-        request.query = validated.query;
-      } catch {}
+    const path = issue.path;
+    if (!Array.isArray(path) || path.length === 0) {
+      return false;
     }
-    if ("cookies" in validated) {
-      try {
-        request.cookies = validated.cookies;
-      } catch {}
+    const segment = path[0];
+    if (segment && typeof segment === "object" && "key" in segment) {
+      return segment.key === "body";
+    }
+    return segment === "body";
+  }
+  issueHasExplicitNonBodyPath(issue) {
+    if (!issue || typeof issue !== "object" || !("path" in issue)) {
+      return false;
     }
-    if ("body" in validated) {
-      this.setContentAndBodyAlias(request, validated.body);
+    const path = issue.path;
+    if (!Array.isArray(path) || path.length === 0) {
+      return false;
+    }
+    const segment = path[0];
+    if (segment && typeof segment === "object" && "key" in segment) {
+      return segment.key !== "body";
     }
+    return segment !== "body";
   }
-  setContentAndBodyAlias(request, value) {
-    try {
-      request.content = value;
-    } catch {
-      return;
+  issueHasUnknownPath(issue) {
+    if (!issue || typeof issue !== "object" || !("path" in issue)) {
+      return true;
     }
-    this.setBodyAlias(request, value);
+    const path = issue.path;
+    if (!Array.isArray(path)) {
+      return true;
+    }
+    return path.length === 0;
   }
-  setBodyAlias(request, value) {
-    try {
-      request.body = value;
-    } catch {}
+  shouldDeferBodyValidation(issues, context, validationOptions) {
+    if (!(validationOptions?.allowBodyDeferral === true && validationOptions?.includeBody === false)) {
+      return false;
+    }
+    const request = context.request;
+    const mayHaveRequestBody = request.method !== "GET" && request.method !== "HEAD" && request.body !== null;
+    if (!mayHaveRequestBody || issues.length === 0) {
+      return false;
+    }
+    if (issues.some((issue) => this.issueHasBodyPath(issue))) {
+      return true;
+    }
+    const hasExplicitNonBodyPath = issues.some((issue) => this.issueHasExplicitNonBodyPath(issue));
+    const hasUnknownPath = issues.some((issue) => this.issueHasUnknownPath(issue));
+    return !hasExplicitNonBodyPath && hasUnknownPath;
   }
-  async validateInputSchema(request, options) {
+  async validateInputSchema(context, options, fallbackParams, validationOptions) {
     const inputSchema = options.schema?.input;
     if (!inputSchema) {
-      return null;
+      return { response: null, requiresBody: false };
     }
     if (options.validate === false) {
-      return null;
+      return { response: null, requiresBody: false };
     }
     if (!isStandardRouteSchema(inputSchema)) {
-      return APIError.internalServerError("Invalid route schema configuration", options.responseContentType);
+      return {
+        response: APIError.internalServerError("Invalid route schema configuration", options.responseContentType),
+        requiresBody: false
+      };
     }
     const includeRawIssues = this.isDevelopmentMode();
-    const payload = await this.buildInputValidationPayload(request, options);
+    const payload = await this.buildInputValidationPayload(context, options, fallbackParams, {
+      includeBody: validationOptions?.includeBody
+    });
     try {
       const validation = await runStandardValidation(inputSchema, payload);
       if (validation.success === false) {
+        if (this.shouldDeferBodyValidation(validation.issues, context, validationOptions)) {
+          return { response: null, requiresBody: true };
+        }
         const issues = normalizeValidationIssues(validation.issues, includeRawIssues);
-        return createResponse(422, createValidationErrorPayload("input", issues), options.responseContentType);
+        return {
+          response: createResponse(422, createValidationErrorPayload("input", issues), options.responseContentType),
+          requiresBody: false
+        };
       }
-      this.applyValidatedInput(request, validation.value);
-      return null;
+      this.applyValidatedInput(context, validation.value);
+      return { response: null, requiresBody: false };
     } catch (error) {
       const thrownIssues = extractThrownIssues(error);
       if (thrownIssues) {
+        if (this.shouldDeferBodyValidation(thrownIssues, context, validationOptions)) {
+          return { response: null, requiresBody: true };
+        }
         const issues = normalizeValidationIssues(thrownIssues, includeRawIssues);
-        return createResponse(422, createValidationErrorPayload("input", issues), options.responseContentType);
+        return {
+          response: createResponse(422, createValidationErrorPayload("input", issues), options.responseContentType),
+          requiresBody: false
+        };
       }
-      return APIError.internalServerError(error instanceof Error ? error.message : "Validation failed", options.responseContentType);
+      return {
+        response: APIError.internalServerError(error instanceof Error ? error.message : "Validation failed", options.responseContentType),
+        requiresBody: false
+      };
     }
   }
   getOrCreateMethodMap(path) {
@@ -1277,6 +3304,19 @@ class VectorRouter {
     }
     return query;
   }
+  static parseCookies(cookieHeader) {
+    const cookies = {};
+    if (!cookieHeader) {
+      return cookies;
+    }
+    for (const pair of cookieHeader.split(";")) {
+      const idx = pair.indexOf("=");
+      if (idx > 0) {
+        cookies[pair.slice(0, idx).trim()] = pair.slice(idx + 1).trim();
+      }
+    }
+    return cookies;
+  }
   routeSpecificityScore(path) {
     const STATIC_SEGMENT_WEIGHT = 1000;
     const PARAM_SEGMENT_WEIGHT = 10;
@@ -1299,6 +3339,20 @@ class VectorRouter {
     }
     return score;
   }
+  applyCorsResponse(response, request) {
+    const entries = this.corsHeadersEntries;
+    if (entries) {
+      for (const [k, v] of entries) {
+        response.headers.set(k, v);
+      }
+      return response;
+    }
+    const dynamicCors = this.corsHandler;
+    if (dynamicCors) {
+      return dynamicCors(response, request);
+    }
+    return response;
+  }
 }
 
 // src/core/server.ts
@@ -1525,6 +3579,124 @@ function renderOpenAPIDocsHtml(spec, openapiPath, tailwindScriptPath, logoDarkPa
     .dark .json-number { color: #7dc9ff; }
     .dark .json-boolean { color: #93a4bf; }
     .dark .json-null { color: #7c8ba3; }
+    .param-row {
+      --param-row-bg-rgb: 255 255 255;
+    }
+    .dark .param-row {
+      --param-row-bg-rgb: 10 10 10;
+    }
+    .param-row-head {
+      display: grid;
+      grid-template-columns: minmax(0, 1fr) auto;
+      align-items: center;
+      gap: 0.5rem;
+      min-width: 0;
+      width: 100%;
+    }
+    .param-row-main {
+      min-width: 0;
+      display: flex;
+      align-items: center;
+      gap: 0.4rem;
+      overflow: hidden;
+    }
+    .param-tooltip-trigger {
+      border: 0;
+      margin: 0;
+      padding: 0;
+      background: transparent;
+      color: inherit;
+      cursor: pointer;
+      font: inherit;
+      text-align: left;
+      min-width: 0;
+    }
+    .param-tooltip-trigger:focus-visible {
+      outline: 2px solid rgba(0, 161, 255, 0.65);
+      outline-offset: 2px;
+      border-radius: 0.375rem;
+    }
+    .param-name-trigger {
+      min-width: 0;
+      flex: 1 1 auto;
+      overflow: hidden;
+    }
+    .param-name-text {
+      display: block;
+      max-width: 100%;
+      overflow: hidden;
+      text-overflow: ellipsis;
+      white-space: nowrap;
+      mask-image: linear-gradient(to right, #000 0%, #000 calc(100% - 18px), transparent 100%);
+      -webkit-mask-image: linear-gradient(to right, #000 0%, #000 calc(100% - 18px), transparent 100%);
+    }
+    .param-type-fade {
+      position: relative;
+      z-index: 1;
+      display: block;
+      max-width: none;
+      overflow: visible;
+      text-overflow: clip;
+      padding-left: 1.25rem;
+      white-space: nowrap;
+      text-align: left;
+      justify-self: end;
+      background: linear-gradient(
+        90deg,
+        rgba(var(--param-row-bg-rgb), 0) 0%,
+        rgba(var(--param-row-bg-rgb), 0.76) 36%,
+        rgba(var(--param-row-bg-rgb), 0.94) 68%,
+        rgba(var(--param-row-bg-rgb), 1) 100%
+      );
+    }
+    #param-value-tooltip {
+      position: fixed;
+      top: 0;
+      left: 0;
+      z-index: 70;
+      width: min(42rem, calc(100vw - 0.75rem));
+      border-radius: 0.5rem;
+      border: 1px solid rgba(15, 23, 42, 0.12);
+      background: rgba(255, 255, 255, 0.92);
+      color: #111111;
+      box-shadow: 0 10px 20px rgba(15, 23, 42, 0.14);
+      backdrop-filter: blur(12px) saturate(145%);
+      -webkit-backdrop-filter: blur(12px) saturate(145%);
+      padding: 0.4rem 0.6rem;
+      opacity: 0;
+      pointer-events: none;
+      transform: translateY(6px) scale(0.98);
+      transition:
+        opacity var(--motion-fast) var(--motion-ease),
+        transform var(--motion-fast) var(--motion-ease);
+    }
+    #param-value-tooltip.is-visible {
+      opacity: 1;
+      pointer-events: auto;
+      transform: translateY(0) scale(1);
+    }
+    .dark #param-value-tooltip {
+      border-color: rgba(148, 163, 184, 0.24);
+      background: rgba(17, 17, 17, 0.9);
+      color: #ededed;
+      box-shadow: 0 14px 30px rgba(0, 0, 0, 0.45);
+    }
+    #param-tooltip-line {
+      margin: 0;
+      font-size: 11px;
+      line-height: 1.3;
+      font-family: "JetBrains Mono", monospace;
+      white-space: normal;
+      word-break: break-word;
+    }
+    #param-tooltip-description {
+      margin: 0.2rem 0 0;
+      font-size: 11px;
+      line-height: 1.3;
+      opacity: 0.8;
+      white-space: normal;
+      word-break: break-word;
+    }
   </style>
 </head>
 <body class="bg-light-bg text-light-text dark:bg-dark-bg dark:text-dark-text font-sans antialiased flex h-screen overflow-hidden">
@@ -1554,6 +3726,16 @@ function renderOpenAPIDocsHtml(spec, openapiPath, tailwindScriptPath, logoDarkPa
         />
       </div>
     </div>
+    <div id="auth-panel" class="border-b border-light-border dark:border-dark-border">
+      <button id="auth-toggle" class="w-full flex items-center justify-between px-4 py-2.5 text-xs font-semibold uppercase tracking-wider opacity-60 hover:opacity-100 transition-opacity">
+        <span class="flex items-center gap-1.5">
+          <svg class="w-3.5 h-3.5" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 15v2m-6 4h12a2 2 0 002-2v-6a2 2 0 00-2-2H6a2 2 0 00-2 2v6a2 2 0 002 2zm10-10V7a4 4 0 00-8 0v4h8z"></path></svg>
+          Auth
+        </span>
+        <svg id="auth-chevron" class="w-3.5 h-3.5 transition-transform duration-200" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M19 9l-7 7-7-7"></path></svg>
+      </button>
+      <div id="auth-fields" class="px-4 pb-3 space-y-2"></div>
+    </div>
     <nav class="flex-1 overflow-y-auto px-3 py-2 space-y-6 text-sm" id="sidebar-nav"></nav>
   </aside>
 
@@ -1587,6 +3769,9 @@ function renderOpenAPIDocsHtml(spec, openapiPath, tailwindScriptPath, logoDarkPa
              <span id="endpoint-method" class="px-2.5 py-0.5 rounded-full text-xs font-mono font-medium"></span>
              <h2 class="text-xl font-semibold tracking-tight" id="endpoint-title">Operation</h2>
           </div>
+          <div id="deprecated-banner" class="hidden mb-4 px-3 py-2 rounded border border-amber-300 dark:border-amber-700 bg-amber-50 dark:bg-amber-900/20 text-amber-700 dark:text-amber-400 text-xs font-medium">
+            ! This operation is deprecated
+          </div>
           <p class="text-sm opacity-80 mb-8 font-mono" id="endpoint-path">/</p>
           <div class="grid grid-cols-1 lg:grid-cols-12 gap-10">
             <div class="lg:col-span-5 space-y-8" id="params-column"></div>
@@ -1682,6 +3867,10 @@ function renderOpenAPIDocsHtml(spec, openapiPath, tailwindScriptPath, logoDarkPa
       <pre id="expand-viewer" class="hidden w-full h-[70vh] text-sm p-3 rounded border border-light-border dark:border-dark-border bg-light-bg dark:bg-dark-bg overflow-auto font-mono"></pre>
     </div>
   </div>
+  <div id="param-value-tooltip" aria-hidden="true" role="tooltip">
+    <p id="param-tooltip-line"></p>
+    <p id="param-tooltip-description" class="hidden"></p>
+  </div>
 
   <script>
     const spec = ${specJson};
@@ -1752,14 +3941,71 @@ function renderOpenAPIDocsHtml(spec, openapiPath, tailwindScriptPath, logoDarkPa
       return ops;
     }
 
+    const AUTH_STATE_KEY = "vector-docs-auth-v1";
+    const AUTH_SELECTION_KEY = "vector-docs-auth-selection-v1";
+    const HEADERS_STATE_KEY = "vector-docs-headers-v1";
+
+    function loadSavedHeaders() {
+      try {
+        const raw = localStorage.getItem(HEADERS_STATE_KEY);
+        if (raw) {
+          const parsed = JSON.parse(raw);
+          if (Array.isArray(parsed) && parsed.length > 0) return parsed;
+        }
+      } catch {}
+      return [{ key: "", value: "" }];
+    }
+
+    function saveHeaders() {
+      try { localStorage.setItem(HEADERS_STATE_KEY, JSON.stringify(requestHeaders)); } catch {}
+    }
+
+    function loadAuthState() {
+      try {
+        const raw = localStorage.getItem(AUTH_STATE_KEY);
+        if (raw) return JSON.parse(raw);
+      } catch {}
+      return {};
+    }
+
+    function saveAuthState() {
+      try { localStorage.setItem(AUTH_STATE_KEY, JSON.stringify(authState)); } catch {}
+    }
+
+    function loadAuthSelectionState() {
+      try {
+        const raw = localStorage.getItem(AUTH_SELECTION_KEY);
+        if (raw) {
+          const parsed = JSON.parse(raw);
+          if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            return parsed;
+          }
+        }
+      } catch {}
+      return {};
+    }
+
+    function saveAuthSelectionState() {
+      try { localStorage.setItem(AUTH_SELECTION_KEY, JSON.stringify(authSelectionState)); } catch {}
+    }
+
+    const authSchemes = (spec.components && spec.components.securitySchemes) || {};
+    let authState = loadAuthState();
+    let authSelectionState = loadAuthSelectionState();
+
     const operations = getOperations();
     let selected = operations[0] || null;
     const operationParamValues = new Map();
     const operationBodyDrafts = new Map();
-    const requestHeaders = [{ key: "Authorization", value: "" }];
+    const requestHeaders = loadSavedHeaders();
     let expandModalMode = null;
     let isMobileSidebarOpen = false;
     let sidebarSearchQuery = "";
+    const paramTooltipRoot = document.getElementById("param-value-tooltip");
+    const paramTooltipLine = document.getElementById("param-tooltip-line");
+    const paramTooltipDescription = document.getElementById("param-tooltip-description");
+    let activeParamTooltipTrigger = null;
+    let paramTooltipHideTimer = null;
 
     function setMobileSidebarOpen(open) {
       const sidebar = document.getElementById("docs-sidebar");
@@ -1779,6 +4025,29 @@ function renderOpenAPIDocsHtml(spec, openapiPath, tailwindScriptPath, logoDarkPa
       return op.method + " " + op.path;
     }
 
+    function getOpHash(op) {
+      var tag = op.tag || "default";
+      var id = (op.operation && op.operation.operationId)
+        ? op.operation.operationId
+        : op.method.toLowerCase() + "_" + op.path.split("/").filter(Boolean).join("_").replace(/[{}]/g, "");
+      return "#/" + encodeURIComponent(tag) + "/" + encodeURIComponent(id);
+    }
+
+    function findOpByHash(hash) {
+      if (!hash || hash.length <= 1) return null;
+      var parts = hash.slice(1).split("/").filter(Boolean);
+      if (parts.length < 2) return null;
+      var hashTag = decodeURIComponent(parts[0]);
+      var hashId = decodeURIComponent(parts[1]);
+      return operations.find(function(op) {
+        if (op.tag !== hashTag) return false;
+        var id = (op.operation && op.operation.operationId)
+          ? op.operation.operationId
+          : op.method.toLowerCase() + "_" + op.path.split("/").filter(Boolean).join("_").replace(/[{}]/g, "");
+        return id === hashId;
+      }) || null;
+    }
+
     function getOperationParameterGroups(op) {
       const params =
         op &&
@@ -1828,7 +4097,7 @@ function renderOpenAPIDocsHtml(spec, openapiPath, tailwindScriptPath, logoDarkPa
       return resolved;
     }
 
-    function buildRequestPath(op, pathParams, queryParams, values) {
+    function buildRequestPath(op, pathParams, queryParams, values, extraQuery) {
       const resolvedPath = resolvePath(op.path, pathParams, values);
       const query = new URLSearchParams();
 
@@ -1840,6 +4109,13 @@ function renderOpenAPIDocsHtml(spec, openapiPath, tailwindScriptPath, logoDarkPa
         query.append(param.name, String(rawValue));
       }
 
+      if (extraQuery) {
+        for (const key of Object.keys(extraQuery)) {
+          const val = extraQuery[key];
+          if (val) query.set(key, String(val));
+        }
+      }
+
       const queryString = query.toString();
       return queryString ? resolvedPath + "?" + queryString : resolvedPath;
     }
@@ -1979,14 +4255,25 @@ function renderOpenAPIDocsHtml(spec, openapiPath, tailwindScriptPath, logoDarkPa
 
           const name = document.createElement("span");
           name.textContent = op.name;
+          if (op.operation && op.operation.deprecated) {
+            name.style.textDecoration = "line-through";
+            name.style.opacity = "0.5";
+          }
 
           row.appendChild(method);
           row.appendChild(name);
+          if (op.operation && op.operation.deprecated) {
+            const badge = document.createElement("span");
+            badge.className = "text-[9px] px-1 py-0.5 rounded bg-amber-100 dark:bg-amber-900/30 text-amber-700 dark:text-amber-500 font-semibold shrink-0";
+            badge.textContent = "deprecated";
+            row.appendChild(badge);
+          }
           a.appendChild(row);
 
           a.onclick = (e) => {
             e.preventDefault();
             selected = op;
+            history.pushState(null, "", getOpHash(op));
             renderSidebar();
             renderEndpoint();
             if (window.innerWidth < 768) {
@@ -2000,51 +4287,257 @@ function renderOpenAPIDocsHtml(spec, openapiPath, tailwindScriptPath, logoDarkPa
       }
     }
 
+    function hideParamTooltip() {
+      if (!paramTooltipRoot) return;
+      if (paramTooltipHideTimer) {
+        window.clearTimeout(paramTooltipHideTimer);
+        paramTooltipHideTimer = null;
+      }
+      paramTooltipRoot.classList.remove("is-visible");
+      paramTooltipRoot.setAttribute("aria-hidden", "true");
+      if (activeParamTooltipTrigger) {
+        activeParamTooltipTrigger.setAttribute("aria-expanded", "false");
+      }
+      activeParamTooltipTrigger = null;
+    }
+
+    function scheduleParamTooltipHide() {
+      if (paramTooltipHideTimer) {
+        window.clearTimeout(paramTooltipHideTimer);
+      }
+      paramTooltipHideTimer = window.setTimeout(() => {
+        hideParamTooltip();
+      }, 95);
+    }
+
+    function positionParamTooltip(trigger) {
+      if (!paramTooltipRoot || !trigger) return;
+      const viewportPadding = 8;
+      const spacing = 10;
+      const triggerRect = trigger.getBoundingClientRect();
+      const tooltipRect = paramTooltipRoot.getBoundingClientRect();
+      let left = triggerRect.left + (triggerRect.width / 2) - (tooltipRect.width / 2);
+      left = Math.max(viewportPadding, Math.min(left, window.innerWidth - tooltipRect.width - viewportPadding));
+      let top = triggerRect.top - tooltipRect.height - spacing;
+      if (top < viewportPadding) {
+        top = triggerRect.bottom + spacing;
+      }
+      if (top + tooltipRect.height > window.innerHeight - viewportPadding) {
+        top = window.innerHeight - tooltipRect.height - viewportPadding;
+      }
+      paramTooltipRoot.style.left = Math.round(left) + "px";
+      paramTooltipRoot.style.top = Math.round(top) + "px";
+    }
+
+    function showParamTooltip(trigger) {
+      if (
+        !paramTooltipRoot ||
+        !paramTooltipLine ||
+        !paramTooltipDescription ||
+        !trigger
+      ) {
+        return;
+      }
+      if (paramTooltipHideTimer) {
+        window.clearTimeout(paramTooltipHideTimer);
+        paramTooltipHideTimer = null;
+      }
+      const label = trigger.getAttribute("data-param-tooltip-label") || "Value";
+      const value = trigger.getAttribute("data-param-tooltip-value") || "";
+      const related = trigger.getAttribute("data-param-tooltip-related") || "";
+      const description = trigger.getAttribute("data-param-tooltip-description") || "";
+      if (activeParamTooltipTrigger && activeParamTooltipTrigger !== trigger) {
+        activeParamTooltipTrigger.setAttribute("aria-expanded", "false");
+      }
+      activeParamTooltipTrigger = trigger;
+      activeParamTooltipTrigger.setAttribute("aria-expanded", "true");
+      const pathLabel = related ? " | path: " + related : "";
+      paramTooltipLine.textContent = label + ": " + value + pathLabel;
+      if (description.trim()) {
+        paramTooltipDescription.textContent = description;
+        paramTooltipDescription.classList.remove("hidden");
+      } else {
+        paramTooltipDescription.textContent = "";
+        paramTooltipDescription.classList.add("hidden");
+      }
+      paramTooltipRoot.classList.add("is-visible");
+      paramTooltipRoot.setAttribute("aria-hidden", "false");
+      positionParamTooltip(trigger);
+    }
+
+    function registerParamTooltipTargets(scope) {
+      if (!scope) return;
+      const targets = scope.querySelectorAll("[data-param-tooltip-value]");
+      for (const target of targets) {
+        target.addEventListener("click", (event) => {
+          event.preventDefault();
+          if (
+            activeParamTooltipTrigger === target &&
+            paramTooltipRoot &&
+            paramTooltipRoot.classList.contains("is-visible")
+          ) {
+            hideParamTooltip();
+            return;
+          }
+          showParamTooltip(target);
+        });
+        target.addEventListener("mouseenter", () => {
+          showParamTooltip(target);
+        });
+        target.addEventListener("mouseleave", (event) => {
+          const related = event.relatedTarget;
+          if (paramTooltipRoot && related && paramTooltipRoot.contains(related)) return;
+          scheduleParamTooltipHide();
+        });
+        target.addEventListener("focus", () => {
+          showParamTooltip(target);
+        });
+        target.addEventListener("blur", (event) => {
+          const related = event.relatedTarget;
+          if (paramTooltipRoot && related && paramTooltipRoot.contains(related)) return;
+          scheduleParamTooltipHide();
+        });
+      }
+    }
+
     function renderParamSection(title, params) {
       if (!params.length) return "";
       let rows = "";
       for (const p of params) {
-        const type = escapeHtml((p.schema && p.schema.type) || "unknown");
-        const name = escapeHtml(p.name || "");
-        rows += '<div class="py-2 flex justify-between border-b border-light-border/50 dark:border-dark-border/50"><div><code class="text-sm font-mono">' + name + '</code><span class="text-xs text-brand ml-2">' + (p.required ? "required" : "optional") + '</span></div><span class="text-xs font-mono opacity-60">' + type + '</span></div>';
+        const schema = resolveSchemaRef(p.schema || {});
+        const typeRaw = getSchemaTypeLabel(schema);
+        const type = escapeHtml(typeRaw);
+        const nameRaw = p.name || "";
+        const name = escapeHtml(nameRaw);
+        const tooltipName = escapeHtmlAttribute(nameRaw);
+        const tooltipType = escapeHtmlAttribute(typeRaw);
+        const tooltipDescription = (typeof p.description === "string" && p.description.trim())
+          ? escapeHtmlAttribute(p.description.trim())
+          : (typeof schema.description === "string" && schema.description.trim())
+            ? escapeHtmlAttribute(schema.description.trim())
+            : "";
+        const desc = (typeof p.description === "string" && p.description.trim())
+          ? '<p class="text-xs opacity-60 mt-0.5 leading-snug">' + renderMarkdown(p.description.trim()) + '</p>'
+          : "";
+        const extra = buildSchemaExtra(schema);
+        rows +=
+          '<div class="param-row py-2 border-b border-light-border/50 dark:border-dark-border/50">' +
+          '<div class="param-row-head">' +
+          '<div class="param-row-main">' +
+          '<button type="button" class="param-tooltip-trigger param-name-trigger" data-param-tooltip-label="Parameter" data-param-tooltip-value="' +
+          tooltipName +
+          '" data-param-tooltip-description="' +
+          tooltipDescription +
+          '" aria-expanded="false">' +
+          '<code class="text-sm font-mono param-name-text">' +
+          name +
+          "</code></button>" +
+          '<span class="text-xs text-brand shrink-0">' +
+          (p.required ? "required" : "optional") +
+          "</span></div>" +
+          '<button type="button" class="param-tooltip-trigger param-type-fade text-xs font-mono opacity-60" data-param-tooltip-label="Type" data-param-tooltip-value="' +
+          tooltipType +
+          '" data-param-tooltip-description="' +
+          tooltipDescription +
+          '" aria-expanded="false">' +
+          type +
+          "</button></div>" +
+          desc +
+          extra +
+          "</div>";
       }
       return '<div><h3 class="text-sm font-semibold mb-3 flex items-center border-b border-light-border dark:border-dark-border pb-2">' + escapeHtml(title) + "</h3>" + rows + "</div>";
     }
 
     function getSchemaTypeLabel(schema) {
-      if (!schema || typeof schema !== "object") return "unknown";
-      if (Array.isArray(schema.type)) return schema.type.join(" | ");
-      if (schema.type) return String(schema.type);
-      if (schema.properties) return "object";
-      if (schema.items) return "array";
-      if (Array.isArray(schema.oneOf)) return "oneOf";
-      if (Array.isArray(schema.anyOf)) return "anyOf";
-      if (Array.isArray(schema.allOf)) return "allOf";
+      const resolved = resolveSchemaRef(schema);
+      if (!resolved || typeof resolved !== "object") return "unknown";
+      if (Array.isArray(resolved.type)) return resolved.type.join(" | ");
+      if (resolved.type) return String(resolved.type);
+      if (resolved.properties) return "object";
+      if (resolved.items) return "array";
+      if (Array.isArray(resolved.oneOf)) return "oneOf";
+      if (Array.isArray(resolved.anyOf)) return "anyOf";
+      if (Array.isArray(resolved.allOf)) return "allOf";
       return "unknown";
     }
 
+    function buildSchemaExtra(schema) {
+      const resolved = resolveSchemaRef(schema);
+      if (!resolved || typeof resolved !== "object") return "";
+      const chips = [];
+      if (resolved.format) chips.push(escapeHtml(String(resolved.format)));
+      if (Array.isArray(resolved.enum) && resolved.enum.length > 0) {
+        const shown = resolved.enum.slice(0, 5).map(function(v) { return escapeHtml(JSON.stringify(v)); });
+        chips.push(shown.join(" | ") + (resolved.enum.length > 5 ? " \u2026" : ""));
+      }
+      if (resolved.minimum !== undefined) chips.push("min: " + resolved.minimum);
+      if (resolved.maximum !== undefined) chips.push("max: " + resolved.maximum);
+      if (typeof resolved.exclusiveMinimum === "number") chips.push("&gt;" + resolved.exclusiveMinimum);
+      if (typeof resolved.exclusiveMaximum === "number") chips.push("&lt;" + resolved.exclusiveMaximum);
+      if (resolved.minLength !== undefined) chips.push("minLen: " + resolved.minLength);
+      if (resolved.maxLength !== undefined) chips.push("maxLen: " + resolved.maxLength);
+      if (resolved.minItems !== undefined) chips.push("minItems: " + resolved.minItems);
+      if (resolved.maxItems !== undefined) chips.push("maxItems: " + resolved.maxItems);
+      if (resolved.uniqueItems) chips.push("unique");
+      if (resolved.pattern) chips.push("/" + escapeHtml(String(resolved.pattern)) + "/");
+      if (!chips.length) return "";
+      return '<div class="flex flex-wrap gap-1 mt-1.5">' +
+        chips.map(function(c) {
+          return '<span class="text-[10px] px-1.5 py-0.5 rounded bg-black/5 dark:bg-white/5 font-mono opacity-80">' + c + '</span>';
+        }).join("") +
+        '</div>';
+    }
+
+    function resolveSchemaRef(schema, visitedRefs) {
+      if (!schema || typeof schema !== "object") return schema;
+      const ref = typeof schema.$ref === "string" ? schema.$ref : "";
+      if (!ref || !ref.startsWith("#/components/schemas/")) {
+        return schema;
+      }
+
+      const seen = visitedRefs || new Set();
+      if (seen.has(ref)) return schema;
+      seen.add(ref);
+
+      const parts = ref.split("/");
+      const schemaName = parts[parts.length - 1];
+      const referenced = spec && spec.components && spec.components.schemas && spec.components.schemas[schemaName];
+      if (!referenced || typeof referenced !== "object") return schema;
+
+      const merged = Object.assign({}, referenced, schema);
+      delete merged.$ref;
+      return resolveSchemaRef(merged, seen);
+    }
+
     function buildSchemaChildren(schema) {
-      if (!schema || typeof schema !== "object") return [];
+      const resolved = resolveSchemaRef(schema);
+      if (!resolved || typeof resolved !== "object") return [];
 
       const children = [];
 
-      if (schema.properties && typeof schema.properties === "object") {
+      if (resolved.properties && typeof resolved.properties === "object") {
         const requiredSet = new Set(
-          Array.isArray(schema.required) ? schema.required : [],
+          Array.isArray(resolved.required) ? resolved.required : [],
         );
-        for (const [name, childSchema] of Object.entries(schema.properties)) {
+        for (const [name, childSchema] of Object.entries(resolved.properties)) {
+          const childDef = childSchema || {};
+          const isArrayType = Array.isArray(childDef.type)
+            ? childDef.type.includes("array")
+            : childDef.type === "array";
+          const isArrayLike = isArrayType || childDef.items !== undefined;
           children.push({
-            name,
-            schema: childSchema || {},
+            name: isArrayLike ? (name + "[]") : name,
+            schema: childDef,
             required: requiredSet.has(name),
           });
         }
       }
 
-      if (schema.items) {
+      if (resolved.items) {
         children.push({
-          name: "items[]",
-          schema: schema.items,
+          name: getArrayItemNodeName(resolved.items),
+          schema: resolved.items,
           required: true,
         });
       }
@@ -2052,45 +4545,100 @@ function renderOpenAPIDocsHtml(spec, openapiPath, tailwindScriptPath, logoDarkPa
       return children;
     }
 
-    function renderSchemaFieldNode(field, depth) {
-      const schema = field.schema || {};
-      const name = escapeHtml(field.name || "field");
+    function getArrayItemNodeName(itemSchema) {
+      if (!itemSchema || typeof itemSchema !== "object") return "item";
+      const title =
+        typeof itemSchema.title === "string" && itemSchema.title.trim()
+          ? itemSchema.title.trim()
+          : "";
+      if (title) return title;
+
+      const ref =
+        typeof itemSchema.$ref === "string" && itemSchema.$ref.trim()
+          ? itemSchema.$ref.trim()
+          : "";
+      if (ref) {
+        const parts = ref.split("/").filter(Boolean);
+        const last = parts[parts.length - 1];
+        if (last) return last;
+      }
+
+      const typeLabel = getSchemaTypeLabel(itemSchema);
+      if (typeLabel && typeLabel !== "unknown") return typeLabel;
+      return "type";
+    }
+
+    function renderSchemaFieldNode(field, depth, parentPath) {
+      const schema = resolveSchemaRef(field.schema || {});
+      const nameRaw = field.name || "field";
+      const name = escapeHtml(nameRaw);
       const requiredLabel = field.required ? "required" : "optional";
-      const type = escapeHtml(getSchemaTypeLabel(schema));
+      const typeRaw = getSchemaTypeLabel(schema);
+      const type = escapeHtml(typeRaw);
+      const tooltipName = escapeHtmlAttribute(nameRaw);
+      const tooltipType = escapeHtmlAttribute(typeRaw);
+      const fieldPath = parentPath ? (parentPath + "." + nameRaw) : nameRaw;
+      const tooltipPath = escapeHtmlAttribute(fieldPath);
+      const tooltipDescription = (typeof schema.description === "string" && schema.description.trim())
+        ? escapeHtmlAttribute(schema.description.trim())
+        : "";
       const children = buildSchemaChildren(schema);
       const padding = depth * 14;
+      const extra = buildSchemaExtra(schema);
 
       if (!children.length) {
         return (
-          '<div class="py-2 border-b border-light-border/50 dark:border-dark-border/50" style="padding-left:' +
+          '<div class="param-row py-2 border-b border-light-border/50 dark:border-dark-border/50" style="padding-left:' +
           padding +
-          'px"><div class="flex justify-between"><div><code class="text-sm font-mono">' +
+          'px"><div class="param-row-head"><div class="param-row-main">' +
+          '<button type="button" class="param-tooltip-trigger param-name-trigger" data-param-tooltip-label="Field" data-param-tooltip-value="' +
+          tooltipName +
+          '" data-param-tooltip-related="' +
+          tooltipPath +
+          '" data-param-tooltip-description="' +
+          tooltipDescription +
+          '" aria-expanded="false"><code class="text-sm font-mono param-name-text">' +
           name +
-          '</code><span class="text-xs text-brand ml-2">' +
+          '</code></button><span class="text-xs text-brand shrink-0">' +
           requiredLabel +
-          '</span></div><span class="text-xs font-mono opacity-60">' +
+          '</span></div><button type="button" class="param-tooltip-trigger param-type-fade text-xs font-mono opacity-60" data-param-tooltip-label="Type" data-param-tooltip-value="' +
+          tooltipType +
+          '" data-param-tooltip-description="' +
+          tooltipDescription +
+          '" aria-expanded="false">' +
           type +
-          "</span></div></div>"
+          "</button></div>" + extra + "</div>"
         );
       }
 
       let nested = "";
       for (const child of children) {
-        nested += renderSchemaFieldNode(child, depth + 1);
+        nested += renderSchemaFieldNode(child, depth + 1, fieldPath);
       }
 
       return (
-        '<details class="border-b border-light-border/50 dark:border-dark-border/50" open>' +
-        '<summary class="list-none cursor-pointer py-2 flex justify-between items-center" style="padding-left:' +
+        '<details open>' +
+        '<summary class="list-none cursor-pointer py-2 border-b border-light-border/50 dark:border-dark-border/50" style="padding-left:' +
         padding +
-        'px"><div class="flex items-center gap-2"><span class="text-xs opacity-70">\u25BE</span><code class="text-sm font-mono">' +
+        'px"><div class="param-row-head"><div class="param-row-main"><span class="text-xs opacity-70 shrink-0">\u25BE</span>' +
+        '<button type="button" class="param-tooltip-trigger param-name-trigger" data-param-tooltip-label="Field" data-param-tooltip-value="' +
+        tooltipName +
+        '" data-param-tooltip-related="' +
+        tooltipPath +
+        '" data-param-tooltip-description="' +
+        tooltipDescription +
+        '" aria-expanded="false"><code class="text-sm font-mono param-name-text">' +
         name +
-        '</code><span class="text-xs text-brand">' +
+        '</code></button><span class="text-xs text-brand shrink-0">' +
         requiredLabel +
-        '</span></div><span class="text-xs font-mono opacity-60">' +
+        '</span></div><button type="button" class="param-tooltip-trigger param-type-fade text-xs font-mono opacity-60" data-param-tooltip-label="Type" data-param-tooltip-value="' +
+        tooltipType +
+        '" data-param-tooltip-description="' +
+        tooltipDescription +
+        '" aria-expanded="false">' +
         type +
-        "</span></summary>" +
-        '<div class="pb-1">' +
+        "</button></div>" + extra + "</summary>" +
+        "<div>" +
         nested +
         "</div></details>"
       );
@@ -2103,7 +4651,7 @@ function renderOpenAPIDocsHtml(spec, openapiPath, tailwindScriptPath, logoDarkPa
 
       let rows = "";
       for (const child of rootChildren) {
-        rows += renderSchemaFieldNode(child, 0);
+        rows += renderSchemaFieldNode(child, 0, "");
       }
 
       return (
@@ -2130,27 +4678,40 @@ function renderOpenAPIDocsHtml(spec, openapiPath, tailwindScriptPath, logoDarkPa
         const responseDef = responses[statusCode];
         if (!responseDef || typeof responseDef !== "object") continue;
 
+        const responseDesc = (typeof responseDef.description === "string" && responseDef.description.trim())
+          ? responseDef.description.trim()
+          : "";
+
         const jsonSchema =
           responseDef.content &&
           responseDef.content["application/json"] &&
           responseDef.content["application/json"].schema;
 
-        if (!jsonSchema || typeof jsonSchema !== "object") continue;
-
-        const rootChildren = buildSchemaChildren(jsonSchema);
-        if (!rootChildren.length) continue;
-
         let rows = "";
-        for (const child of rootChildren) {
-          rows += renderSchemaFieldNode(child, 0);
+        if (jsonSchema && typeof jsonSchema === "object") {
+          const rootChildren = buildSchemaChildren(jsonSchema);
+          for (const child of rootChildren) {
+            rows += renderSchemaFieldNode(child, 0, "");
+          }
         }
 
+        if (!responseDesc && !rows) continue;
+
+        const descHtml = responseDesc
+          ? ' <span class="normal-case font-sans opacity-70 ml-1">\u2014 ' + escapeHtml(responseDesc) + '</span>'
+          : "";
+        const contentHtml = rows || '<p class="text-xs opacity-60 mt-1">No schema fields</p>';
+
         sections +=
-          '<div class="mb-4"><h4 class="text-xs font-mono uppercase tracking-wider opacity-70 mb-2">Status ' +
+          '<details class="mb-4">' +
+          '<summary class="list-none cursor-pointer">' +
+          '<h4 class="text-xs font-mono uppercase tracking-wider opacity-70 mb-2">Status ' +
           escapeHtml(statusCode) +
+          descHtml +
           "</h4>" +
-          rows +
-          "</div>";
+          "</summary>" +
+          contentHtml +
+          "</details>";
       }
 
       if (!sections) return "";
@@ -2242,6 +4803,7 @@ function renderOpenAPIDocsHtml(spec, openapiPath, tailwindScriptPath, logoDarkPa
           "w-full text-xs px-2.5 py-2 rounded border border-light-border dark:border-dark-border bg-light-bg dark:bg-dark-bg focus:outline-none focus:border-brand dark:focus:border-brand transition-colors font-mono";
         keyInput.addEventListener("input", () => {
           entry.key = keyInput.value;
+          saveHeaders();
           updateRequestPreview();
         });
 
@@ -2256,6 +4818,7 @@ function renderOpenAPIDocsHtml(spec, openapiPath, tailwindScriptPath, logoDarkPa
           "w-full text-xs px-2.5 py-2 rounded border border-light-border dark:border-dark-border bg-light-bg dark:bg-dark-bg focus:outline-none focus:border-brand dark:focus:border-brand transition-colors font-mono";
         valueInput.addEventListener("input", () => {
           entry.value = valueInput.value;
+          saveHeaders();
           updateRequestPreview();
         });
 
@@ -2269,6 +4832,7 @@ function renderOpenAPIDocsHtml(spec, openapiPath, tailwindScriptPath, logoDarkPa
           '<svg class="w-3.5 h-3.5" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M6 12h12"></path></svg>';
         removeButton.addEventListener("click", () => {
           requestHeaders.splice(index, 1);
+          saveHeaders();
           renderHeaderInputs();
           updateRequestPreview();
         });
@@ -2285,15 +4849,32 @@ function renderOpenAPIDocsHtml(spec, openapiPath, tailwindScriptPath, logoDarkPa
       return Object.keys(headers).some((key) => key.toLowerCase() === target);
     }
 
-    function getRequestHeadersObject() {
-      const headers = {};
+    function buildCookieHeaderValue(cookieValues) {
+      const entries = Object.entries(cookieValues);
+      if (!entries.length) return "";
+      return entries
+        .map(([name, value]) => String(name) + "=" + encodeURIComponent(String(value)))
+        .join("; ");
+    }
+
+    function getRequestHeadersObject(op) {
+      const auth = getAuthHeaders(op);
+      const authCookies = getAuthCookieParams(op);
+      if (Object.keys(authCookies).length > 0) {
+        const cookieHeader = buildCookieHeaderValue(authCookies);
+        if (cookieHeader) {
+          auth["Cookie"] = cookieHeader;
+        }
+      }
+      const manual = {};
       for (const entry of requestHeaders) {
         const key = String(entry.key || "").trim();
         const value = String(entry.value || "").trim();
         if (!key || !value) continue;
-        headers[key] = value;
+        manual[key] = value;
       }
-      return headers;
+      // Auth provides defaults; manual headers win on conflict
+      return Object.assign({}, auth, manual);
     }
 
     function buildCurl(op, headers, body, requestPath) {
@@ -2330,6 +4911,33 @@ function renderOpenAPIDocsHtml(spec, openapiPath, tailwindScriptPath, logoDarkPa
         .replace(/>/g, "&gt;");
     }
 
+    function escapeHtmlAttribute(value) {
+      return String(value)
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&#39;");
+    }
+
+    function renderMarkdown(text) {
+      if (!text || typeof text !== "string") return "";
+      var s = escapeHtml(text);
+      // inline code \u2014 process first to protect content inside backticks
+      s = s.replace(/\`([^\`\\n]+)\`/g, '<code class="text-xs font-mono bg-black/5 dark:bg-white/5 px-1 py-0.5 rounded">$1</code>');
+      // bold **text**
+      s = s.replace(/\\*\\*([^*\\n]+)\\*\\*/g, '<strong>$1</strong>');
+      // italic *text*
+      s = s.replace(/\\*([^*\\n]+)\\*/g, '<em>$1</em>');
+      // links [text](url)
+      s = s.replace(/\\[([^\\]]+)\\]\\(([^)]+)\\)/g, function(m, txt, url) {
+        var lc = url.toLowerCase().replace(/\\s/g, "");
+        if (lc.indexOf("javascript:") === 0 || lc.indexOf("data:") === 0 || lc.indexOf("vbscript:") === 0) return txt;
+        return '<a href="' + url.replace(/"/g, '&quot;') + '" target="_blank" rel="noopener noreferrer" class="text-brand hover:underline">' + txt + '</a>';
+      });
+      return s;
+    }
+
     function toPrettyJson(value) {
       const trimmed = (value || "").trim();
       if (!trimmed) return null;
@@ -2463,10 +5071,10 @@ function renderOpenAPIDocsHtml(spec, openapiPath, tailwindScriptPath, logoDarkPa
 
       const { path, query } = getOperationParameterGroups(selected);
       const values = getParameterValues(selected);
-      const requestPath = buildRequestPath(selected, path, query, values);
+      const requestPath = buildRequestPath(selected, path, query, values, getAuthQueryParams(selected));
       const bodyInput = document.getElementById("body-input");
       const body = bodyInput ? bodyInput.value.trim() : "";
-      const headers = getRequestHeadersObject();
+      const headers = getRequestHeadersObject(selected);
       if (body && !hasHeaderName(headers, "Content-Type")) {
         headers["Content-Type"] = "application/json";
       }
@@ -2517,8 +5125,13 @@ function renderOpenAPIDocsHtml(spec, openapiPath, tailwindScriptPath, logoDarkPa
       }
       setResponseContent("", "", false);
 
+      const deprecatedBanner = document.getElementById("deprecated-banner");
+      if (deprecatedBanner) {
+        deprecatedBanner.classList.toggle("hidden", !op.deprecated);
+      }
+
       document.getElementById("tag-title").textContent = selected.tag;
-      document.getElementById("tag-description").textContent = op.description || "Interactive API documentation.";
+      document.getElementById("tag-description").innerHTML = op.description ? renderMarkdown(op.description) : "Interactive API documentation.";
       const methodNode = document.getElementById("endpoint-method");
       methodNode.textContent = selected.method;
       methodNode.className = "px-2.5 py-0.5 rounded-full text-xs font-mono font-medium " + (methodBadge[selected.method] || methodBadgeDefault);
@@ -2535,7 +5148,13 @@ function renderOpenAPIDocsHtml(spec, openapiPath, tailwindScriptPath, logoDarkPa
 
       html += renderRequestBodySchemaSection(reqSchema);
       html += renderResponseSchemasSection(op.responses);
-      document.getElementById("params-column").innerHTML = html || '<div class="text-sm opacity-70">No parameters</div>';
+      const paramsColumn = document.getElementById("params-column");
+      if (paramsColumn) {
+        hideParamTooltip();
+        paramsColumn.innerHTML = html || '<div class="text-sm opacity-70">No parameters</div>';
+        registerParamTooltipTargets(paramsColumn);
+      }
+      renderAuthPanel();
       renderTryItParameterInputs(path, query);
       renderHeaderInputs();
       updateRequestPreview();
@@ -2546,6 +5165,24 @@ function renderOpenAPIDocsHtml(spec, openapiPath, tailwindScriptPath, logoDarkPa
     document.getElementById("copy-curl").addEventListener("click", async () => {
       try { await navigator.clipboard.writeText(document.getElementById("curl-code").textContent || ""); } catch {}
     });
+    if (paramTooltipRoot) {
+      paramTooltipRoot.addEventListener("mouseenter", () => {
+        if (paramTooltipHideTimer) {
+          window.clearTimeout(paramTooltipHideTimer);
+          paramTooltipHideTimer = null;
+        }
+      });
+      paramTooltipRoot.addEventListener("mouseleave", () => {
+        scheduleParamTooltipHide();
+      });
+    }
+    document.addEventListener("pointerdown", (event) => {
+      if (!paramTooltipRoot) return;
+      const target = event.target;
+      if (target && paramTooltipRoot.contains(target)) return;
+      if (target && target.closest && target.closest("[data-param-tooltip-value]")) return;
+      hideParamTooltip();
+    });
     document.getElementById("sidebar-search").addEventListener("input", (event) => {
       sidebarSearchQuery = event.currentTarget.value || "";
       renderSidebar();
@@ -2571,7 +5208,7 @@ function renderOpenAPIDocsHtml(spec, openapiPath, tailwindScriptPath, logoDarkPa
         return;
       }
 
-      const requestPath = buildRequestPath(selected, path, query, values);
+      const requestPath = buildRequestPath(selected, path, query, values, getAuthQueryParams(selected));
       formatBodyJsonInput();
       updateBodyJsonPresentation();
       const op = selected.operation || {};
@@ -2580,7 +5217,7 @@ function renderOpenAPIDocsHtml(spec, openapiPath, tailwindScriptPath, logoDarkPa
       const bodyInput = document.getElementById("body-input");
       const body =
         supportsBody && bodyInput ? bodyInput.value.trim() : "";
-      const headers = getRequestHeadersObject();
+      const headers = getRequestHeadersObject(selected);
       if (body && !hasHeaderName(headers, "Content-Type")) {
         headers["Content-Type"] = "application/json";
       }
@@ -2588,7 +5225,13 @@ function renderOpenAPIDocsHtml(spec, openapiPath, tailwindScriptPath, logoDarkPa
       setSubmitLoading(true);
       try {
         const requestStart = performance.now();
-        const response = await fetch(requestPath, { method: selected.method, headers, body: body || undefined });
+        applyAuthCookies(selected);
+        const response = await fetch(requestPath, {
+          method: selected.method,
+          headers,
+          body: body || undefined,
+          credentials: "same-origin",
+        });
         const text = await response.text();
         const responseTimeMs = Math.round(performance.now() - requestStart);
         const contentType = response.headers.get("content-type") || "unknown";
@@ -2664,6 +5307,7 @@ function renderOpenAPIDocsHtml(spec, openapiPath, tailwindScriptPath, logoDarkPa
 
     document.getElementById("add-header-btn").addEventListener("click", () => {
       requestHeaders.push({ key: "", value: "" });
+      saveHeaders();
       renderHeaderInputs();
       updateRequestPreview();
     });
@@ -2777,12 +5421,21 @@ function renderOpenAPIDocsHtml(spec, openapiPath, tailwindScriptPath, logoDarkPa
       setMobileSidebarOpen(false);
     });
     window.addEventListener("resize", () => {
+      if (activeParamTooltipTrigger) {
+        positionParamTooltip(activeParamTooltipTrigger);
+      }
       if (window.innerWidth >= 768 && isMobileSidebarOpen) {
         setMobileSidebarOpen(false);
       }
     });
+    window.addEventListener("scroll", () => {
+      if (activeParamTooltipTrigger) {
+        positionParamTooltip(activeParamTooltipTrigger);
+      }
+    }, true);
     document.addEventListener("keydown", (event) => {
       if (event.key === "Escape") {
+        hideParamTooltip();
         if (isMobileSidebarOpen) {
           setMobileSidebarOpen(false);
         }
@@ -2807,7 +5460,444 @@ function renderOpenAPIDocsHtml(spec, openapiPath, tailwindScriptPath, logoDarkPa
       }
     });
 
+    function getOperationSecurityRequirements(op) {
+      const operationSecurity = op && op.operation && Array.isArray(op.operation.security)
+        ? op.operation.security
+        : null;
+      if (operationSecurity) {
+        return operationSecurity;
+      }
+      return Array.isArray(spec.security) ? spec.security : [];
+    }
+
+    function getAuthSelectionKeyForOperation(op) {
+      if (!op) return "";
+      return getOperationKey(op);
+    }
+
+    function getAuthSchemeOptionsForOperation(op) {
+      const requirements = getOperationSecurityRequirements(op).filter((requirement) =>
+        requirement && typeof requirement === "object" && !Array.isArray(requirement)
+      );
+      if (!requirements.length) return [];
+
+      const seen = new Set();
+      const options = [];
+      for (const requirement of requirements) {
+        for (const schemeName of Object.keys(requirement)) {
+          if (!Object.prototype.hasOwnProperty.call(authSchemes, schemeName)) continue;
+          if (seen.has(schemeName)) continue;
+          seen.add(schemeName);
+          options.push(schemeName);
+        }
+      }
+      return options;
+    }
+
+    function getSelectedAuthSchemeForOperation(op) {
+      const selectionKey = getAuthSelectionKeyForOperation(op);
+      if (!selectionKey) return null;
+
+      const selectedScheme = authSelectionState[selectionKey];
+      if (!selectedScheme || typeof selectedScheme !== "string") return null;
+
+      const options = Object.keys(authSchemes);
+      if (!options.includes(selectedScheme)) {
+        delete authSelectionState[selectionKey];
+        saveAuthSelectionState();
+        return null;
+      }
+
+      return selectedScheme;
+    }
+
+    function setSelectedAuthSchemeForOperation(op, schemeName) {
+      const selectionKey = getAuthSelectionKeyForOperation(op);
+      if (!selectionKey) return;
+
+      if (!schemeName) {
+        delete authSelectionState[selectionKey];
+      } else {
+        authSelectionState[selectionKey] = schemeName;
+      }
+      saveAuthSelectionState();
+    }
+
+    function hasAuthStateForScheme(schemeName) {
+      const scheme = authSchemes[schemeName];
+      if (!scheme) return false;
+
+      const state = authState[schemeName] || {};
+      const type = (scheme.type || "").toLowerCase();
+      const httpScheme = (scheme.scheme || "").toLowerCase();
+
+      if (type === "http" && httpScheme === "basic") {
+        return Boolean(state.username && state.password);
+      }
+      if (type === "http") {
+        return Boolean(state.token);
+      }
+      if (type === "apikey") {
+        return Boolean(state.value);
+      }
+      if (type === "oauth2" || type === "openidconnect") {
+        return Boolean(state.token);
+      }
+
+      return false;
+    }
+
+    function chooseOperationSecurityRequirement(op) {
+      const requirements = getOperationSecurityRequirements(op).filter((requirement) =>
+        requirement && typeof requirement === "object" && !Array.isArray(requirement)
+      );
+      if (!requirements.length) return null;
+
+      const selectedScheme = getSelectedAuthSchemeForOperation(op);
+      if (selectedScheme) {
+        const selectedRequirement = requirements.find((requirement) =>
+          Object.prototype.hasOwnProperty.call(requirement, selectedScheme)
+        );
+        if (selectedRequirement) return selectedRequirement;
+      }
+
+      let bestRequirement = null;
+      let bestScore = -1;
+
+      for (const requirement of requirements) {
+        const schemeNames = Object.keys(requirement).filter((schemeName) =>
+          Object.prototype.hasOwnProperty.call(authSchemes, schemeName)
+        );
+        if (!schemeNames.length) continue;
+
+        const providedCount = schemeNames.filter((schemeName) => hasAuthStateForScheme(schemeName)).length;
+        const isComplete = providedCount === schemeNames.length;
+        const score = isComplete ? 1000 + providedCount : providedCount;
+
+        if (score > bestScore) {
+          bestScore = score;
+          bestRequirement = requirement;
+        }
+      }
+
+      return bestRequirement || requirements[0];
+    }
+
+    function getAuthSchemeNamesForOperation(op) {
+      const schemeNames = Object.keys(authSchemes);
+      if (!schemeNames.length) return [];
+
+      const selectedScheme = getSelectedAuthSchemeForOperation(op);
+      if (selectedScheme) {
+        const requirement = chooseOperationSecurityRequirement(op);
+        if (requirement && Object.prototype.hasOwnProperty.call(requirement, selectedScheme)) {
+          return Object.keys(requirement).filter((schemeName) =>
+            Object.prototype.hasOwnProperty.call(authSchemes, schemeName)
+          );
+        }
+        return [selectedScheme];
+      }
+
+      const requirement = chooseOperationSecurityRequirement(op);
+      if (!requirement) return [];
+
+      return Object.keys(requirement).filter((schemeName) =>
+        Object.prototype.hasOwnProperty.call(authSchemes, schemeName)
+      );
+    }
+
+    function getAuthHeaders(op) {
+      const headers = {};
+      const schemeNames = getAuthSchemeNamesForOperation(op);
+      const allSchemeNames = Object.keys(authSchemes);
+
+      if (!allSchemeNames.length) {
+        const state = authState["__default__"] || {};
+        if (state.token) headers["Authorization"] = "Bearer " + state.token;
+        return headers;
+      }
+      if (!schemeNames.length) return headers;
+
+      for (const schemeName of schemeNames) {
+        const scheme = authSchemes[schemeName];
+        const state = authState[schemeName] || {};
+        const type = (scheme.type || "").toLowerCase();
+        const httpScheme = (scheme.scheme || "").toLowerCase();
+
+        if (type === "http" && httpScheme === "basic") {
+          if (state.username && state.password) {
+            try {
+              headers["Authorization"] = "Basic " + btoa(state.username + ":" + state.password);
+            } catch {}
+          }
+        } else if (type === "http") {
+          if (state.token) headers["Authorization"] = "Bearer " + state.token;
+        } else if (type === "apikey" && (scheme.in || "").toLowerCase() === "header") {
+          if (state.value && scheme.name) headers[scheme.name] = state.value;
+        } else if (type === "oauth2" || type === "openidconnect") {
+          if (state.token) headers["Authorization"] = "Bearer " + state.token;
+        }
+      }
+      return headers;
+    }
+
+    function getAuthQueryParams(op) {
+      const params = {};
+      for (const schemeName of getAuthSchemeNamesForOperation(op)) {
+        const scheme = authSchemes[schemeName];
+        if ((scheme.type || "").toLowerCase() === "apikey" && (scheme.in || "").toLowerCase() === "query") {
+          const state = authState[schemeName] || {};
+          if (state.value && scheme.name) params[scheme.name] = state.value;
+        }
+      }
+      return params;
+    }
+
+    function getAuthCookieParams(op) {
+      const cookies = {};
+      for (const schemeName of getAuthSchemeNamesForOperation(op)) {
+        const scheme = authSchemes[schemeName];
+        if ((scheme.type || "").toLowerCase() !== "apikey") continue;
+        if ((scheme.in || "").toLowerCase() !== "cookie") continue;
+        const state = authState[schemeName] || {};
+        if (state.value && scheme.name) {
+          cookies[scheme.name] = state.value;
+        }
+      }
+      return cookies;
+    }
+
+    function applyAuthCookies(op) {
+      const cookies = getAuthCookieParams(op);
+      for (const [name, value] of Object.entries(cookies)) {
+        try {
+          document.cookie = encodeURIComponent(String(name)) + "=" + encodeURIComponent(String(value)) + "; path=/";
+        } catch {}
+      }
+    }
+
+    function renderAuthPanel() {
+      const fields = document.getElementById("auth-fields");
+      if (!fields) return;
+      fields.innerHTML = "";
+
+      const schemeNames = Object.keys(authSchemes);
+      const op = selected;
+      const operationSchemeOptions = op ? getAuthSchemeOptionsForOperation(op) : [];
+      const availableSchemeOptions = Object.keys(authSchemes);
+      const selectedScheme = op ? getSelectedAuthSchemeForOperation(op) : null;
+
+      function getAuthSchemeDisplayLabel(schemeName) {
+        const scheme = authSchemes[schemeName] || {};
+        const type = (scheme.type || "").toLowerCase();
+        const httpScheme = (scheme.scheme || "").toLowerCase();
+        const location = (scheme.in || "").toLowerCase();
+
+        if (type === "http" && httpScheme === "basic") return "HTTP Basic";
+        if (type === "http" && httpScheme === "bearer") return "HTTP Bearer";
+        if (type === "http" && httpScheme === "digest") return "HTTP Digest";
+        if (type === "http") return "HTTP " + (httpScheme || "Token");
+        if (type === "apikey") return "API Key" + (location ? " (" + location + ")" : "");
+        if (type === "oauth2") return "OAuth 2.0";
+        if (type === "openidconnect") return "OpenID Connect";
+        if (type === "mutualtls") return "Mutual TLS";
+        return schemeName;
+      }
+
+      function makeInput(placeholder, value, onInput, type) {
+        const inp = document.createElement("input");
+        inp.type = type || "text";
+        inp.value = value || "";
+        inp.placeholder = placeholder;
+        inp.className = "w-full text-xs px-2.5 py-2 rounded-md border border-light-border dark:border-dark-border bg-light-bg dark:bg-dark-bg focus:outline-none focus:border-brand dark:focus:border-brand transition-colors font-mono";
+        inp.addEventListener("input", onInput);
+        return inp;
+      }
+
+      function makeLabel(text, small) {
+        const el = document.createElement("p");
+        el.className = small
+          ? "text-[10px] font-medium uppercase tracking-wider opacity-55"
+          : "text-[10px] font-semibold uppercase tracking-wider opacity-55";
+        el.textContent = text;
+        return el;
+      }
+
+      function makeField(label, input) {
+        const wrapper = document.createElement("div");
+        wrapper.className = "space-y-1";
+        wrapper.appendChild(makeLabel(label, true));
+        wrapper.appendChild(input);
+        return wrapper;
+      }
+
+      function makeSchemeCard(title, subtitle) {
+        const card = document.createElement("div");
+        card.className = "space-y-2 rounded-md border border-light-border dark:border-dark-border bg-light-bg/40 dark:bg-dark-bg/40 p-2.5";
+
+        const titleRow = document.createElement("div");
+        titleRow.className = "flex items-center justify-between gap-2";
+
+        const heading = document.createElement("p");
+        heading.className = "text-[11px] font-semibold tracking-wide";
+        heading.textContent = title;
+        titleRow.appendChild(heading);
+
+        if (subtitle) {
+          const note = document.createElement("span");
+          note.className = "text-[10px] opacity-60 font-mono";
+          note.textContent = subtitle;
+          titleRow.appendChild(note);
+        }
+
+        card.appendChild(titleRow);
+        return card;
+      }
+
+      if (!schemeNames.length) {
+        if (!authState["__default__"]) authState["__default__"] = {};
+        const defaultCard = makeSchemeCard("Default Auth", "bearer");
+        defaultCard.appendChild(makeField("Token", makeInput("Enter token\u2026", authState["__default__"].token, function(e) {
+          authState["__default__"].token = e.target.value;
+          saveAuthState();
+          updateRequestPreview();
+        })));
+        fields.appendChild(defaultCard);
+        return;
+      }
+
+      if (op && availableSchemeOptions.length > 0) {
+        const selectorWrap = document.createElement("div");
+        selectorWrap.className = "space-y-1";
+        selectorWrap.appendChild(makeLabel("Auth Type"));
+        const select = document.createElement("select");
+        select.className = "w-full text-xs px-2.5 py-2 rounded-md border border-light-border dark:border-dark-border bg-light-bg dark:bg-dark-bg focus:outline-none focus:border-brand dark:focus:border-brand transition-colors font-mono";
+
+        const autoOption = document.createElement("option");
+        autoOption.value = "";
+        autoOption.textContent = "Auto";
+        select.appendChild(autoOption);
+
+        for (const schemeName of availableSchemeOptions) {
+          const option = document.createElement("option");
+          option.value = schemeName;
+          const isOperationScheme = operationSchemeOptions.includes(schemeName);
+          const label = getAuthSchemeDisplayLabel(schemeName);
+          option.textContent = isOperationScheme
+            ? label
+            : (label + " \u2022 override");
+          select.appendChild(option);
+        }
+
+        select.value = selectedScheme || "";
+        select.addEventListener("change", function(e) {
+          setSelectedAuthSchemeForOperation(op, e.target.value || "");
+          renderAuthPanel();
+          updateRequestPreview();
+        });
+        selectorWrap.appendChild(select);
+        fields.appendChild(selectorWrap);
+      }
+
+      const schemesToRender = selectedScheme
+        ? [selectedScheme]
+        : (operationSchemeOptions.length ? operationSchemeOptions : schemeNames);
+
+      for (const schemeName of schemesToRender) {
+        const scheme = authSchemes[schemeName];
+        if (!authState[schemeName]) authState[schemeName] = {};
+        const state = authState[schemeName];
+        const type = (scheme.type || "").toLowerCase();
+        const httpScheme = (scheme.scheme || "").toLowerCase();
+        const card = makeSchemeCard(getAuthSchemeDisplayLabel(schemeName), schemeName);
+
+        if (type === "http" && httpScheme === "basic") {
+          card.appendChild(makeField("Username", makeInput("Username", state.username, function(e) {
+            authState[schemeName].username = e.target.value;
+            saveAuthState();
+            updateRequestPreview();
+          })));
+          card.appendChild(makeField("Password", makeInput("Password", state.password, function(e) {
+            authState[schemeName].password = e.target.value;
+            saveAuthState();
+            updateRequestPreview();
+          }, "password")));
+        } else if (type === "apikey") {
+          const paramName = scheme.name || "key";
+          const location = (scheme.in || "header").toLowerCase();
+          card.appendChild(makeField("API Key", makeInput(paramName + " (" + location + ")", state.value, function(e) {
+            authState[schemeName].value = e.target.value;
+            saveAuthState();
+            updateRequestPreview();
+          })));
+        } else if (type === "oauth2") {
+          card.appendChild(makeField("Access Token", makeInput("OAuth2 access token\u2026", state.token, function(e) {
+            authState[schemeName].token = e.target.value;
+            saveAuthState();
+            updateRequestPreview();
+          })));
+        } else if (type === "openidconnect") {
+          card.appendChild(makeField("ID Token / Access Token", makeInput("OpenID Connect token\u2026", state.token, function(e) {
+            authState[schemeName].token = e.target.value;
+            saveAuthState();
+            updateRequestPreview();
+          })));
+        } else if (type === "http" && httpScheme === "digest") {
+          card.appendChild(makeField("Digest Credential", makeInput("Digest token\u2026", state.token, function(e) {
+            authState[schemeName].token = e.target.value;
+            saveAuthState();
+            updateRequestPreview();
+          })));
+        } else if (type === "http" && httpScheme === "bearer") {
+          card.appendChild(makeField("Bearer Token", makeInput("Bearer token\u2026", state.token, function(e) {
+            authState[schemeName].token = e.target.value;
+            saveAuthState();
+            updateRequestPreview();
+          })));
+        } else if (type === "mutualtls") {
+          const hint = document.createElement("p");
+          hint.className = "text-xs opacity-70 leading-relaxed";
+          hint.textContent = "Configured by your client certificate. No token input required.";
+          card.appendChild(hint);
+        } else {
+          card.appendChild(makeField("Token", makeInput("Token\u2026", state.token, function(e) {
+            authState[schemeName].token = e.target.value;
+            saveAuthState();
+            updateRequestPreview();
+          })));
+        }
+        fields.appendChild(card);
+      }
+    }
+
+    let authPanelOpen = true;
+    document.getElementById("auth-toggle").addEventListener("click", function() {
+      authPanelOpen = !authPanelOpen;
+      const fieldsEl = document.getElementById("auth-fields");
+      const chevron = document.getElementById("auth-chevron");
+      if (fieldsEl) fieldsEl.classList.toggle("hidden", !authPanelOpen);
+      if (chevron) chevron.style.transform = authPanelOpen ? "" : "rotate(-90deg)";
+    });
+
+    // Restore selected operation from URL hash, or set hash for the default selection
+    var initMatch = findOpByHash(window.location.hash);
+    if (initMatch) {
+      selected = initMatch;
+    } else if (selected) {
+      history.replaceState(null, "", getOpHash(selected));
+    }
+
+    window.addEventListener("popstate", function() {
+      var match = findOpByHash(window.location.hash);
+      if (match) {
+        selected = match;
+        renderSidebar();
+        renderEndpoint();
+      }
+    });
+
     setMobileSidebarOpen(false);
+    renderAuthPanel();
     renderSidebar();
     renderEndpoint();
   </script>
@@ -2816,6 +5906,106 @@ function renderOpenAPIDocsHtml(spec, openapiPath, tailwindScriptPath, logoDarkPa
 }
 
 // src/openapi/generator.ts
+var AUTH_KIND_VALUES2 = new Set(Object.values(AuthKind));
+var DEFAULT_SECURITY_SCHEME_NAMES = {
+  ["ApiKey" /* ApiKey */]: "apiKeyAuth",
+  ["HttpBasic" /* HttpBasic */]: "basicAuth",
+  ["HttpBearer" /* HttpBearer */]: "bearerAuth",
+  ["HttpDigest" /* HttpDigest */]: "digestAuth",
+  ["OAuth2" /* OAuth2 */]: "oauth2Auth",
+  ["OpenIdConnect" /* OpenIdConnect */]: "openIdConnectAuth",
+  ["MutualTls" /* MutualTls */]: "mutualTlsAuth"
+};
+function isAuthKind(value) {
+  return typeof value === "string" && AUTH_KIND_VALUES2.has(value);
+}
+function resolveRouteAuthKind(routeAuth, defaultAuthKind) {
+  if (routeAuth === undefined || routeAuth === false || routeAuth === null) {
+    return null;
+  }
+  if (routeAuth === true) {
+    return defaultAuthKind;
+  }
+  if (isAuthKind(routeAuth)) {
+    return routeAuth;
+  }
+  return defaultAuthKind;
+}
+function resolveSecuritySchemeName(kind, authOptions) {
+  const configuredName = authOptions?.securitySchemeNames?.[kind];
+  if (typeof configuredName === "string" && configuredName.trim().length > 0) {
+    return configuredName.trim();
+  }
+  return DEFAULT_SECURITY_SCHEME_NAMES[kind];
+}
+function toOpenApiSecurityScheme(kind) {
+  switch (kind) {
+    case "ApiKey" /* ApiKey */:
+      return {
+        type: "apiKey" /* ApiKey */,
+        name: "X-API-Key",
+        in: "header"
+      };
+    case "HttpBasic" /* HttpBasic */:
+      return {
+        type: "http" /* Http */,
+        scheme: "basic" /* Basic */
+      };
+    case "HttpBearer" /* HttpBearer */:
+      return {
+        type: "http" /* Http */,
+        scheme: "bearer" /* Bearer */,
+        bearerFormat: "JWT"
+      };
+    case "HttpDigest" /* HttpDigest */:
+      return {
+        type: "http" /* Http */,
+        scheme: "digest" /* Digest */
+      };
+    case "OAuth2" /* OAuth2 */:
+      return {
+        type: "oauth2" /* OAuth2 */,
+        flows: {
+          authorizationCode: {
+            authorizationUrl: "https://example.com/oauth/authorize",
+            tokenUrl: "https://example.com/oauth/token",
+            scopes: {}
+          }
+        }
+      };
+    case "OpenIdConnect" /* OpenIdConnect */:
+      return {
+        type: "openIdConnect" /* OpenIdConnect */,
+        openIdConnectUrl: "https://example.com/.well-known/openid-configuration"
+      };
+    case "MutualTls" /* MutualTls */:
+      return {
+        type: "mutualTLS" /* MutualTls */
+      };
+    default: {
+      const exhaustiveCheck = kind;
+      return exhaustiveCheck;
+    }
+  }
+}
+function resolveSecurityScheme(kind, authOptions) {
+  const defaultScheme = toOpenApiSecurityScheme(kind);
+  const override = authOptions?.securitySchemes?.[kind];
+  if (!override) {
+    return defaultScheme;
+  }
+  const merged = {
+    ...defaultScheme,
+    ...override
+  };
+  if (isRecord(defaultScheme.flows) && isRecord(override.flows)) {
+    merged.flows = {
+      ...defaultScheme.flows,
+      ...override.flows
+    };
+  }
+  return merged;
+}
 function isJSONSchemaCapable(schema) {
   const standard = schema?.["~standard"];
   const converter = standard?.jsonSchema;
@@ -2887,15 +6077,88 @@ function isNoBodyResponseStatus(status) {
   return numericStatus >= 100 && numericStatus < 200 || numericStatus === 204 || numericStatus === 205 || numericStatus === 304;
 }
 function getResponseDescription(status) {
-  if (status === "204")
-    return "No Content";
-  if (status === "205")
-    return "Reset Content";
-  if (status === "304")
-    return "Not Modified";
+  const knownDescriptions = {
+    "100": "Continue",
+    "101": "Switching Protocols",
+    "102": "Processing",
+    "103": "Early Hints",
+    "200": "OK",
+    "201": "Created",
+    "202": "Accepted",
+    "203": "Non-Authoritative Information",
+    "204": "No Content",
+    "205": "Reset Content",
+    "206": "Partial Content",
+    "207": "Multi-Status",
+    "208": "Already Reported",
+    "226": "IM Used",
+    "300": "Multiple Choices",
+    "301": "Moved Permanently",
+    "302": "Found",
+    "303": "See Other",
+    "304": "Not Modified",
+    "305": "Use Proxy",
+    "307": "Temporary Redirect",
+    "308": "Permanent Redirect",
+    "400": "Bad Request",
+    "401": "Unauthorized",
+    "402": "Payment Required",
+    "403": "Forbidden",
+    "404": "Not Found",
+    "405": "Method Not Allowed",
+    "406": "Not Acceptable",
+    "407": "Proxy Authentication Required",
+    "408": "Request Timeout",
+    "409": "Conflict",
+    "410": "Gone",
+    "411": "Length Required",
+    "412": "Precondition Failed",
+    "413": "Payload Too Large",
+    "414": "URI Too Long",
+    "415": "Unsupported Media Type",
+    "416": "Range Not Satisfiable",
+    "417": "Expectation Failed",
+    "418": "I'm a teapot",
+    "421": "Misdirected Request",
+    "422": "Unprocessable Content",
+    "423": "Locked",
+    "424": "Failed Dependency",
+    "425": "Too Early",
+    "426": "Upgrade Required",
+    "428": "Precondition Required",
+    "429": "Too Many Requests",
+    "431": "Request Header Fields Too Large",
+    "451": "Unavailable For Legal Reasons",
+    "500": "Internal Server Error",
+    "501": "Not Implemented",
+    "502": "Bad Gateway",
+    "503": "Service Unavailable",
+    "504": "Gateway Timeout",
+    "505": "HTTP Version Not Supported",
+    "506": "Variant Also Negotiates",
+    "507": "Insufficient Storage",
+    "508": "Loop Detected",
+    "510": "Not Extended",
+    "511": "Network Authentication Required"
+  };
+  if (knownDescriptions[status]) {
+    return knownDescriptions[status];
+  }
   const numericStatus = Number(status);
   if (Number.isInteger(numericStatus) && numericStatus >= 100 && numericStatus < 200) {
-    return "Informational";
+    return "Informational Response";
+  }
+  if (Number.isInteger(numericStatus) && numericStatus >= 200 && numericStatus < 300) {
+    return "Successful Response";
+  }
+  if (Number.isInteger(numericStatus) && numericStatus >= 300 && numericStatus < 400) {
+    return "Redirection";
+  }
+  if (Number.isInteger(numericStatus) && numericStatus >= 400 && numericStatus < 500) {
+    return "Client Error";
+  }
+  if (Number.isInteger(numericStatus) && numericStatus >= 500 && numericStatus < 600) {
+    return "Server Error";
   }
   return "OK";
 }
@@ -3330,6 +6593,8 @@ function addOutputSchemasToOperation(operation, routePath, routeSchema, target,
 function generateOpenAPIDocument(routes, options) {
   const warnings = [];
   const paths = {};
+  const defaultAuthKind = "HttpBearer" /* HttpBearer */;
+  const usedAuthKinds = new Set;
   for (const route of routes) {
     if (route.options.expose === false)
       continue;
@@ -3343,12 +6608,50 @@ function generateOpenAPIDocument(routes, options) {
       operationId: createOperationId(method, openapiPath),
       tags: [route.options.schema?.tag || inferTagFromPath(route.path)]
     };
+    if (typeof route.options.schema?.summary === "string" && route.options.schema.summary.trim()) {
+      operation.summary = route.options.schema.summary.trim();
+    }
+    const routeSchemaDescription = typeof route.options.schema?.description === "string" && route.options.schema.description.trim() ? route.options.schema.description.trim() : typeof route.options.schema?.descrition === "string" && route.options.schema.descrition.trim() ? route.options.schema.descrition.trim() : undefined;
+    if (routeSchemaDescription) {
+      operation.description = routeSchemaDescription;
+    }
+    if (route.options.deprecated === true) {
+      operation.deprecated = true;
+    }
+    const routeAuthKind = resolveRouteAuthKind(route.options.auth, defaultAuthKind);
+    if (routeAuthKind) {
+      usedAuthKinds.add(routeAuthKind);
+      const securitySchemeName = resolveSecuritySchemeName(routeAuthKind, options.auth);
+      operation.security = [{ [securitySchemeName]: [] }];
+    }
     const inputJSONSchema = convertInputSchema(route.path, route.options.schema?.input, options.target, warnings);
     if (inputJSONSchema) {
+      if (!operation.summary && typeof inputJSONSchema.title === "string" && inputJSONSchema.title.trim()) {
+        operation.summary = inputJSONSchema.title.trim();
+      }
+      if (!operation.description && typeof inputJSONSchema.description === "string" && inputJSONSchema.description.trim()) {
+        operation.description = inputJSONSchema.description.trim();
+      }
       addStructuredInputToOperation(operation, inputJSONSchema);
     }
     addMissingPathParameters(operation, route.path);
     addOutputSchemasToOperation(operation, route.path, route.options.schema || {}, options.target, warnings);
+    if (!operation.summary || !operation.description) {
+      const responseEntries = Object.values(operation.responses || {});
+      for (const response of responseEntries) {
+        const responseSchema = response?.content?.["application/json"]?.schema;
+        if (!responseSchema || typeof responseSchema !== "object")
+          continue;
+        if (!operation.summary && typeof responseSchema.title === "string" && responseSchema.title.trim()) {
+          operation.summary = responseSchema.title.trim();
+        }
+        if (!operation.description && typeof responseSchema.description === "string" && responseSchema.description.trim()) {
+          operation.description = responseSchema.description.trim();
+        }
+        if (operation.summary && operation.description)
+          break;
+      }
+    }
     paths[openapiPath] ||= {};
     paths[openapiPath][method] = operation;
   }
@@ -3362,6 +6665,16 @@ function generateOpenAPIDocument(routes, options) {
     },
     paths
   };
+  if (usedAuthKinds.size > 0) {
+    const securitySchemes = {};
+    for (const authKind of usedAuthKinds) {
+      const name = resolveSecuritySchemeName(authKind, options.auth);
+      securitySchemes[name] = resolveSecurityScheme(authKind, options.auth);
+    }
+    document.components = {
+      securitySchemes
+    };
+  }
   return {
     document,
     warnings
@@ -3498,6 +6811,17 @@ var OPENAPI_FAVICON_ASSETS = [
 var DOCS_HTML_CACHE_CONTROL = "public, max-age=0, must-revalidate";
 var DOCS_ASSET_CACHE_CONTROL = "public, max-age=31536000, immutable";
 var DOCS_ASSET_ERROR_CACHE_CONTROL = "no-store";
+var DEFAULT_PORT = 3000;
+function normalizePort(port) {
+  if (port === undefined) {
+    return DEFAULT_PORT;
+  }
+  const normalized = Number(port);
+  if (!Number.isInteger(normalized) || normalized < 0 || normalized > 65535) {
+    throw new Error(`Invalid port: ${String(port)}. Port must be an integer between 0 and 65535.`);
+  }
+  return normalized;
+}
 function escapeRegex(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
@@ -3559,6 +6883,9 @@ class VectorServer {
       this.router.setCorsHandler(this.corsHeadersEntries ? null : this.corsHandler.corsify);
     }
   }
+  setCheckpointGateway(gateway) {
+    this.router.setCheckpointGateway(gateway);
+  }
   normalizeOpenAPIConfig(openapi, development) {
     const isDev = development !== false && true;
     const defaultEnabled = isDev;
@@ -3590,7 +6917,8 @@ class VectorServer {
       path: openapiObject.path || "/openapi.json",
       target: openapiObject.target || "openapi-3.0",
       docs,
-      info: openapiObject.info
+      info: openapiObject.info,
+      auth: openapiObject.auth
     };
   }
   isDocsReservedPath(path) {
@@ -3612,7 +6940,8 @@ class VectorServer {
     const routes = this.router.getRouteDefinitions().filter((route) => !this.isDocsReservedPath(route.path));
     const result = generateOpenAPIDocument(routes, {
       target: this.openapiConfig.target,
-      info: this.openapiConfig.info
+      info: this.openapiConfig.info,
+      auth: this.openapiConfig.auth
     });
     if (!this.openapiWarningsLogged && result.warnings.length > 0) {
       if (this.shouldLogOpenAPIConversionWarnings()) {
@@ -3832,10 +7161,10 @@ class VectorServer {
     return response;
   }
   async start() {
-    const port = this.config.port ?? 3000;
+    const port = normalizePort(this.config.port);
     const hostname = this.config.hostname || "localhost";
     this.validateReservedOpenAPIPaths();
-    const fallbackFetch = async (request) => {
+    const appFetch = async (request) => {
       try {
         if (this.corsHandler && request.method === "OPTIONS") {
           return this.corsHandler.preflight(request);
@@ -3844,7 +7173,7 @@ class VectorServer {
         if (openapiResponse) {
           return this.applyCors(openapiResponse, request);
         }
-        return this.applyCors(STATIC_RESPONSES.NOT_FOUND.clone(), request);
+        return await this.router.handle(request);
       } catch (error) {
         console.error("Server error:", error);
         return this.applyCors(new Response("Internal Server Error", { status: 500 }), request);
@@ -3855,8 +7184,7 @@ class VectorServer {
         port,
         hostname,
         reusePort: this.config.reusePort !== false,
-        routes: this.router.getRouteTable(),
-        fetch: fallbackFetch,
+        fetch: appFetch,
         idleTimeout: this.config.idleTimeout ?? 60,
         error: (error, request) => {
           console.error("[ERROR] Server error:", error);
@@ -3895,7 +7223,7 @@ class VectorServer {
     return this.server;
   }
   getPort() {
-    return this.server?.port ?? this.config.port ?? 3000;
+    return this.server?.port ?? normalizePort(this.config.port);
   }
   getHostname() {
     return this.server?.hostname || this.config.hostname || "localhost";
@@ -3921,6 +7249,7 @@ class Vector {
   _protectedHandler = null;
   _cacheHandler = null;
   shutdownPromise = null;
+  checkpointProcessManager = null;
   constructor() {
     this.middlewareManager = new MiddlewareManager;
     this.authManager = new AuthManager;
@@ -3959,6 +7288,10 @@ class Vector {
     this.router.route(options, handler);
   }
   async startServer(config) {
+    if (this.checkpointProcessManager) {
+      await this.checkpointProcessManager.stopAll();
+      this.checkpointProcessManager = null;
+    }
     this.config = { ...this.config, ...config };
     const routeDefaults = { ...this.config.defaults?.route };
     this.router.setRouteBooleanDefaults(routeDefaults);
@@ -3981,6 +7314,9 @@ class Vector {
     }
     this.server = new VectorServer(this.router, this.config);
     const bunServer = await this.server.start();
+    if (this.config.checkpoint && this.config.checkpoint.enabled !== false) {
+      await this.enableCheckpointGateway(this.config.checkpoint);
+    }
     return bunServer;
   }
   async discoverRoutes() {
@@ -3999,7 +7335,7 @@ class Vector {
         for (const route of routes) {
           try {
             const importPath = toFileUrl(route.path);
-            const module = await import(importPath);
+            const module = await import(`${importPath}?t=${Date.now()}`);
             const exported = route.name === "default" ? module.default : module[route.name];
             if (exported) {
               if (this.isRouteDefinition(exported)) {
@@ -4052,6 +7388,41 @@ class Vector {
     return value !== null && typeof value === "object" && "entry" in value && "options" in value && "handler" in value && typeof value.handler === "function";
   }
   logRouteLoaded(_) {}
+  async enableCheckpointGateway(checkpointConfig) {
+    if (!this.server) {
+      throw new Error("Cannot enable checkpoint gateway before server is started. Call startServer() first.");
+    }
+    const { CheckpointManager: CheckpointManager2 } = await Promise.resolve().then(() => (init_manager(), exports_manager));
+    const { CheckpointProcessManager: CheckpointProcessManager2 } = await Promise.resolve().then(() => (init_process_manager(), exports_process_manager));
+    const { CheckpointResolver: CheckpointResolver2 } = await Promise.resolve().then(() => exports_resolver);
+    const { CheckpointForwarder: CheckpointForwarder2 } = await Promise.resolve().then(() => exports_forwarder);
+    const { CheckpointGateway: CheckpointGateway2 } = await Promise.resolve().then(() => exports_gateway);
+    if (this.checkpointProcessManager) {
+      await this.checkpointProcessManager.stopAll();
+      this.checkpointProcessManager = null;
+    }
+    const manager = new CheckpointManager2(checkpointConfig);
+    const processManager = new CheckpointProcessManager2({
+      idleTimeoutMs: checkpointConfig?.idleTimeoutMs
+    });
+    this.checkpointProcessManager = processManager;
+    const resolver = new CheckpointResolver2(manager, processManager, {
+      versionHeader: checkpointConfig?.versionHeader,
+      cacheKeyOverride: checkpointConfig?.cacheKeyOverride
+    });
+    const forwarder = new CheckpointForwarder2;
+    const gateway = new CheckpointGateway2(resolver, forwarder);
+    this.server.setCheckpointGateway(gateway);
+    const active = await manager.getActive();
+    if (active) {
+      try {
+        const manifest = await manager.readManifest(active.version);
+        await processManager.spawn(manifest, manager.getStorageDir());
+      } catch (err) {
+        console.error(`[Checkpoint] Failed to start active checkpoint ${active.version}:`, err);
+      }
+    }
+  }
   stop() {
     if (this.server) {
       this.server.stop();
@@ -4064,6 +7435,10 @@ class Vector {
     }
     this.shutdownPromise = (async () => {
       this.stop();
+      if (this.checkpointProcessManager) {
+        await this.checkpointProcessManager.stopAll();
+        this.checkpointProcessManager = null;
+      }
       if (typeof this.config.shutdown === "function") {
         await this.config.shutdown();
       }
@@ -4130,7 +7505,12 @@ async function startVector(options = {}) {
 
 // src/cli/index.ts
 var args = typeof Bun !== "undefined" ? Bun.argv.slice(2) : process.argv.slice(2);
-var { values, positionals } = parseArgs({
+if (args[0] === "checkpoint") {
+  const { runCheckpointCli: runCheckpointCli2 } = await Promise.resolve().then(() => (init_cli(), exports_cli));
+  await runCheckpointCli2(args.slice(1));
+  process.exit(0);
+}
+var { values, positionals } = parseArgs2({
   args,
   options: {
     port: {
@@ -4252,7 +7632,7 @@ Listening on ${cyan}http://${config.hostname}:${config.port}${reset}
               if (app) {
                 app.stop();
               }
-              await new Promise((resolve3) => setTimeout(resolve3, 100));
+              await new Promise((resolve5) => setTimeout(resolve5, 100));
               try {
                 const result2 = await startServer();
                 server = result2.server;
@@ -4299,8 +7679,9 @@ switch (command) {
 Usage: vector [command] [options]
 
 Commands:
-  dev     Start development server (default)
-  start   Start production server
+  dev       Start development server (default)
+  start     Start production server
+  checkpoint  Manage versioned checkpoints (publish, list, rollback, remove)
 
 Options:
   -p, --port <port>      Port to listen on (default: 3000)