@littlebearapps/platform-admin-sdk 1.4.2 → 2.0.0

package/templates/full/workers/platform-auditor.ts

@@ -0,0 +1,1071 @@
+/**
+ * Platform Auditor Worker
+ *
+ * SDK integration auditor using 4-layer triangulation:
+ *   1. Config checks — Verify PLATFORM_CACHE KV and PLATFORM_TELEMETRY queue bindings
+ *   2. Code smell tests — String matching for SDK patterns in source files
+ *   3. Runtime checks — Cross-reference D1 system_health_checks heartbeats
+ *   4. AI Judge — Gemini via AI Gateway deep code analysis (rubric-based scoring)
+ *
+ * Audit targets are loaded from KV (CONFIG:AUDIT_TARGETS) — configure in config/audit-targets.yaml
+ * and sync via `npm run sync:config`.
+ *
+ * Schedule:
+ *   Sunday Midnight UTC — Full deep scan (all dimensions, all projects)
+ *   Wednesday Midnight UTC — Focused scan (weak dimensions, projects < threshold)
+ *
+ * @module workers/platform-auditor
+ */
+
+import type {
+  KVNamespace,
+  ExecutionContext,
+  ScheduledEvent,
+  D1Database,
+  Fetcher,
+} from '@cloudflare/workers-types';
+import {
+  withFeatureBudget,
+  withCronBudget,
+  CircuitBreakerError,
+  completeTracking,
+  createLogger,
+  createLoggerFromRequest,
+  createTraceContext,
+  health,
+  pingHeartbeat,
+  type Logger,
+} from '@littlebearapps/platform-consumer-sdk';
+import {
+  validateAIJudgeResponse,
+  calculateCompositeScore,
+  formatValidationErrors,
+  DEFAULT_RUBRIC_WEIGHTS,
+  type RubricScores,
+  type CategorisedIssue,
+} from './lib/ai-judge-schema';
+import {
+  runFeatureCoverageAudit,
+  storeFeatureCoverageAudit,
+  type FeatureCoverageReport,
+} from './lib/auditor/feature-coverage';
+import {
+  generateComprehensiveReport,
+  storeComprehensiveReport,
+} from './lib/auditor/comprehensive-report';
+import type {
+  AuditorEnv,
+  AuditTarget,
+  AuditTargetsConfig,
+  AuditDimension,
+  AuditStatus,
+  ScanType,
+  ConfigCheckResult,
+  CodeSmellResult,
+  RuntimeCheckResult,
+  AIJudgeResult,
+  BehavioralResult,
+  ProjectAuditResult,
+} from './lib/auditor/types';
+
+// =============================================================================
+// Feature IDs (register these in budgets.yaml)
+// =============================================================================
+
+const FEATURE_AUDITOR = 'platform:monitor:auditor';
+const FEATURE_HEARTBEAT = 'platform:heartbeat:auditor';
+
+// =============================================================================
+// Constants (defaults — overridden by audit-targets.yaml config)
+// =============================================================================
+
+const DEFAULT_HEARTBEAT_FRESHNESS_HOURS = 24;
+const DEFAULT_AI_CACHE_TTL_SECONDS = 3 * 24 * 60 * 60; // 3 days
+const DEFAULT_FOCUSED_SCAN_THRESHOLD = 90;
+const DEEP_SCAN_FILE_LIMIT = 50000; // Max chars per file
+const SUPPLEMENTARY_CONTENT_WARN_LIMIT = 3_000_000; // ~750K tokens safety
+const DEFAULT_BEHAVIORAL_ANALYSIS_DAYS = 30;
+const DEFAULT_HOTSPOT_MIN_COMMITS = 3;
+const AI_MAX_RETRIES = 2;
+
+const GITHUB_API_BASE = 'https://api.github.com';
+const AI_GATEWAY_URL = 'https://gateway.ai.cloudflare.com/v1';
+
+const DEFAULT_SDK_PATTERNS = [
+  'withFeatureBudget', 'withCronBudget', 'withQueueBudget',
+  'trackedEnv', 'platform-sdk', 'completeTracking',
+  'CircuitBreakerError', 'PLATFORM_CACHE', 'PLATFORM_TELEMETRY',
+];
+
+// =============================================================================
+// Wrangler Config Shape (for JSONC parsing)
+// =============================================================================
+
+interface WranglerConfig {
+  kv_namespaces?: Array<{ binding: string }>;
+  queues?: { producers?: Array<{ binding: string }> };
+  observability?: {
+    enabled?: boolean;
+    logs?: { enabled?: boolean; sampling_rate?: number; invocation_logs?: boolean };
+    traces?: { enabled?: boolean; head_sampling_rate?: number };
+  };
+  upload_source_maps?: boolean;
+}
+
+// =============================================================================
+// GitHub Types
+// =============================================================================
+
+interface GitHubCommit {
+  sha: string;
+  commit: { message: string; author: { name: string; date: string } };
+  files?: Array<{ filename: string; status: string; patch?: string }>;
+}
+
+// =============================================================================
+// CONFIG LOADING
+// =============================================================================
+
+/** Load audit targets config from KV */
+async function loadAuditConfig(
+  env: AuditorEnv,
+  log: Logger
+): Promise<AuditTargetsConfig> {
+  try {
+    const configJson = await env.PLATFORM_CACHE.get('CONFIG:AUDIT_TARGETS');
+    if (configJson) {
+      return JSON.parse(configJson) as AuditTargetsConfig;
+    }
+  } catch (error) {
+    log.warn('Failed to load audit targets from KV, using defaults', error);
+  }
+
+  return {
+    targets: {},
+    sdkPatterns: DEFAULT_SDK_PATTERNS,
+    rubricWeights: { ...DEFAULT_RUBRIC_WEIGHTS },
+    heartbeatFreshnessHours: DEFAULT_HEARTBEAT_FRESHNESS_HOURS,
+    focusedScanThreshold: DEFAULT_FOCUSED_SCAN_THRESHOLD,
+    aiCacheTtlSeconds: DEFAULT_AI_CACHE_TTL_SECONDS,
+    behavioralAnalysisDays: DEFAULT_BEHAVIORAL_ANALYSIS_DAYS,
+    hotspotMinCommits: DEFAULT_HOTSPOT_MIN_COMMITS,
+  };
+}
+
+// =============================================================================
+// SCAN TYPE HELPERS
+// =============================================================================
+
+function determineScanType(scheduledTime: number): ScanType {
+  const day = new Date(scheduledTime).getUTCDay();
+  return day === 0 ? 'full' : 'focused';
+}
+
+async function getWeakDimensions(
+  project: string,
+  threshold: number,
+  env: AuditorEnv,
+  log: Logger
+): Promise<{ dimensions: AuditDimension[]; previousScore: number }> {
+  try {
+    const latest = await env.PLATFORM_DB.prepare(
+      `SELECT composite_score, rubric_sdk, rubric_observability, rubric_cost_protection, rubric_security
+       FROM audit_results
+       WHERE project = ? AND scan_type = 'full' AND ai_judge_score IS NOT NULL
+       ORDER BY created_at DESC LIMIT 1`
+    ).bind(project).first<{
+      composite_score: number;
+      rubric_sdk: number | null;
+      rubric_observability: number | null;
+      rubric_cost_protection: number | null;
+      rubric_security: number | null;
+    }>();
+
+    if (!latest) {
+      return { dimensions: ['sdk', 'observability', 'cost', 'security'], previousScore: 0 };
+    }
+
+    const weak: AuditDimension[] = [];
+    if ((latest.rubric_sdk ?? 0) < 4) weak.push('sdk');
+    if ((latest.rubric_observability ?? 0) < 4) weak.push('observability');
+    if ((latest.rubric_cost_protection ?? 0) < 4) weak.push('cost');
+    if ((latest.rubric_security ?? 0) < 4) weak.push('security');
+
+    if (weak.length === 0 && latest.composite_score < threshold) {
+      return { dimensions: ['sdk', 'observability', 'cost', 'security'], previousScore: latest.composite_score };
+    }
+
+    return { dimensions: weak, previousScore: latest.composite_score };
+  } catch (error) {
+    log.warn('Failed to get weak dimensions, defaulting to full scan', error, { project });
+    return { dimensions: ['sdk', 'observability', 'cost', 'security'], previousScore: 0 };
+  }
+}
+
+// =============================================================================
+// CHECK FUNCTIONS
+// =============================================================================
+
+/** Layer 1: Config checks (wrangler bindings) */
+function checkConfig(config: WranglerConfig | null): ConfigCheckResult {
+  if (!config) {
+    return {
+      hasPlatformCache: false, hasPlatformTelemetry: false,
+      observabilityEnabled: false, logsEnabled: false,
+      tracesEnabled: false, traceSamplingRate: null,
+      logSamplingRate: null, invocationLogsEnabled: false,
+      sourceMapsEnabled: false, issues: ['Wrangler config not found or invalid'],
+    };
+  }
+
+  const kvBindings = (config.kv_namespaces ?? []).map((kv) => kv.binding);
+  const queueBindings = (config.queues?.producers ?? []).map((q) => q.binding);
+  const obs = config.observability;
+  const issues: string[] = [];
+
+  const hasPlatformCache = kvBindings.includes('PLATFORM_CACHE');
+  const hasPlatformTelemetry = queueBindings.includes('PLATFORM_TELEMETRY');
+  const observabilityEnabled = obs?.enabled ?? false;
+  const logsEnabled = obs?.logs?.enabled ?? false;
+  const tracesEnabled = obs?.traces?.enabled ?? false;
+
+  if (!hasPlatformCache) issues.push('Missing PLATFORM_CACHE KV binding');
+  if (!hasPlatformTelemetry) issues.push('Missing PLATFORM_TELEMETRY queue binding');
+  if (!observabilityEnabled) issues.push('Observability not enabled');
+
+  return {
+    hasPlatformCache, hasPlatformTelemetry,
+    observabilityEnabled, logsEnabled,
+    tracesEnabled,
+    traceSamplingRate: obs?.traces?.head_sampling_rate ?? null,
+    logSamplingRate: obs?.logs?.sampling_rate ?? null,
+    invocationLogsEnabled: obs?.logs?.invocation_logs ?? false,
+    sourceMapsEnabled: config.upload_source_maps ?? false,
+    issues,
+  };
+}
+
+/** Layer 2: Code smell checks (SDK pattern detection) */
+function checkCodeSmells(
+  content: string | null,
+  patterns: string[] = DEFAULT_SDK_PATTERNS
+): CodeSmellResult {
+  if (!content) {
+    return {
+      hasSdkFolder: false, hasWithFeatureBudget: false,
+      hasTrackedEnv: false, hasCircuitBreakerError: false,
+      hasErrorLogging: false, patternCounts: {},
+    };
+  }
+
+  const patternCounts: Record<string, number> = {};
+  for (const pattern of patterns) {
+    const matches = content.match(new RegExp(pattern, 'g'));
+    patternCounts[pattern] = matches?.length ?? 0;
+  }
+
+  return {
+    hasSdkFolder: content.includes('platform-sdk') || content.includes('@littlebearapps/platform'),
+    hasWithFeatureBudget: (patternCounts['withFeatureBudget'] ?? 0) > 0,
+    hasTrackedEnv: (patternCounts['trackedEnv'] ?? 0) > 0,
+    hasCircuitBreakerError: (patternCounts['CircuitBreakerError'] ?? 0) > 0,
+    hasErrorLogging: content.includes('log.error') || content.includes('console.error'),
+    patternCounts,
+  };
+}
+
+/** Layer 3: Runtime checks (heartbeat freshness) */
+async function checkRuntime(
+  project: string,
+  freshnessHours: number,
+  env: AuditorEnv,
+  log: Logger
+): Promise<RuntimeCheckResult> {
+  try {
+    const result = await env.PLATFORM_DB.prepare(
+      `SELECT MAX(last_heartbeat) as latest
+       FROM system_health_checks
+       WHERE project_id = ?`
+    ).bind(project).first<{ latest: number | null }>();
+
+    if (!result?.latest) {
+      return { hasRecentHeartbeat: false, hoursSinceHeartbeat: null, lastHeartbeatTime: null };
+    }
+
+    const hoursSince = (Date.now() / 1000 - result.latest) / 3600;
+    return {
+      hasRecentHeartbeat: hoursSince < freshnessHours,
+      hoursSinceHeartbeat: Math.round(hoursSince),
+      lastHeartbeatTime: new Date(result.latest * 1000).toISOString(),
+    };
+  } catch (error) {
+    log.error('Runtime check failed', error, { project });
+    return { hasRecentHeartbeat: false, hoursSinceHeartbeat: null, lastHeartbeatTime: null };
+  }
+}
+
+// =============================================================================
+// AI JUDGE
+// =============================================================================
+
+/** Layer 4: AI Judge analysis via Gemini AI Gateway */
+async function auditWithGemini(
+  project: string,
+  entryPointContent: string,
+  wranglerContent: string | null,
+  staticChecks: Record<string, boolean>,
+  supplementaryContent: string,
+  config: AuditTargetsConfig,
+  env: AuditorEnv,
+  log: Logger
+): Promise<AIJudgeResult | null> {
+  // Check content hash cache
+  const contentHash = await hashContent(`${project}:${entryPointContent}:${supplementaryContent}`);
+  const cacheKey = `AUDIT:AI:${contentHash}`;
+
+  const cached = await env.PLATFORM_CACHE.get(cacheKey);
+  if (cached) {
+    log.debug('AI Judge cache hit', { project, cacheKey });
+    try {
+      return JSON.parse(cached) as AIJudgeResult;
+    } catch { /* cache corrupt, proceed with fresh analysis */ }
+  }
+
+  const prompt = buildAIPrompt(project, entryPointContent, wranglerContent, staticChecks, supplementaryContent);
+  const weights = config.rubricWeights ?? DEFAULT_RUBRIC_WEIGHTS;
+
+  for (let attempt = 0; attempt <= AI_MAX_RETRIES; attempt++) {
+    try {
+      const response = await callGemini(prompt, env, log);
+      if (!response) return null;
+
+      const parsed = JSON.parse(response);
+      const validation = validateAIJudgeResponse(parsed);
+
+      if (validation.success) {
+        const data = validation.data;
+        const rubricScores = data.rubricScores;
+        const compositeScore = calculateCompositeScore(rubricScores, weights);
+
+        const result: AIJudgeResult = {
+          score: compositeScore,
+          summary: data.summary,
+          issues: JSON.stringify(data.issues),
+          categorisedIssues: JSON.stringify(data.issues),
+          reasoning: data.reasoning,
+          rubricScores: {
+            sdk: rubricScores.sdk.score,
+            observability: rubricScores.observability.score,
+            costProtection: rubricScores.costProtection.score,
+            security: rubricScores.security.score,
+          },
+          rubricEvidence: JSON.stringify({
+            sdk: rubricScores.sdk.evidence,
+            observability: rubricScores.observability.evidence,
+            costProtection: rubricScores.costProtection.evidence,
+            security: rubricScores.security.evidence,
+          }),
+          validationRetries: attempt,
+          cachedAt: new Date().toISOString(),
+        };
+
+        // Cache result
+        await env.PLATFORM_CACHE.put(cacheKey, JSON.stringify(result), {
+          expirationTtl: config.aiCacheTtlSeconds ?? DEFAULT_AI_CACHE_TTL_SECONDS,
+        });
+
+        log.info('AI Judge complete', { project, score: compositeScore, attempt });
+        return result;
+      }
+
+      // Validation failed — retry with error feedback
+      log.warn('AI Judge validation failed', { project, attempt, errors: validation.errors });
+      if (attempt < AI_MAX_RETRIES) {
+        prompt.concat('\n\n' + formatValidationErrors(validation.errors));
+      }
+    } catch (error) {
+      log.error('AI Judge attempt failed', error, { project, attempt });
+    }
+  }
+
+  return null;
+}
+
+/** Build AI Judge prompt */
+function buildAIPrompt(
+  project: string,
+  entryPoint: string,
+  wrangler: string | null,
+  staticChecks: Record<string, boolean>,
+  supplementary: string
+): string {
+  return `You are an expert Cloudflare Workers SDK integration auditor.
+
+Analyse the following project "${project}" and score it on 4 dimensions (1-5 scale):
+- sdk: SDK integration patterns (withFeatureBudget, completeTracking, circuit breakers)
+- observability: Logging, tracing, metrics, error reporting
+- costProtection: Circuit breakers, budgets, DLQ handling, rate limiting
+- security: Authentication, input validation, secrets handling, CORS
+
+## Entry Point:
+\`\`\`typescript
+${entryPoint.slice(0, DEEP_SCAN_FILE_LIMIT)}
+\`\`\`
+
+${wrangler ? `## Wrangler Config:\n\`\`\`jsonc\n${wrangler.slice(0, 5000)}\n\`\`\`` : ''}
+
+## Static Check Results:
+${JSON.stringify(staticChecks, null, 2)}
+
+${supplementary ? `## Additional Source Files:\n${supplementary}` : ''}
+
+Respond with ONLY valid JSON matching this schema:
+{
+  "reasoning": "Chain-of-thought analysis...",
+  "rubricScores": {
+    "sdk": { "score": 1-5, "evidence": ["..."] },
+    "observability": { "score": 1-5, "evidence": ["..."] },
+    "costProtection": { "score": 1-5, "evidence": ["..."] },
+    "security": { "score": 1-5, "evidence": ["..."] }
+  },
+  "issues": [{ "category": "sdk|observability|cost|security", "severity": "critical|high|medium|low", "description": "...", "file": "...", "line": 123 }],
+  "summary": "Brief summary..."
+}`;
+}
+
+/** Call Gemini via AI Gateway */
+async function callGemini(
+  prompt: string,
+  env: AuditorEnv,
+  log: Logger
+): Promise<string | null> {
+  const gatewayUrl = `${AI_GATEWAY_URL}/${env.CLOUDFLARE_ACCOUNT_ID}/platform/google-ai-studio/v1beta/models/gemini-2.0-flash-lite:generateContent`;
+
+  try {
+    const response = await fetch(gatewayUrl, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'cf-aig-authorization': `Bearer ${env.PLATFORM_AI_GATEWAY_KEY}`,
+        'x-goog-api-key': env.GEMINI_API_KEY,
+      },
+      body: JSON.stringify({
+        contents: [{ parts: [{ text: prompt }] }],
+        generationConfig: {
+          temperature: 0.1,
+          maxOutputTokens: 4096,
+          responseMimeType: 'application/json',
+        },
+      }),
+    });
+
+    if (!response.ok) {
+      const errorBody = await response.text();
+      log.error('Gemini API error', new Error(`HTTP ${response.status}`), {
+        status: response.status,
+        errorBody: errorBody.substring(0, 500),
+      });
+      return null;
+    }
+
+    const data = await response.json() as {
+      candidates?: Array<{ content?: { parts?: Array<{ text?: string }> } }>;
+    };
+
+    return data.candidates?.[0]?.content?.parts?.[0]?.text ?? null;
+  } catch (error) {
+    log.error('Gemini fetch failed', error);
+    return null;
+  }
+}
+
+// =============================================================================
+// STATUS DETERMINATION
+// =============================================================================
+
+function determineStatus(
+  config: ConfigCheckResult,
+  code: CodeSmellResult,
+  runtime: RuntimeCheckResult
+): AuditStatus {
+  const hasConfig = config.hasPlatformCache && config.hasPlatformTelemetry;
+  const hasCode = code.hasWithFeatureBudget || code.hasTrackedEnv;
+  const hasRuntime = runtime.hasRecentHeartbeat;
+
+  if (hasConfig && hasCode && hasRuntime) return 'HEALTHY';
+  if (hasConfig && hasCode && !hasRuntime) return 'ZOMBIE';
+  if (hasConfig && !hasCode) return 'BROKEN';
+  if (!hasConfig && hasCode) return 'BROKEN';
+  if (!hasConfig && !hasCode && hasRuntime) return 'UNTRACKED';
+  return 'NOT_INTEGRATED';
+}
+
+function generateStatusMessage(
+  status: AuditStatus,
+  config: ConfigCheckResult,
+  code: CodeSmellResult,
+  runtime: RuntimeCheckResult
+): string {
+  switch (status) {
+    case 'HEALTHY': return 'SDK fully integrated and active';
+    case 'ZOMBIE': return `SDK integrated but no heartbeat in ${runtime.hoursSinceHeartbeat ?? '?'}h`;
+    case 'BROKEN': return `SDK misconfigured: ${config.issues.join(', ')}`;
+    case 'UNTRACKED': return 'Runtime activity detected but no SDK integration';
+    case 'NOT_INTEGRATED': return 'No SDK integration detected';
+  }
+}
+
+// =============================================================================
+// BEHAVIORAL ANALYSIS
+// =============================================================================
+
+async function runBehavioralAnalysis(
+  project: string,
+  repo: string,
+  sdkPatterns: string[],
+  config: AuditTargetsConfig,
+  env: AuditorEnv,
+  log: Logger
+): Promise<BehavioralResult> {
+  const days = config.behavioralAnalysisDays ?? DEFAULT_BEHAVIORAL_ANALYSIS_DAYS;
+  const minCommits = config.hotspotMinCommits ?? DEFAULT_HOTSPOT_MIN_COMMITS;
+
+  const commits = await fetchCommitHistory(repo, env.GITHUB_TOKEN, days, log);
+  if (commits.length === 0) {
+    return { hotspots: [], regressions: [], analysisWindow: days };
+  }
+
+  // Fetch details for recent commits (limit to 20 for performance)
+  const recentCommits = commits.slice(0, 20);
+  const commitDetails = new Map<string, GitHubCommit>();
+  for (const commit of recentCommits) {
+    const details = await fetchCommitDetails(repo, commit.sha, env.GITHUB_TOKEN, log);
+    if (details) commitDetails.set(commit.sha, details);
+  }
+
+  // Analyze hotspots
+  const fileChanges = new Map<string, { count: number; hasSdkPatterns: boolean }>();
+  for (const commit of commits) {
+    const details = commitDetails.get(commit.sha);
+    if (!details?.files) continue;
+    for (const file of details.files) {
+      if (!file.filename.match(/\.(ts|tsx|js|jsx)$/)) continue;
+      const existing = fileChanges.get(file.filename);
+      if (existing) { existing.count++; }
+      else {
+        const hasSdk = file.filename.includes('platform-sdk') || file.filename.includes('circuit-breaker');
+        fileChanges.set(file.filename, { count: 1, hasSdkPatterns: hasSdk });
+      }
+    }
+  }
+
+  const hotspots = [...fileChanges.entries()]
+    .filter(([, data]) => data.count >= minCommits)
+    .map(([filePath, data]) => ({
+      filePath,
+      changeCount: data.count,
+      hasSdkPatterns: data.hasSdkPatterns,
+      hotspotScore: data.count * (data.hasSdkPatterns ? 1 : 3),
+    }))
+    .sort((a, b) => b.hotspotScore - a.hotspotScore)
+    .slice(0, 10);
+
+  // Detect regressions
+  const regressions: BehavioralResult['regressions'] = [];
+  for (const commit of commits) {
+    const details = commitDetails.get(commit.sha);
+    if (!details?.files) continue;
+
+    const allAdded: string[] = [];
+    for (const f of details.files) {
+      if (!f.patch) continue;
+      for (const line of f.patch.split('\n')) {
+        if (line.startsWith('+') && !line.startsWith('+++')) allAdded.push(line);
+      }
+    }
+
+    for (const file of details.files) {
+      if (!file.patch || file.status === 'removed') continue;
+      const removed = file.patch.split('\n').filter((l) => l.startsWith('-') && !l.startsWith('---'));
+      const added = file.patch.split('\n').filter((l) => l.startsWith('+') && !l.startsWith('+++'));
+
+      for (const pattern of sdkPatterns) {
+        const removedCount = removed.filter((l) => l.includes(pattern)).length;
+        const addedCount = added.filter((l) => l.includes(pattern)).length;
+        if (removedCount > addedCount) {
+          const addedElsewhere = allAdded.some((l) => l.includes(pattern));
+          if (!addedElsewhere) {
+            regressions.push({
+              commitSha: commit.sha,
+              commitMessage: commit.commit.message.split('\n')[0].substring(0, 100),
+              removedPattern: pattern,
+              filePath: file.filename,
+            });
+          }
+        }
+      }
+    }
+  }
+
+  log.info('Behavioral analysis complete', {
+    project, commitsAnalyzed: commits.length,
+    hotspotsFound: hotspots.length, regressionsFound: regressions.length,
+  });
+
+  return { hotspots, regressions, analysisWindow: days };
+}
+
+// =============================================================================
+// GITHUB HELPERS
+// =============================================================================
+
+async function fetchGitHubFile(
+  repo: string, path: string, token: string, log: Logger
+): Promise<string | null> {
+  try {
+    const response = await fetch(`${GITHUB_API_BASE}/repos/${repo}/contents/${path}`, {
+      headers: {
+        Authorization: `Bearer ${token}`,
+        Accept: 'application/vnd.github.v3.raw',
+        'User-Agent': 'platform-auditor/1.0',
+      },
+    });
+    if (!response.ok) {
+      if (response.status !== 404) {
+        const body = await response.text();
+        log.error('GitHub API error', new Error(`HTTP ${response.status}`), { repo, path, body: body.substring(0, 500) });
+      }
+      return null;
+    }
+    return await response.text();
+  } catch (error) {
+    log.error('GitHub fetch failed', error, { repo, path });
+    return null;
+  }
+}
+
+async function fetchDeepScanFiles(
+  target: AuditTarget, dimensions: AuditDimension[],
+  env: AuditorEnv, log: Logger
+): Promise<string> {
+  const files = new Set<string>();
+  for (const dim of dimensions) {
+    for (const f of target.deepScanFiles[dim] || []) files.add(f);
+  }
+
+  let content = '';
+  for (const filePath of files) {
+    const fileContent = await fetchGitHubFile(target.repo, filePath, env.GITHUB_TOKEN, log);
+    if (fileContent) {
+      content += `\n\n## ${filePath}:\n\`\`\`typescript\n${fileContent.slice(0, DEEP_SCAN_FILE_LIMIT)}\n\`\`\``;
+    }
+  }
+
+  if (content.length > SUPPLEMENTARY_CONTENT_WARN_LIMIT) {
+    log.warn('Deep scan content exceeds safety threshold', {
+      repo: target.repo, contentLength: content.length,
+      estimatedTokens: Math.round(content.length / 4),
+    });
+  }
+
+  return content;
+}
+
+async function fetchCommitHistory(
+  repo: string, token: string, days: number, log: Logger
+): Promise<GitHubCommit[]> {
+  const since = new Date();
+  since.setDate(since.getDate() - days);
+  try {
+    const response = await fetch(
+      `${GITHUB_API_BASE}/repos/${repo}/commits?since=${since.toISOString()}&per_page=100`,
+      { headers: { Authorization: `Bearer ${token}`, Accept: 'application/vnd.github.v3+json', 'User-Agent': 'platform-auditor/1.0' } }
+    );
+    if (!response.ok) { await response.text(); return []; }
+    return (await response.json()) as GitHubCommit[];
+  } catch { return []; }
+}
+
+async function fetchCommitDetails(
+  repo: string, sha: string, token: string, log: Logger
+): Promise<GitHubCommit | null> {
+  try {
+    const response = await fetch(`${GITHUB_API_BASE}/repos/${repo}/commits/${sha}`, {
+      headers: { Authorization: `Bearer ${token}`, Accept: 'application/vnd.github.v3+json', 'User-Agent': 'platform-auditor/1.0' },
+    });
+    if (!response.ok) { await response.text(); return null; }
+    return (await response.json()) as GitHubCommit;
+  } catch { return null; }
+}
+
+// =============================================================================
+// UTILITIES
+// =============================================================================
+
+function generateAuditId(): string {
+  return `audit-${new Date().toISOString().replace(/[:.]/g, '-')}`;
+}
+
+async function hashContent(content: string): Promise<string> {
+  const encoder = new TextEncoder();
+  const data = encoder.encode(content);
+  const hashBuffer = await crypto.subtle.digest('SHA-256', data);
+  const hashArray = Array.from(new Uint8Array(hashBuffer));
+  return hashArray.map((b) => b.toString(16).padStart(2, '0')).join('').slice(0, 16);
+}
+
+function parseJsonc(content: string): WranglerConfig | null {
+  try {
+    let result = '';
+    let i = 0;
+    while (i < content.length) {
+      if (content[i] === '"') {
+        result += content[i++];
+        while (i < content.length && content[i] !== '"') {
+          if (content[i] === '\\' && i + 1 < content.length) result += content[i++];
+          result += content[i++];
+        }
+        if (i < content.length) result += content[i++];
+      } else if (content[i] === '/' && content[i + 1] === '/') {
+        while (i < content.length && content[i] !== '\n') i++;
+      } else if (content[i] === '/' && content[i + 1] === '*') {
+        i += 2;
+        while (i < content.length - 1 && !(content[i] === '*' && content[i + 1] === '/')) i++;
+        i += 2;
+      } else {
+        result += content[i++];
+      }
+    }
+    return JSON.parse(result) as WranglerConfig;
+  } catch {
+    return null;
+  }
+}
+
+// =============================================================================
+// D1 STORAGE
+// =============================================================================
+
+async function storeAuditResult(
+  auditId: string,
+  result: ProjectAuditResult,
+  env: AuditorEnv,
+  log: Logger
+): Promise<void> {
+  try {
+    await env.PLATFORM_DB.prepare(
+      `INSERT INTO audit_results (
+        audit_id, project, status, status_message,
+        has_platform_cache, has_platform_telemetry, observability_enabled, logs_enabled, config_issues,
+        has_sdk_folder, has_with_feature_budget, has_tracked_env, has_circuit_breaker_error, has_error_logging,
+        has_recent_heartbeat, hours_since_heartbeat,
+        ai_judge_score, ai_judge_summary, ai_judge_issues, ai_cached_at,
+        traces_enabled, trace_sampling_rate, log_sampling_rate, invocation_logs_enabled, source_maps_enabled,
+        rubric_sdk, rubric_observability, rubric_cost_protection, rubric_security,
+        rubric_evidence, ai_reasoning, ai_categorised_issues, ai_validation_retries,
+        scan_type, focused_dimensions, composite_score
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+    ).bind(
+      auditId, result.project, result.status, result.statusMessage,
+      result.config.hasPlatformCache ? 1 : 0,
+      result.config.hasPlatformTelemetry ? 1 : 0,
+      result.config.observabilityEnabled ? 1 : 0,
+      result.config.logsEnabled ? 1 : 0,
+      JSON.stringify(result.config.issues),
+      result.codeSmells.hasSdkFolder ? 1 : 0,
+      result.codeSmells.hasWithFeatureBudget ? 1 : 0,
+      result.codeSmells.hasTrackedEnv ? 1 : 0,
+      result.codeSmells.hasCircuitBreakerError ? 1 : 0,
+      result.codeSmells.hasErrorLogging ? 1 : 0,
+      result.runtime.hasRecentHeartbeat ? 1 : 0,
+      result.runtime.hoursSinceHeartbeat,
+      result.aiJudge?.score ?? null,
+      result.aiJudge?.summary ?? null,
+      result.aiJudge?.issues ?? null,
+      result.aiJudge?.cachedAt ?? null,
+      result.config.tracesEnabled ? 1 : 0,
+      result.config.traceSamplingRate,
+      result.config.logSamplingRate,
+      result.config.invocationLogsEnabled ? 1 : 0,
+      result.config.sourceMapsEnabled ? 1 : 0,
+      result.aiJudge?.rubricScores.sdk ?? null,
+      result.aiJudge?.rubricScores.observability ?? null,
+      result.aiJudge?.rubricScores.costProtection ?? null,
+      result.aiJudge?.rubricScores.security ?? null,
+      result.aiJudge?.rubricEvidence ?? null,
+      result.aiJudge?.reasoning ?? null,
+      result.aiJudge?.categorisedIssues ?? null,
+      result.aiJudge?.validationRetries ?? 0,
+      result.scanType,
+      result.focusedDimensions ? JSON.stringify(result.focusedDimensions) : null,
+      result.compositeScore
+    ).run();
+
+    log.debug('Stored audit result', { project: result.project, auditId });
+  } catch (error) {
+    log.error('Failed to store audit result', error, { project: result.project });
+  }
+}
+
+async function storeBehavioralResults(
+  project: string,
+  result: BehavioralResult,
+  env: AuditorEnv,
+  log: Logger
+): Promise<void> {
+  const auditDate = new Date().toISOString().split('T')[0];
+  try {
+    for (const hotspot of result.hotspots) {
+      await env.PLATFORM_DB.prepare(
+        `INSERT OR REPLACE INTO audit_file_hotspots (
+          project, file_path, change_count, has_sdk_patterns, hotspot_score, audit_date
+        ) VALUES (?, ?, ?, ?, ?, ?)`
+      ).bind(project, hotspot.filePath, hotspot.changeCount, hotspot.hasSdkPatterns ? 1 : 0, hotspot.hotspotScore, auditDate).run();
+    }
+    for (const reg of result.regressions) {
+      await env.PLATFORM_DB.prepare(
+        `INSERT OR IGNORE INTO audit_sdk_regressions (
+          project, commit_sha, commit_message, file_path, regression_type, audit_date
+        ) VALUES (?, ?, ?, ?, ?, ?)`
+      ).bind(project, reg.commitSha, reg.commitMessage, reg.filePath, `${reg.removedPattern}_removed`, auditDate).run();
+    }
+  } catch (error) {
+    log.error('Failed to store behavioral results', error, { project });
+  }
+}
+
+// =============================================================================
+// ALERT SENDING
+// =============================================================================
+
+async function sendAlerts(
+  auditId: string,
+  results: ProjectAuditResult[],
+  env: AuditorEnv,
+  log: Logger
+): Promise<void> {
+  const unhealthy = results.filter((r) => r.status !== 'HEALTHY');
+  if (unhealthy.length === 0) return;
+
+  try {
+    await env.ALERT_ROUTER.fetch('https://internal/alerts', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        source: 'platform-auditor',
+        auditId,
+        alerts: unhealthy.map((r) => ({
+          project: r.project,
+          status: r.status,
+          message: r.statusMessage,
+          score: r.compositeScore,
+        })),
+      }),
+    });
+  } catch (error) {
+    log.warn('Failed to send alerts (non-fatal)', error);
+  }
+}
+
+// =============================================================================
+// MAIN WORKER
+// =============================================================================
+
+export default {
+  async scheduled(event: ScheduledEvent, env: AuditorEnv, ctx: ExecutionContext): Promise<void> {
+    const log = createLogger({ worker: 'platform-auditor', featureId: FEATURE_AUDITOR });
+    const scanType = determineScanType(event.scheduledTime);
+    log.info('Audit triggered', { scan_type: scanType });
+
+    try {
+      const trackedEnv = withCronBudget(env, FEATURE_AUDITOR, {
+        ctx, cronExpression: '0 0 * * 0,3',
+      });
+
+      const config = await loadAuditConfig(env, log);
+      if (Object.keys(config.targets).length === 0) {
+        log.warn('No audit targets configured — add targets to config/audit-targets.yaml and sync');
+        await completeTracking(trackedEnv);
+        return;
+      }
+
+      const auditId = generateAuditId();
+      const results: ProjectAuditResult[] = [];
+
+      for (const [project, target] of Object.entries(config.targets)) {
+        let focusedDimensions: AuditDimension[] | null = null;
+        if (scanType === 'focused') {
+          const { dimensions, previousScore } = await getWeakDimensions(
+            project, config.focusedScanThreshold, env, log
+          );
+          if (previousScore >= config.focusedScanThreshold && dimensions.length === 0) {
+            log.info('Skipping project (above threshold)', { project, previousScore });
+            continue;
+          }
+          focusedDimensions = dimensions;
+        }
+
+        try {
+          // Layer 1: Config
+          const wranglerContent = await fetchGitHubFile(target.repo, target.wranglerPath, env.GITHUB_TOKEN, log);
+          const wranglerConfig = wranglerContent ? parseJsonc(wranglerContent) : null;
+          const configResult = checkConfig(wranglerConfig);
+
+          // Layer 2: Code smells
+          let entryPointContent = await fetchGitHubFile(target.repo, target.entryPoint, env.GITHUB_TOKEN, log);
+          if (!entryPointContent && target.entryPointFallback) {
+            entryPointContent = await fetchGitHubFile(target.repo, target.entryPointFallback, env.GITHUB_TOKEN, log);
+          }
+          const codeResult = checkCodeSmells(entryPointContent, config.sdkPatterns);
+
+          // Layer 3: Runtime
+          const runtimeResult = await checkRuntime(project, config.heartbeatFreshnessHours, env, log);
+
+          // Layer 4: AI Judge
+          let aiJudge: AIJudgeResult | null = null;
+          if (env.PLATFORM_AI_GATEWAY_KEY && entryPointContent) {
+            const staticChecks = {
+              hasPlatformCache: configResult.hasPlatformCache,
+              hasPlatformTelemetry: configResult.hasPlatformTelemetry,
+              observabilityEnabled: configResult.observabilityEnabled,
+              hasFeatureBudget: codeResult.hasWithFeatureBudget,
+            };
+
+            let supplementary = '';
+            const dims = scanType === 'full'
+              ? (['sdk', 'observability', 'cost', 'security'] as AuditDimension[])
+              : (focusedDimensions ?? []);
+            if (dims.length > 0) {
+              supplementary = await fetchDeepScanFiles(target, dims, env, log);
+            }
+
+            aiJudge = await auditWithGemini(
+              project, entryPointContent, wranglerContent, staticChecks, supplementary, config, env, log
+            );
+          }
+
+          // Determine status
+          const status = determineStatus(configResult, codeResult, runtimeResult);
+          const statusMessage = generateStatusMessage(status, configResult, codeResult, runtimeResult);
+          const compositeScore = aiJudge?.score ?? 0;
+
+          // Behavioral analysis
+          let behavioral: BehavioralResult | null = null;
+          try {
+            behavioral = await runBehavioralAnalysis(project, target.repo, config.sdkPatterns, config, env, log);
+            await storeBehavioralResults(project, behavioral, env, log);
+          } catch (error) {
+            log.warn('Behavioral analysis failed (non-fatal)', error, { project });
+          }
+
+          const auditResult: ProjectAuditResult = {
+            project, auditId, status, statusMessage, scanType,
+            focusedDimensions, config: configResult, codeSmells: codeResult,
+            runtime: runtimeResult, aiJudge: aiJudge, behavioral,
+            compositeScore, timestamp: new Date().toISOString(),
+          };
+
+          results.push(auditResult);
+          await storeAuditResult(auditId, auditResult, env, log);
+        } catch (error) {
+          log.error('Project audit failed', error, { project });
+        }
+      }
+
+      // Store latest in KV
+      await env.PLATFORM_CACHE.put('AUDIT:LATEST', JSON.stringify({
+        auditId, results, scanType, timestamp: new Date().toISOString(),
+      }), { expirationTtl: 30 * 24 * 60 * 60 });
+
+      // Feature coverage + comprehensive report (full scans only)
+      if (scanType === 'full') {
+        let featureCoverage: FeatureCoverageReport | null = null;
+        try {
+          featureCoverage = await runFeatureCoverageAudit(env, log);
+          await storeFeatureCoverageAudit(env, featureCoverage, log);
+        } catch (error) { log.warn('Feature coverage audit failed (non-fatal)', error); }
+
+        try {
+          const report = await generateComprehensiveReport(env, featureCoverage, log);
+          await storeComprehensiveReport(env, report, log);
+        } catch (error) { log.warn('Comprehensive report failed (non-fatal)', error); }
+      }
+
+      await sendAlerts(auditId, results, env, log);
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      await health(FEATURE_HEARTBEAT, env.PLATFORM_CACHE as any, env.PLATFORM_TELEMETRY, ctx);
+      await completeTracking(trackedEnv);
+      pingHeartbeat(ctx, env.GATUS_HEARTBEAT_URL, env.GATUS_TOKEN, true);
+
+      log.info('Audit complete', {
+        auditId, scanType, totalProjects: results.length,
+        healthy: results.filter((r) => r.status === 'HEALTHY').length,
+      });
+    } catch (error) {
+      if (error instanceof CircuitBreakerError) {
+        log.warn('Circuit breaker STOP', error);
+        return;
+      }
+      pingHeartbeat(ctx, env.GATUS_HEARTBEAT_URL, env.GATUS_TOKEN, false);
+      log.error('Audit failed', error);
+    }
+  },
+
+  async fetch(request: Request, env: AuditorEnv, ctx: ExecutionContext): Promise<Response> {
+    const url = new URL(request.url);
+
+    if (url.pathname === '/health') {
+      return Response.json({ status: 'ok', service: 'platform-auditor', timestamp: new Date().toISOString() });
+    }
+
+    const traceContext = createTraceContext(request, env);
+    const log = createLoggerFromRequest(request, env, 'platform-auditor', FEATURE_AUDITOR);
+
+    try {
+      const trackedEnv = withFeatureBudget(env, FEATURE_AUDITOR, { ctx });
+
+      if (url.pathname === '/audit' && request.method === 'GET') {
+        const requestedType = url.searchParams.get('type') || 'full';
+        const fakeDay = requestedType === 'focused' ? 3 : 0;
+        const fakeDate = new Date();
+        fakeDate.setUTCDate(fakeDate.getUTCDate() + ((fakeDay - fakeDate.getUTCDay() + 7) % 7));
+        await this.scheduled({ scheduledTime: fakeDate.getTime(), cron: '0 0 * * 0,3', noRetry: () => {} } as unknown as ScheduledEvent, env, ctx);
+        await completeTracking(trackedEnv);
+        return Response.json({ status: 'audit_triggered', scan_type: requestedType });
+      }
+
+      if (url.pathname === '/audit/latest') {
+        const latest = await env.PLATFORM_CACHE.get('AUDIT:LATEST');
+        await completeTracking(trackedEnv);
+        if (!latest) return Response.json({ error: 'No audit results found' }, { status: 404 });
+        return Response.json(JSON.parse(latest));
+      }
+
+      if (url.pathname.startsWith('/audit/latest/')) {
+        const project = url.pathname.split('/').pop();
+        const latest = await env.PLATFORM_CACHE.get('AUDIT:LATEST');
+        await completeTracking(trackedEnv);
+        if (!latest) return Response.json({ error: 'No audit results' }, { status: 404 });
+        const parsed = JSON.parse(latest) as { auditId: string; results: ProjectAuditResult[] };
+        const result = parsed.results.find((r) => r.project === project);
+        if (!result) return Response.json({ error: `Project ${project} not found` }, { status: 404 });
+        return Response.json({ auditId: parsed.auditId, result });
+      }
+
+      await completeTracking(trackedEnv);
+      return Response.json({
+        service: 'platform-auditor',
+        endpoints: [
+          'GET /health', 'GET /audit?type=full|focused',
+          'GET /audit/latest', 'GET /audit/latest/:project',
+        ],
+      });
+    } catch (error) {
+      if (error instanceof CircuitBreakerError) {
+        return Response.json({ error: 'Service temporarily unavailable', code: 'CIRCUIT_BREAKER' }, { status: 503, headers: { 'Retry-After': '60' } });
+      }
+      log.error('Request failed', error, { path: url.pathname, traceId: traceContext.traceId });
+      return Response.json({ error: 'Internal server error', traceId: traceContext.traceId }, { status: 500 });
+    }
+  },
+};