veryfront 0.1.49 → 0.1.51

package/src/src/oauth/providers/base.ts

@@ -10,6 +10,13 @@ import type {
   TokenStore,
 } from "../types.js";
 import { getEnv } from "../../platform/compat/process.js";
+import { INVALID_ARGUMENT, TOKEN_STORAGE_ERROR } from "../../errors/index.js";
+
+/** Buffer before token expiry to trigger proactive refresh (5 minutes). */
+const TOKEN_REFRESH_BUFFER_MS = 300_000;
+
+/** Multiplier to convert `expires_in` (seconds) to milliseconds. */
+const SECONDS_TO_MS = 1_000;
 
 export type EnvReader = (key: string) => string | undefined;
 
@@ -59,7 +66,9 @@ export class OAuthProvider {
     options: AuthorizationUrlOptions & { defaultScopes?: string[] } = {},
   ): Promise<{ url: string; state: OAuthState }> {
     const clientId = this.getClientId();
-    if (!clientId) throw new Error(`${this.config.clientIdEnvVar} not configured`);
+    if (!clientId) {
+      throw INVALID_ARGUMENT.create({ detail: `${this.config.clientIdEnvVar} not configured` });
+    }
 
     const state = options.state ?? generateRandomString(32);
     const scopes = options.scopes ?? options.defaultScopes ?? [];
@@ -116,12 +125,21 @@ export class OAuthProvider {
   ): OAuthTokens {
     const mapping = this.config.tokenResponseMapping ?? {};
 
-    const accessToken = data[mapping.accessToken ?? "access_token"] as string;
-    const refreshToken = (data[mapping.refreshToken ?? "refresh_token"] as string | undefined) ??
+    const str = (key: string): string => {
+      const v = data[key];
+      return typeof v === "string" ? v : "";
+    };
+    const optStr = (key: string): string | undefined => {
+      const v = data[key];
+      return typeof v === "string" ? v : undefined;
+    };
+
+    const accessToken = str(mapping.accessToken ?? "access_token");
+    const refreshToken = optStr(mapping.refreshToken ?? "refresh_token") ??
       fallbackRefreshToken;
-    const tokenType = data[mapping.tokenType ?? "token_type"] as string;
-    const scope = data[mapping.scope ?? "scope"] as string;
-    const idToken = data.id_token as string | undefined;
+    const tokenType = str(mapping.tokenType ?? "token_type");
+    const scope = str(mapping.scope ?? "scope");
+    const idToken = optStr("id_token");
 
     const tokens: OAuthTokens = {
       accessToken,
@@ -131,8 +149,13 @@ export class OAuthProvider {
       idToken,
     };
 
-    const expiresIn = data[mapping.expiresIn ?? "expires_in"] as number | undefined;
-    if (expiresIn) tokens.expiresAt = Date.now() + expiresIn * 1000;
+    const rawExpiresIn = data[mapping.expiresIn ?? "expires_in"];
+    const expiresIn = typeof rawExpiresIn === "number"
+      ? rawExpiresIn
+      : typeof rawExpiresIn === "string"
+      ? Number(rawExpiresIn) || undefined
+      : undefined;
+    if (expiresIn) tokens.expiresAt = Date.now() + expiresIn * SECONDS_TO_MS;
 
     return tokens;
   }
@@ -174,8 +197,9 @@ export class OAuthProvider {
       if (!response.ok) {
         return {
           success: false,
-          error: (data.error as string) || errorFallback,
-          errorDescription: (data.error_description as string) ||
+          error: (typeof data.error === "string" ? data.error : "") || errorFallback,
+          errorDescription:
+            (typeof data.error_description === "string" ? data.error_description : "") ||
             (errorDescriptionFallback ? errorDescriptionFallback(response.status) : undefined),
         };
       }
@@ -257,7 +281,8 @@ export class OAuthProvider {
       });
 
       return response.ok;
-    } catch {
+    } catch (_) {
+      // expected: network failure during token revocation
       return false;
     }
   }
@@ -294,7 +319,7 @@ export class OAuthService extends OAuthProvider {
     const tokens = await this.tokenStore?.getTokens(this.serviceId);
     if (!tokens) return null;
 
-    const isExpired = tokens.expiresAt && Date.now() > tokens.expiresAt - 300000;
+    const isExpired = tokens.expiresAt && Date.now() > tokens.expiresAt - TOKEN_REFRESH_BUFFER_MS;
     if (!isExpired) return tokens.accessToken;
 
     if (!tokens.refreshToken) return null;
@@ -302,13 +327,20 @@ export class OAuthService extends OAuthProvider {
     const result = await this.refreshTokens(tokens.refreshToken);
     if (!result.success || !result.tokens) return null;
 
-    await this.tokenStore!.setTokens(this.serviceId, result.tokens);
+    if (!this.tokenStore) {
+      throw new Error("TokenStore not configured");
+    }
+    await this.tokenStore.setTokens(this.serviceId, result.tokens);
     return result.tokens.accessToken;
   }
 
   async fetch<T>(endpoint: string, options: dntShim.RequestInit = {}): Promise<T> {
     const token = await this.getAccessToken();
-    if (!token) throw new Error(`Not authenticated with ${this.serviceConfig.displayName}`);
+    if (!token) {
+      throw TOKEN_STORAGE_ERROR.create({
+        detail: `Not authenticated with ${this.serviceConfig.displayName}`,
+      });
+    }
 
     const url = endpoint.startsWith("http") ? endpoint : `${this.apiBaseUrl}${endpoint}`;
 
@@ -323,7 +355,9 @@ export class OAuthService extends OAuthProvider {
 
     if (!response.ok) {
       const error = await response.text();
-      throw new Error(`${this.serviceConfig.displayName} API error: ${response.status} ${error}`);
+      throw INVALID_ARGUMENT.create({
+        detail: `${this.serviceConfig.displayName} API error: ${response.status} ${error}`,
+      });
     }
 
     return response.json();

package/src/src/oauth/token-store/memory.ts

@@ -1,12 +1,12 @@
 import type { OAuthState, OAuthTokens, TokenStore } from "../types.js";
 
+/** How long an OAuth state nonce remains valid (10 minutes). */
+const STATE_EXPIRATION_MS = 10 * 60 * 1_000;
+
 export class MemoryTokenStore implements TokenStore {
   private tokens = new Map<string, OAuthTokens>();
   private states = new Map<string, OAuthState>();
 
-  /** State expiration time in ms (10 minutes) */
-  private stateExpirationMs = 10 * 60 * 1000;
-
   async getTokens(serviceId: string): Promise<OAuthTokens | null> {
     return this.tokens.get(serviceId) ?? null;
   }
@@ -23,7 +23,7 @@ export class MemoryTokenStore implements TokenStore {
     const oauthState = this.states.get(state);
     if (!oauthState) return null;
 
-    if (Date.now() - oauthState.createdAt > this.stateExpirationMs) {
+    if (Date.now() - oauthState.createdAt > STATE_EXPIRATION_MS) {
       this.states.delete(state);
       return null;
     }
@@ -43,7 +43,7 @@ export class MemoryTokenStore implements TokenStore {
   private cleanupExpiredStates(): void {
     const now = Date.now();
     for (const [state, oauthState] of this.states) {
-      if (now - oauthState.createdAt > this.stateExpirationMs) {
+      if (now - oauthState.createdAt > STATE_EXPIRATION_MS) {
         this.states.delete(state);
       }
     }

package/src/src/observability/auto-instrument/http-instrumentation.ts

@@ -93,8 +93,8 @@ export function createInstrumentedFetch(
       fetchAttrs["http.target"] = parsed.pathname;
       fetchAttrs["http.host"] = parsed.host;
       fetchAttrs["http.scheme"] = parsed.protocol.replace(":", "");
-    } catch {
-      // Relative URLs are fine; leave defaults
+    } catch (_) {
+      /* expected: relative URLs cannot be parsed, leave defaults */
     }
 
     try {

package/src/src/observability/auto-instrument/types.ts

@@ -1,8 +1,8 @@
 import type { RuntimeAdapter } from "../../platform/adapters/base.js";
 
-export type AttributeValue = string | number | boolean;
+type AttributeValue = string | number | boolean;
 
-export type SpanAttributes = Record<string, AttributeValue>;
+type SpanAttributes = Record<string, AttributeValue>;
 export type ErrorAttributes = Record<string, AttributeValue>;
 export type HttpAttributes = Record<string, AttributeValue>;
 
@@ -29,7 +29,7 @@ export interface AutoInstrumentConfig {
   captureErrors?: boolean;
 }
 
-export interface InstrumentationContext {
+interface InstrumentationContext {
   config: AutoInstrumentConfig;
   adapter?: RuntimeAdapter;
   initialized: boolean;

package/src/src/observability/error-collector.ts

@@ -6,6 +6,7 @@
  **************************/
 
 import type { ErrorCategory } from "../errors/types.js";
+import { INVALID_ARGUMENT } from "../errors/index.js";
 
 export type ErrorType = "compile" | "runtime" | "bundle" | "hmr" | "module";
 
@@ -75,9 +76,10 @@ export class ErrorCollector {
   add(error: Omit<DevError, "id" | "timestamp">): DevError {
     const expectedCategory = ERROR_TYPE_TO_CATEGORY[error.type];
     if (error.category !== expectedCategory) {
-      throw new Error(
-        `ErrorCollector.add() received mismatched type/category: ${error.type} must use ${expectedCategory}, got ${error.category}`,
-      );
+      throw INVALID_ARGUMENT.create({
+        detail:
+          `ErrorCollector.add() received mismatched type/category: ${error.type} must use ${expectedCategory}, got ${error.category}`,
+      });
     }
 
     const fullError: DevError = {
@@ -96,8 +98,8 @@ export class ErrorCollector {
     for (const subscriber of this.subscribers) {
       try {
         subscriber(fullError);
-      } catch {
-        // Ignore subscriber errors
+      } catch (_) {
+        /* expected: subscriber errors must not break error collection */
       }
     }
 

package/src/src/observability/log-buffer.ts

@@ -49,8 +49,8 @@ export class LogBuffer {
     for (const subscriber of this.subscribers) {
       try {
         subscriber(fullEntry);
-      } catch {
-        // Ignore subscriber errors
+      } catch (_) {
+        /* expected: subscriber errors must not break log buffering */
       }
     }
 
@@ -187,7 +187,8 @@ export function interceptConsole(buffer: LogBuffer, source = "console"): () => v
 
         try {
           return JSON.stringify(a);
-        } catch {
+        } catch (_) {
+          /* expected: circular references or non-serializable values */
           return String(a);
         }
       })

package/src/src/observability/metrics/config.ts

@@ -75,8 +75,8 @@ export function loadConfig(
       metricsEndpoint: metricsConfig.metricsEndpoint,
       exporter: metricsConfig.exporter,
     });
-  } catch {
-    // getEnv access may fail, silently continue
+  } catch (_) {
+    /* expected: getEnv access may fail in some runtimes */
   }
 
   return finalConfig;
@@ -89,7 +89,8 @@ export function getMemoryUsage(): {
 } | null {
   try {
     return platformMemoryUsage();
-  } catch {
+  } catch (_) {
+    /* expected: memory usage API may be unavailable on some platforms */
     return null;
   }
 }

package/src/src/observability/simple-metrics/metrics-recorder.ts

@@ -11,11 +11,14 @@ import type { RSCRequestKind } from "./types.js";
 function recordObservability(
   fn: (obs: Awaited<ReturnType<typeof getObservabilityMetrics>>) => void,
 ): void {
-  void getObservabilityMetrics()
-    .then(fn)
-    .catch(() => {
+  void (async () => {
+    try {
+      const obs = await getObservabilityMetrics();
+      fn(obs);
+    } catch {
       /* metrics recording failure - non-critical */
-    });
+    }
+  })();
 }
 
 /**

package/src/src/observability/simple-metrics/otel-instruments.ts

@@ -14,8 +14,8 @@ const otel: OtelInstruments = {};
 export function safeLogWarn(message: string, error?: unknown): void {
   try {
     logger.warn(message, error);
-  } catch {
-    // Logger unavailable
+  } catch (_) {
+    /* expected: logger may be unavailable during bootstrap */
   }
 }
 

package/src/src/observability/tracing/config.ts

@@ -60,8 +60,8 @@ function applyEnvFromDeno(config: TracingConfig): void {
 
     const exporterType = tracingConfig.exporter;
     if (isValidExporter(exporterType)) config.exporter = exporterType;
-  } catch {
-    // Environment access may fail in some runtimes
+  } catch (_) {
+    /* expected: environment access may fail in some runtimes */
   }
 }
 

package/src/src/platform/adapters/detect.ts

@@ -4,9 +4,6 @@ import { createError, toError } from "../../errors/veryfront-error.js";
 import { detectRuntime } from "./runtime-detection.js";
 import type { RuntimeAdapter } from "./base.js";
 
-// Re-export from standalone module to avoid circular dependency
-export { detectRuntime } from "./runtime-detection.js";
-
 // Re-export the registry for convenient access
 export { runtime } from "./registry.js";
 

package/src/src/platform/adapters/fs/factory.ts

@@ -5,18 +5,12 @@ import {
   clearSSRModuleCache,
   clearSSRModuleCacheForProject,
 } from "../../../modules/react-loader/ssr-module-loader/cache/index.js";
-import {
-  clearRouterDetectionCache,
-  clearRouterDetectionCacheForProject,
-} from "../../../rendering/router-detection.js";
+import { clearRouterDetectionCacheForProject } from "../../../rendering/router-detection.js";
 import {
   clearModulePathCache,
   invalidateModulePaths,
 } from "../../../transforms/mdx/esm-module-loader/cache/index.js";
-import {
-  clearSnippetCache,
-  clearSnippetCacheForProject,
-} from "../../../rendering/snippet-renderer.js";
+import { clearSnippetCacheForProject } from "../../../rendering/snippet-renderer.js";
 import { clearRendererCacheForProject } from "../../../rendering/renderer.js";
 import { invalidateProjectCSS } from "../../../html/styles-builder/tailwind-compiler.js";
 import { invalidateProjectCandidateManifests } from "../../../rendering/orchestrator/css-candidate-manifest.js";
@@ -44,10 +38,8 @@ export function createFSAdapter(config: FSAdapterConfig): Promise<FSAdapter> {
           ...config,
           invalidationCallbacks: {
             clearSSRModuleCache,
-            clearRouterDetectionCache,
             clearModulePathCache,
             invalidateModulePaths,
-            clearSnippetCache,
             clearSSRModuleCacheForProject,
             clearRouterDetectionCacheForProject,
             clearSnippetCacheForProject,

package/src/src/platform/adapters/fs/github/adapter.ts

@@ -1,4 +1,5 @@
 import { logger } from "../../../../utils/index.js";
+import { CONFIG_INVALID } from "../../../../errors/index.js";
 import { getEnv } from "../../../compat/process.js";
 import { FileCache } from "../cache/file-cache.js";
 import type { FSAdapter, FSAdapterConfig } from "../veryfront/types.js";
@@ -30,7 +31,7 @@ export class GitHubFSAdapter implements FSAdapter {
   constructor(adapterConfig: FSAdapterConfig) {
     const githubConfig = adapterConfig.github;
     if (!githubConfig) {
-      throw new Error("GitHub adapter requires github configuration");
+      throw CONFIG_INVALID.create({ detail: "GitHub adapter requires github configuration" });
     }
 
     this.projectDir = adapterConfig.projectDir ?? "";

package/src/src/platform/adapters/fs/github/github-api-client.ts

@@ -13,6 +13,9 @@ import {
 
 const LOG_PREFIX = "[GitHubApiClient]";
 
+const RATE_LIMIT_WARNING_THRESHOLD = 100;
+const RETRY_JITTER_MAX_MS = 1_000;
+
 interface RateLimitInfo {
   limit: number;
   remaining: number;
@@ -139,7 +142,7 @@ export class GitHubApiClient {
       used: used ? parseInt(used, 10) : 0,
     };
 
-    if (this.rateLimitInfo.remaining < 100) {
+    if (this.rateLimitInfo.remaining < RATE_LIMIT_WARNING_THRESHOLD) {
       logger.warn(`${LOG_PREFIX} Approaching rate limit`, {
         remaining: this.rateLimitInfo.remaining,
         reset: this.rateLimitInfo.reset.toISOString(),
@@ -217,9 +220,10 @@ export class GitHubApiClient {
       this.config.retry.maxDelay,
     );
 
-    return delay + Math.random() * 1000;
+    return delay + Math.random() * RETRY_JITTER_MAX_MS;
   }
 
+  // no cleanup needed: one-shot
   private sleep(ms: number): Promise<void> {
     return new Promise((resolve) => dntShim.setTimeout(resolve, ms));
   }

package/src/src/platform/adapters/fs/github/stat-operations.ts

@@ -170,7 +170,8 @@ export class GitHubStatOperations {
     try {
       await this.stat(path);
       return true;
-    } catch {
+    } catch (_) {
+      /* expected: stat throws when file does not exist */
       return false;
     }
   }

package/src/src/platform/adapters/fs/github/types.ts

@@ -61,6 +61,13 @@ export interface FileIndexEntry {
   type: "blob" | "tree";
 }
 
+const DEFAULT_CACHE_TTL_MS = 60_000;
+const DEFAULT_CACHE_MAX_ENTRIES = 1_000;
+const DEFAULT_CACHE_MAX_MEMORY_BYTES = 100 * 1024 * 1024;
+const DEFAULT_MAX_RETRIES = 3;
+const DEFAULT_INITIAL_RETRY_DELAY_MS = 1_000;
+const DEFAULT_MAX_RETRY_DELAY_MS = 10_000;
+
 export function createGitHubConfig(config: GitHubConfig): ResolvedGitHubConfig {
   if (!config.token) {
     throw toError(
@@ -89,14 +96,14 @@ export function createGitHubConfig(config: GitHubConfig): ResolvedGitHubConfig {
     ref: config.ref ?? "main",
     cache: {
       enabled: config.cache?.enabled ?? true,
-      ttl: config.cache?.ttl ?? 60_000,
-      maxSize: config.cache?.maxSize ?? 1000,
-      maxMemory: config.cache?.maxMemory ?? 100 * 1024 * 1024,
+      ttl: config.cache?.ttl ?? DEFAULT_CACHE_TTL_MS,
+      maxSize: config.cache?.maxSize ?? DEFAULT_CACHE_MAX_ENTRIES,
+      maxMemory: config.cache?.maxMemory ?? DEFAULT_CACHE_MAX_MEMORY_BYTES,
     },
     retry: {
-      maxRetries: config.retry?.maxRetries ?? 3,
-      initialDelay: config.retry?.initialDelay ?? 1000,
-      maxDelay: config.retry?.maxDelay ?? 10_000,
+      maxRetries: config.retry?.maxRetries ?? DEFAULT_MAX_RETRIES,
+      initialDelay: config.retry?.initialDelay ?? DEFAULT_INITIAL_RETRY_DELAY_MS,
+      maxDelay: config.retry?.maxDelay ?? DEFAULT_MAX_RETRY_DELAY_MS,
     },
   };
 }

package/src/src/platform/adapters/fs/veryfront/adapter-content-context.ts

@@ -1,3 +1,4 @@
+import { API_CLIENT_ERROR, INVALID_ARGUMENT } from "../../../../errors/index.js";
 import type { VeryfrontApiClient } from "../../veryfront-api-client/index.js";
 import type { ContentSource, ResolvedContentContext } from "./types.js";
 
@@ -107,7 +108,9 @@ export async function resolveContentContext(
     case "domain": {
       const lookup = await client.lookupProjectByDomain(contentSource.domain);
       if (!lookup) {
-        throw new Error(`Domain lookup failed for: ${contentSource.domain}`);
+        throw API_CLIENT_ERROR.create({
+          detail: `Domain lookup failed for: ${contentSource.domain}`,
+        });
       }
       return {
         sourceType: "environment",
@@ -119,9 +122,9 @@ export async function resolveContentContext(
 
     case "release":
       if (!contentSource.releaseId) {
-        throw new Error(
-          `Missing releaseId for release sourceType (project: ${projectSlug})`,
-        );
+        throw INVALID_ARGUMENT.create({
+          detail: `Missing releaseId for release sourceType (project: ${projectSlug})`,
+        });
       }
       return {
         sourceType: "release",

package/src/src/platform/adapters/fs/veryfront/adapter.ts

@@ -31,6 +31,13 @@ import {
 
 const logger = baseLogger.component("veryfront-fs-adapter");
 
+const DEFAULT_MAX_RETRIES = 3;
+const DEFAULT_INITIAL_RETRY_DELAY_MS = 1_000;
+const DEFAULT_MAX_RETRY_DELAY_MS = 10_000;
+const DEFAULT_CACHE_TTL_MS = 60_000;
+const DEFAULT_CACHE_MAX_ENTRIES = 1_000;
+const DEFAULT_CACHE_MAX_MEMORY_BYTES = 100 * 1024 * 1024;
+
 export class VeryfrontFSAdapter implements FSAdapter {
   private client: VeryfrontApiClient;
   private cache: FileCache;
@@ -79,9 +86,9 @@ export class VeryfrontFSAdapter implements FSAdapter {
     this.proxyMode = vf.proxyMode ?? false;
 
     const retryConfig = {
-      maxRetries: 3,
-      initialDelay: 1000,
-      maxDelay: 10000,
+      maxRetries: DEFAULT_MAX_RETRIES,
+      initialDelay: DEFAULT_INITIAL_RETRY_DELAY_MS,
+      maxDelay: DEFAULT_MAX_RETRY_DELAY_MS,
       ...vf.retry,
     };
 
@@ -96,9 +103,9 @@ export class VeryfrontFSAdapter implements FSAdapter {
 
     const cacheConfig: FileCacheOptions = {
       enabled: true,
-      ttl: 60_000,
-      maxSize: 1000,
-      maxMemory: 100 * 1024 * 1024,
+      ttl: DEFAULT_CACHE_TTL_MS,
+      maxSize: DEFAULT_CACHE_MAX_ENTRIES,
+      maxMemory: DEFAULT_CACHE_MAX_MEMORY_BYTES,
       ...vf.cache,
     };
 

package/src/src/platform/adapters/fs/veryfront/api-search-circuit-breaker.ts

@@ -1,4 +1,4 @@
-export interface ApiSearchCircuitBreakerOptions {
+interface ApiSearchCircuitBreakerOptions {
   threshold: number;
   cooldownMs: number;
 }

package/src/src/platform/adapters/fs/veryfront/content-metrics.ts

@@ -115,7 +115,7 @@ export function endRequestMetrics(
   });
 }
 
-export type ContentMetricEvent =
+type ContentMetricEvent =
   | "REQUEST_SCOPED_HIT"
   | "PERSISTENT_CACHE_HIT"
   | "FILE_LIST_HIT"

package/src/src/platform/adapters/fs/veryfront/file-list-index.ts

@@ -48,7 +48,8 @@ export class FileListIndex {
     if (this.readyPromise) {
       try {
         await this.readyPromise;
-      } catch {
+      } catch (_) {
+        /* expected: file list initialization may fail, will fetch individually */
         logger.debug("File list initialization failed, will fetch individually");
       }
     }

package/src/src/platform/adapters/fs/veryfront/in-flight-dedupe.ts

@@ -1,15 +1,15 @@
-export interface InFlightEntry<T> {
+interface InFlightEntry<T> {
   promise: Promise<T>;
   startedAt: number;
 }
 
-export interface InFlightDeduperOptions {
+interface InFlightDeduperOptions {
   timeoutMs: number;
   maxEntries: number;
   cleanupIntervalMs: number;
 }
 
-export interface InFlightCleanupResult {
+interface InFlightCleanupResult {
   cleanedCount: number;
   remainingCount: number;
 }

package/src/src/platform/adapters/fs/veryfront/multi-project-adapter.ts

@@ -1,5 +1,6 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { logger as baseLogger } from "../../../../utils/index.js";
+import { INITIALIZATION_ERROR } from "../../../../errors/index.js";
 import type { DirectoryEntry, FSAdapter, FSAdapterConfig } from "./types.js";
 import type { FileInfo } from "../../base.js";
 import { ProxyFSAdapterManager } from "./proxy-manager.js";
@@ -8,6 +9,10 @@ import { runWithCacheBatching } from "../../../../cache/request-cache-batcher.js
 
 const logger = baseLogger.component("multi-project-fs-adapter");
 
+const DEFAULT_MAX_ADAPTERS = 100;
+const DEFAULT_CLEANUP_INTERVAL_MS = 5 * 60 * 1_000;
+const DEFAULT_MAX_IDLE_MS = 30 * 60 * 1_000;
+
 interface RequestContext {
   projectSlug: string;
   projectId?: string;
@@ -36,9 +41,9 @@ export class MultiProjectFSAdapter implements FSAdapter {
   constructor(config: FSAdapterConfig) {
     this.manager = new ProxyFSAdapterManager({
       baseConfig: config,
-      maxAdapters: 100,
-      cleanupIntervalMs: 5 * 60 * 1000,
-      maxIdleMs: 30 * 60 * 1000,
+      maxAdapters: DEFAULT_MAX_ADAPTERS,
+      cleanupIntervalMs: DEFAULT_CLEANUP_INTERVAL_MS,
+      maxIdleMs: DEFAULT_MAX_IDLE_MS,
     });
 
     logger.debug("Created", {
@@ -126,10 +131,10 @@ export class MultiProjectFSAdapter implements FSAdapter {
 
       if (this.defaultAdapter) return this.defaultAdapter;
 
-      throw new Error(
-        "[MultiProjectFSAdapter] No request context available. " +
+      throw INITIALIZATION_ERROR.create({
+        detail: "[MultiProjectFSAdapter] No request context available. " +
           "Use runWithContext() to set project context before accessing files.",
-      );
+      });
     }
 
     const productionMode = context.productionMode ?? false;
@@ -228,7 +233,8 @@ export class MultiProjectFSAdapter implements FSAdapter {
     try {
       const adapter = await this.getAdapter();
       return adapter.getProjectData?.();
-    } catch {
+    } catch (error) {
+      logger.debug("getProjectData failed", { error });
       return undefined;
     }
   }
@@ -237,7 +243,8 @@ export class MultiProjectFSAdapter implements FSAdapter {
     try {
       const adapter = await this.getAdapter();
       return adapter.getFilePathByEntityId?.(entityId);
-    } catch {
+    } catch (error) {
+      logger.debug("getFilePathByEntityId failed", { entityId, error });
       return undefined;
     }
   }
@@ -332,7 +339,7 @@ export type { RequestContext };
  * Registered on globalThis to avoid circular dependencies between
  * cache-key-builder / cache backends and the FS adapter layer.
  */
-export interface VfMultiProjectAdapterGlobal {
+interface VfMultiProjectAdapterGlobal {
   getCurrentRequestContext: () => RequestContext | null;
   getRequestScopedFile: (cacheKey: string) => string | undefined;
   setRequestScopedFile: (cacheKey: string, content: string) => void;