palaryn 0.1.0 → 0.3.2

package/src/server/gateway.ts

@@ -0,0 +1,1130 @@
+import * as crypto from 'crypto';
+import { Tracer, Span, SpanKind, SpanStatusCode } from '@opentelemetry/api';
+import { ToolCall } from '../types/tool-call';
+import { ToolResult, ToolResultStatus, DLPSeverity } from '../types/tool-result';
+import { PolicyEvalResult, PolicyPack, PolicyTransformation } from '../types/policy';
+import { PolicyEngine } from '../policy/engine';
+import { OPAEngine } from '../policy/opa-engine';
+import { DLPScanner } from '../dlp/scanner';
+import { CompositeDLPScanner } from '../dlp/composite-scanner';
+import { DLPBackend } from '../dlp/interfaces';
+import { PromptInjectionBackend } from '../dlp/prompt-injection-backend';
+import { TruffleHogBackend } from '../dlp/trufflehog-backend';
+import { BudgetManager, CostRecord } from '../budget/manager';
+import { UsageExtractor } from '../budget/usage-extractor';
+import { AuditLogger } from '../audit/logger';
+import { HttpExecutor } from '../executor/http-executor';
+import { ExecutorRegistry } from '../executor/registry';
+import { ToolExecutor } from '../executor/interfaces';
+import { FilesystemExecutor } from '../executor/filesystem-executor';
+import { SQLExecutor } from '../executor/sql-executor';
+import { ShellExecutor } from '../executor/shell-executor';
+import { WebSocketExecutor } from '../executor/websocket-executor';
+import { ApprovalManager } from '../approval/manager';
+import { RateLimiter } from '../ratelimit/limiter';
+import { InMemoryIdempotencyStore } from '../storage/memory';
+import { IdempotencyStore, AuditStore, BudgetStore, ApprovalStore, RateLimitStore, PolicyStore, RateLimitConfigStore, BudgetConfigStore } from '../storage/interfaces';
+import { GatewayConfig, RateLimitConfig } from '../types/config';
+import { UsageData } from '../types/tool-result';
+import { GatewayMetrics } from '../metrics';
+import { GatewayTracer } from '../tracing';
+import { AnomalyDetector } from '../anomaly';
+import { log as devLog, logger } from './logger';
+
+export interface PreExecuteResult {
+  allowed: boolean;
+  result?: ToolResult;
+  policyResult?: PolicyEvalResult;
+  processedToolCall?: ToolCall;
+  argsDlp?: { detected: string[]; redactions: any[]; severity: DLPSeverity };
+  budgetCheck?: { report: any; allowed: boolean; reason?: string };
+  reservationKey?: string;
+  stepTimings: Record<string, number>;
+  startTime: number;
+}
+
+/** In-flight entry stores the promise, a timeout handle, and a creation timestamp. */
+interface InFlightEntry {
+  promise: Promise<ToolResult>;
+  timeout: ReturnType<typeof setTimeout>;
+  createdAt: number;
+}
+
+/** Compute a short body hash for idempotency cache keys (A2). */
+function computeBodyHash(toolCall: ToolCall): string {
+  const payload = toolCall.tool.name + JSON.stringify(toolCall.args);
+  return crypto.createHash('sha256').update(payload).digest('hex').substring(0, 16);
+}
+
+const DEFAULT_RATE_LIMIT: RateLimitConfig = {
+  enabled: false,
+  actor_max_per_window: 100,
+  workspace_max_per_window: 500,
+  window_ms: 60000,
+};
+
+// ---------------------------------------------------------------------------
+// Span helpers — no-op when otel is undefined
+// ---------------------------------------------------------------------------
+
+function childSpan<T>(otel: Tracer | undefined, name: string, fn: () => T): T {
+  if (!otel) return fn();
+  return otel.startActiveSpan(name, (s: Span) => {
+    try {
+      const result = fn();
+      s.end();
+      return result;
+    } catch (e) {
+      s.setStatus({ code: SpanStatusCode.ERROR, message: String(e) });
+      s.recordException(e as Error);
+      s.end();
+      throw e;
+    }
+  });
+}
+
+async function asyncChildSpan<T>(otel: Tracer | undefined, name: string, fn: () => Promise<T>): Promise<T> {
+  if (!otel) return fn();
+  return otel.startActiveSpan(name, async (s: Span) => {
+    try {
+      const result = await fn();
+      s.end();
+      return result;
+    } catch (e) {
+      s.setStatus({ code: SpanStatusCode.ERROR, message: String(e) });
+      s.recordException(e as Error);
+      s.end();
+      throw e;
+    }
+  });
+}
+
+export class Gateway {
+  private policyEngine: PolicyEngine;
+  private dlpScanner: DLPScanner | CompositeDLPScanner;
+  private budgetManager: BudgetManager;
+  private auditLogger: AuditLogger;
+  private executorRegistry: ExecutorRegistry;
+  private httpExecutor: HttpExecutor;
+  private approvalManager: ApprovalManager;
+  private rateLimiter: RateLimiter;
+  private idempotencyStore: IdempotencyStore;
+  private config: GatewayConfig;
+  private metrics?: GatewayMetrics;
+  private tracer?: GatewayTracer;
+  private anomalyDetector?: AnomalyDetector;
+  private opaEngine?: OPAEngine;
+  private policyStore?: PolicyStore;
+  private rateLimitConfigStore?: RateLimitConfigStore;
+  private budgetConfigStore?: BudgetConfigStore;
+  private usageExtractor: UsageExtractor;
+  private inFlightCleanupInterval?: ReturnType<typeof setInterval>;
+  /**
+   * Tracks tool_call_ids currently being processed to prevent TOCTOU races.
+   * Maps cacheKey -> InFlightEntry so duplicate arrivals can await
+   * the in-flight result instead of executing a second time.
+   */
+  private inFlightCalls = new Map<string, InFlightEntry>();
+
+  constructor(config: GatewayConfig, metrics?: GatewayMetrics, tracer?: GatewayTracer) {
+    this.config = config;
+    this.metrics = metrics;
+    this.tracer = tracer;
+    this.policyEngine = new PolicyEngine(config.policy.pack_path, config.policy.default_effect);
+    // Build DLP pipeline: use CompositeDLPScanner when additional backends are configured
+    const dlpBackends: DLPBackend[] = [];
+    if (config.dlp.prompt_injection_detection !== false) {
+      dlpBackends.push(new PromptInjectionBackend({
+        scan_output: config.dlp.scan_output,
+      }));
+    }
+    if (config.dlp.trufflehog?.enabled) {
+      dlpBackends.push(new TruffleHogBackend({
+        binaryPath: config.dlp.trufflehog.binary_path,
+        timeout: config.dlp.trufflehog.timeout_ms,
+      }));
+    }
+    if (dlpBackends.length > 0) {
+      this.dlpScanner = new CompositeDLPScanner(config.dlp, dlpBackends);
+    } else {
+      this.dlpScanner = new DLPScanner(config.dlp);
+    }
+    this.budgetManager = new BudgetManager(config.budget);
+    this.auditLogger = new AuditLogger(config.audit);
+    this.approvalManager = new ApprovalManager(config.approval);
+    this.rateLimiter = new RateLimiter(config.rate_limit || DEFAULT_RATE_LIMIT);
+    this.idempotencyStore = new InMemoryIdempotencyStore();
+
+    // Set up anomaly detector if enabled
+    if (config.anomaly?.enabled) {
+      this.anomalyDetector = new AnomalyDetector(config.anomaly);
+    }
+
+    // Set up OPA engine if enabled
+    if (config.policy.opa?.enabled) {
+      this.opaEngine = new OPAEngine(config.policy.opa);
+    }
+
+    this.usageExtractor = new UsageExtractor(config.budget.token_pricing);
+
+    // Set up executor registry with HTTP as default + catch-all fallback
+    this.executorRegistry = new ExecutorRegistry();
+    this.httpExecutor = new HttpExecutor(config.executor);
+    this.executorRegistry.register('http.*', this.httpExecutor);
+    this.executorRegistry.register('*', this.httpExecutor); // fallback
+
+    // Register non-HTTP executors (conditionally enabled via config)
+    if (config.executor.filesystem?.enabled) {
+      this.executorRegistry.register('file.*', new FilesystemExecutor(config.executor.filesystem), true);
+    }
+    if (config.executor.sql?.enabled) {
+      this.executorRegistry.register('sql.*', new SQLExecutor(config.executor.sql), true);
+    }
+    if (config.executor.shell?.enabled) {
+      this.executorRegistry.register('shell.*', new ShellExecutor(config.executor.shell), true);
+    }
+    if (config.executor.websocket?.enabled) {
+      this.executorRegistry.register('ws.*', new WebSocketExecutor(config.executor.websocket), true);
+    }
+
+    // A1: Periodic cleanup of stale inFlightCalls entries (every 60s, remove entries older than 5min)
+    this.inFlightCleanupInterval = setInterval(() => {
+      const now = Date.now();
+      const MAX_AGE_MS = 5 * 60 * 1000;
+      for (const [key, entry] of this.inFlightCalls) {
+        if (now - entry.createdAt > MAX_AGE_MS) {
+          clearTimeout(entry.timeout);
+          this.inFlightCalls.delete(key);
+        }
+      }
+    }, 60_000);
+    // Don't let the interval prevent process exit
+    if (this.inFlightCleanupInterval.unref) {
+      this.inFlightCleanupInterval.unref();
+    }
+  }
+
+  /** Register a custom executor for a tool name pattern (prepends to take priority over catch-all) */
+  registerExecutor(pattern: string, executor: ToolExecutor): void {
+    this.executorRegistry.register(pattern, executor, true);
+  }
+
+  /**
+   * Run the pre-execution pipeline: rate limit, anomaly, policy, DLP args, budget.
+   * Does NOT handle idempotency or in-flight tracking — the caller manages those.
+   * Returns { allowed: true, ... } with pipeline state on success, or
+   * { allowed: false, result } with a ToolResult to return to the client.
+   */
+  async preExecute(toolCall: ToolCall, otel?: Tracer, requestingApiKeyId?: string): Promise<PreExecuteResult> {
+    const startTime = Date.now();
+    const stepTimings: Record<string, number> = {};
+    let stepStart: number;
+
+    // A3: Capture a local reference to the policy engine so the request uses
+    // a consistent snapshot even if reloadPolicy() swaps the engine mid-request.
+    const policyEngine = this.policyEngine;
+
+    if (!toolCall.timestamp) {
+      toolCall.timestamp = new Date().toISOString();
+    }
+
+    devLog.pipelineStart(toolCall.tool_call_id, toolCall.tool.name);
+
+    // Log receipt
+    this.auditLogger.logToolCallReceived(toolCall);
+
+    // Rate limit check (with optional per-workspace overrides)
+    stepStart = Date.now();
+    const wsRateLimitOverrides = toolCall.workspace_id
+      ? this.getWorkspaceRateLimitConfig(toolCall.workspace_id)
+      : undefined;
+    const rateLimitResult = childSpan(otel, 'gateway.rate_limit', () => {
+      return this.rateLimiter.check(toolCall, wsRateLimitOverrides);
+    });
+    stepTimings.rate_limit = Date.now() - stepStart;
+    if (!rateLimitResult.allowed) {
+      devLog.rateLimit(false, rateLimitResult.current, rateLimitResult.limit, rateLimitResult.blocked_by);
+      this.metrics?.recordRateLimitBlock(rateLimitResult.blocked_by || 'unknown');
+      const durationSec = (Date.now() - startTime) / 1000;
+      this.metrics?.recordRequest('blocked', toolCall.tool.name, toolCall.tool.capability, durationSec);
+      const result = this.buildResult(toolCall, 'blocked', {
+        decision: 'deny',
+        rule_id: 'rate_limit',
+        rule_name: 'Rate limit',
+        reasons: [`Rate limit exceeded (${rateLimitResult.blocked_by}): ${rateLimitResult.current}/${rateLimitResult.limit} requests in window`],
+      }, startTime, undefined,
+        `Rate limit exceeded by ${rateLimitResult.blocked_by}: ${rateLimitResult.current}/${rateLimitResult.limit} requests. Resets at ${rateLimitResult.reset_at}`);
+      devLog.pipelineEnd('blocked', Date.now() - startTime);
+      return { allowed: false, result, stepTimings, startTime };
+    }
+    devLog.rateLimit(true, rateLimitResult.current, rateLimitResult.limit);
+
+    // Anomaly detection
+    stepStart = Date.now();
+    const anomalyAlerts = childSpan(otel, 'gateway.anomaly_detection', () => {
+      return this.anomalyDetector?.analyze(toolCall) || [];
+    });
+    stepTimings.anomaly = Date.now() - stepStart;
+    if (anomalyAlerts.length > 0 && this.config.anomaly?.action === 'block') {
+      const highSeverity = anomalyAlerts.filter(a => a.severity === 'high');
+      if (highSeverity.length > 0) {
+        devLog.anomaly(anomalyAlerts.length, true);
+        const durationSec = (Date.now() - startTime) / 1000;
+        this.metrics?.recordRequest('blocked', toolCall.tool.name, toolCall.tool.capability, durationSec);
+        const result = this.buildResult(toolCall, 'blocked', {
+          decision: 'deny',
+          rule_id: 'anomaly_detection',
+          rule_name: 'Anomaly detection',
+          reasons: highSeverity.map(a => `${a.anomaly_type}: ${a.metric} z-score=${a.z_score.toFixed(2)}`),
+        }, startTime, undefined, 'Blocked by anomaly detection');
+        devLog.pipelineEnd('blocked', Date.now() - startTime);
+        return { allowed: false, result, stepTimings, startTime };
+      }
+    }
+    devLog.anomaly(anomalyAlerts.length, false);
+
+    // DLP scan on full toolCall (args + context + actor fields)
+    // Runs BEFORE policy evaluation so secrets are always detected regardless of policy outcome
+    stepStart = Date.now();
+    const argsDlp = childSpan(otel, 'gateway.dlp_scan_args', () => {
+      if (!this.config.dlp.scan_args) {
+        return { detected: [] as string[], redactions: [] as any[], severity: 'low' as DLPSeverity };
+      }
+      return this.dlpScanner.scan(toolCall, '');
+    });
+    stepTimings.dlp_args = Date.now() - stepStart;
+    this.auditLogger.logDLPScanned(toolCall, argsDlp.detected, argsDlp.severity, argsDlp.redactions.length, argsDlp.redactions);
+    devLog.dlp('args', argsDlp.detected, argsDlp.severity, argsDlp.redactions.length);
+
+    if (argsDlp.detected.length > 0) {
+      for (const detectionType of argsDlp.detected) {
+        this.metrics?.recordDLPDetection(detectionType, argsDlp.severity);
+      }
+    }
+    if (argsDlp.severity === 'high') {
+      this.auditLogger.logIncident(toolCall, 'high', 'dlp_secret_detected',
+        `High severity DLP detection in args: ${argsDlp.detected.join(', ')}`,
+        'Review and rotate any exposed credentials');
+    }
+
+    // Prompt injection blocking check (before policy, so it always runs)
+    const piAction = this.config.dlp.prompt_injection_action || 'log';
+    if (piAction === 'block' && argsDlp.detected.length > 0) {
+      const piDetections = argsDlp.detected.filter((d: string) => d.startsWith('prompt_injection_'));
+      if (piDetections.length > 0) {
+        const threshold = this.config.dlp.prompt_injection_block_threshold || 'high';
+        const severityRank: Record<string, number> = { low: 0, medium: 1, high: 2 };
+        const thresholdRank = severityRank[threshold] ?? 2;
+        const maxSeverityRank = severityRank[argsDlp.severity] ?? 0;
+
+        if (maxSeverityRank >= thresholdRank) {
+          const responseMode = this.config.dlp.prompt_injection_response || 'deny';
+
+          if (responseMode === 'require_approval') {
+            const { approval, token } = this.approvalManager.createApproval(
+              toolCall,
+              'admin',
+              `Prompt injection detected: ${piDetections.join(', ')}`,
+              undefined,
+              requestingApiKeyId,
+            );
+            await this.approvalManager.flush();
+            const durationSec = (Date.now() - startTime) / 1000;
+            this.metrics?.recordRequest('needs_approval', toolCall.tool.name, toolCall.tool.capability, durationSec);
+            const result = this.buildResult(toolCall, 'needs_approval', { decision: 'require_approval', rule_id: 'prompt_injection', rule_name: 'Prompt injection detected', reasons: piDetections }, startTime, undefined,
+              undefined, { approval_id: approval.approval_id, token, expires_at: approval.expires_at }, argsDlp);
+            devLog.pipelineEnd('needs_approval', Date.now() - startTime);
+            return { allowed: false, result, stepTimings, startTime };
+          }
+
+          devLog.pipelineStep('🛡️', 'PROMPT_INJECTION_BLOCK',
+            `Blocked: ${piDetections.join(', ')} (severity: ${argsDlp.severity}, threshold: ${threshold})`);
+          const durationSec = (Date.now() - startTime) / 1000;
+          this.metrics?.recordRequest('blocked', toolCall.tool.name, toolCall.tool.capability, durationSec);
+          const result = this.buildResult(toolCall, 'blocked', {
+            decision: 'deny',
+            rule_id: 'prompt_injection_block',
+            rule_name: 'Prompt injection detected',
+            reasons: [`Prompt injection detected: ${piDetections.join(', ')}`],
+          }, startTime, undefined,
+            `Blocked by prompt injection detection: ${piDetections.join(', ')} (severity: ${argsDlp.severity})`,
+            undefined, argsDlp);
+          devLog.pipelineEnd('blocked', Date.now() - startTime);
+          return { allowed: false, result, stepTimings, startTime };
+        }
+      }
+    }
+
+    // Policy evaluation — DLP context is passed so DLP-conditioned rules
+    // compete with all other rules in a single priority-ordered pass.
+    stepStart = Date.now();
+    const dlpContext = argsDlp.detected.length > 0
+      ? { detected: argsDlp.detected, severity: argsDlp.severity as string, pattern_names: argsDlp.detected }
+      : undefined;
+    let policyResult!: PolicyEvalResult;
+    let usedWorkspacePolicy = false;
+    if (this.policyStore && toolCall.workspace_id) {
+      const workspacePack = this.policyStore.getByWorkspaceId(toolCall.workspace_id);
+      if (workspacePack) {
+        policyResult = childSpan(otel, 'gateway.policy_eval_workspace', () => {
+          const ephemeralEngine = PolicyEngine.fromPack(workspacePack);
+          return ephemeralEngine.evaluate(toolCall, dlpContext);
+        });
+        usedWorkspacePolicy = true;
+      }
+    }
+    if (!usedWorkspacePolicy) {
+      if (this.opaEngine) {
+        try {
+          policyResult = await asyncChildSpan(otel, 'gateway.policy_eval_opa', async () => {
+            return this.opaEngine!.evaluate(toolCall);
+          });
+          if (policyResult.rule_id === 'opa_fallback') {
+            policyResult = childSpan(otel, 'gateway.policy_eval', () => {
+              return policyEngine.evaluate(toolCall, dlpContext);
+            });
+          }
+        } catch (err) {
+          logger.error('OPA evaluation failed, falling back to YAML engine', { component: 'gateway', error: err instanceof Error ? err.message : String(err) });
+          policyResult = childSpan(otel, 'gateway.policy_eval', () => {
+            return policyEngine.evaluate(toolCall, dlpContext);
+          });
+        }
+      } else {
+        policyResult = childSpan(otel, 'gateway.policy_eval', () => {
+          return policyEngine.evaluate(toolCall, dlpContext);
+        });
+      }
+    }
+    stepTimings.policy = Date.now() - stepStart;
+    this.auditLogger.logPolicyDecided(toolCall, policyResult.decision, policyResult.rule_id, policyResult.reasons);
+    this.metrics?.recordPolicyDecision(policyResult.decision, policyResult.rule_id || 'unknown');
+    devLog.policy(policyResult.decision, policyResult.rule_id, policyResult.reasons);
+
+    // Policy: deny
+    if (policyResult.decision === 'deny') {
+      const durationSec = (Date.now() - startTime) / 1000;
+      this.metrics?.recordRequest('blocked', toolCall.tool.name, toolCall.tool.capability, durationSec);
+      const ruleInfo = policyResult.rule_id ? ` [rule: ${policyResult.rule_id}]` : '';
+      const result = this.buildResult(toolCall, 'blocked', policyResult, startTime, undefined,
+        `Blocked by policy${ruleInfo}: ${policyResult.reasons.join(', ')}`, undefined, argsDlp);
+      devLog.pipelineEnd('blocked', Date.now() - startTime);
+      return { allowed: false, result, policyResult, argsDlp, stepTimings, startTime };
+    }
+
+    // Policy: require_approval (DLP report is now always included)
+    if (policyResult.decision === 'require_approval') {
+      const existingApproval = this.approvalManager.findApprovedForTask(
+        toolCall.task_id,
+        toolCall.actor.id,
+        toolCall.tool.name,
+        toolCall.tool.capability
+      );
+      if (existingApproval) {
+        devLog.pipelineStep('✅', 'APPROVAL_BYPASS', `Reusing approval ${existingApproval.approval_id} for task ${toolCall.task_id}`);
+        policyResult = { ...policyResult, decision: 'allow', rule_id: `approved:${existingApproval.approval_id}` };
+        // Fall through to budget/execute below
+      } else {
+      const { approval, token } = this.approvalManager.createApproval(
+        toolCall,
+        policyResult.approval?.scope || 'admin',
+        policyResult.approval?.reason || policyResult.reasons.join(', '),
+        policyResult.approval?.ttl_seconds,
+        requestingApiKeyId,
+      );
+      await this.approvalManager.flush();
+      this.auditLogger.logApprovalRequested(
+        toolCall,
+        approval.scope,
+        approval.reason,
+        this.config.approval.default_ttl_seconds
+      );
+      const durationSec = (Date.now() - startTime) / 1000;
+      this.metrics?.recordRequest('needs_approval', toolCall.tool.name, toolCall.tool.capability, durationSec);
+      this.metrics?.setActiveApprovals(this.approvalManager.getPendingApprovals().length);
+      const result = this.buildResult(toolCall, 'needs_approval', policyResult, startTime, undefined,
+        undefined, { approval_id: approval.approval_id, token, expires_at: approval.expires_at }, argsDlp);
+      return { allowed: false, result, policyResult, argsDlp, stepTimings, startTime };
+      }
+    }
+
+    // Apply transformations
+    let processedToolCall = toolCall;
+    if (policyResult.decision === 'transform' && policyResult.transformations) {
+      devLog.transform(policyResult.transformations);
+      processedToolCall = this.applyTransformations(toolCall, policyResult.transformations);
+    }
+
+    // Budget check + atomic reservation (S5) with optional per-workspace overrides
+    stepStart = Date.now();
+    const wsBudgetOverrides = processedToolCall.workspace_id
+      ? this.getWorkspaceBudgetConfig(processedToolCall.workspace_id)
+      : undefined;
+    const budgetCheck = await asyncChildSpan(otel, 'gateway.budget_check', () => {
+      return this.budgetManager.reserveAndCheck(processedToolCall, wsBudgetOverrides);
+    });
+    stepTimings.budget = Date.now() - stepStart;
+    this.auditLogger.logBudgetChecked(toolCall, budgetCheck.report.estimated_cost_usd, budgetCheck.report.spent_cost_usd_task, budgetCheck.report.remaining_cost_usd_task);
+
+    if (!budgetCheck.allowed) {
+      devLog.budget(false, budgetCheck.report.estimated_cost_usd, budgetCheck.report.spent_cost_usd_task, budgetCheck.report.remaining_cost_usd_task, budgetCheck.reason);
+      this.metrics?.recordBudgetBlock(this.classifyBudgetReason(budgetCheck.reason || ''));
+      const durationSec = (Date.now() - startTime) / 1000;
+      this.metrics?.recordRequest('blocked', toolCall.tool.name, toolCall.tool.capability, durationSec);
+      const spent = budgetCheck.report.spent_cost_usd_task?.toFixed(4) ?? '?';
+      const remaining = budgetCheck.report.remaining_cost_usd_task?.toFixed(4) ?? '?';
+      const estimated = budgetCheck.report.estimated_cost_usd?.toFixed(4) ?? '?';
+      const result = this.buildResult(toolCall, 'blocked', policyResult, startTime, undefined,
+        `Budget exceeded: ${budgetCheck.reason} (spent: $${spent}, remaining: $${remaining}, estimated: $${estimated})`, undefined, argsDlp, budgetCheck.report);
+      devLog.pipelineEnd('blocked', Date.now() - startTime);
+      return { allowed: false, result, policyResult, processedToolCall, argsDlp, budgetCheck, stepTimings, startTime };
+    }
+    devLog.budget(true, budgetCheck.report.estimated_cost_usd, budgetCheck.report.spent_cost_usd_task, budgetCheck.report.remaining_cost_usd_task);
+
+    return { allowed: true, policyResult, processedToolCall, argsDlp, budgetCheck, reservationKey: budgetCheck.reservationKey, stepTimings, startTime };
+  }
+
+  /**
+   * Run the post-execution pipeline: DLP scan output, usage extraction, budget recording,
+   * metrics, audit log, and build the final ToolResult.
+   * Does NOT cache for idempotency — the caller handles that.
+   */
+  async postExecute(
+    toolCall: ToolCall,
+    output: { http_status?: number; body?: unknown; headers?: Record<string, string> },
+    pre: PreExecuteResult,
+    otel?: Tracer,
+  ): Promise<ToolResult> {
+    const { policyResult, processedToolCall, argsDlp, budgetCheck, reservationKey, stepTimings, startTime } = pre;
+
+    const executionDuration = Date.now() - startTime;
+    devLog.executed(output.http_status || 200, executionDuration);
+    this.auditLogger.logToolExecuted(toolCall, 'ok', executionDuration, output.http_status);
+
+    // Record result for anomaly detection
+    this.anomalyDetector?.recordResult(toolCall, executionDuration, false);
+    this.anomalyDetector?.analyzeResult(toolCall, executionDuration, false);
+
+    // DLP scan on output
+    let stepStart = Date.now();
+    let outputDlp: { detected: string[]; redactions: any[]; severity: DLPSeverity } = { detected: [], redactions: [], severity: 'low' };
+    if (this.config.dlp.scan_output && output.body) {
+      outputDlp = childSpan(otel, 'gateway.dlp_scan_output', () => {
+        return this.dlpScanner.scan(output, 'output');
+      });
+      devLog.dlp('output', outputDlp.detected, outputDlp.severity, outputDlp.redactions.length);
+      if (outputDlp.detected.length > 0) {
+        this.auditLogger.logDLPScanned(toolCall, outputDlp.detected, outputDlp.severity, outputDlp.redactions.length, outputDlp.redactions);
+        for (const detectionType of outputDlp.detected) {
+          this.metrics?.recordDLPDetection(detectionType, outputDlp.severity);
+        }
+      }
+    } else if (!this.config.dlp.scan_output && output.body) {
+      // Warn when DLP output scanning is disabled for sensitive operations
+      const capability = toolCall.tool.capability;
+      if (capability === 'write' || capability === 'delete' || capability === 'admin') {
+        logger.warn('DLP output scanning is disabled for sensitive operation', {
+          component: 'gateway',
+          tool: toolCall.tool.name,
+          capability,
+          hint: 'Enable dlp.scan_output for production use',
+        });
+      }
+    }
+    stepTimings.dlp_out = Date.now() - stepStart;
+
+    // Extract usage data from response
+    const headerUsage = this.usageExtractor.extractFromHeaders(output.headers);
+    const bodyUsage = this.usageExtractor.extractFromBody(output.body);
+    const mergedUsage = this.usageExtractor.merge(headerUsage, bodyUsage);
+
+    // Compute actual cost from usage if available
+    let actualCostUsd: number | undefined;
+    if (mergedUsage) {
+      if (mergedUsage.provider_cost_usd !== undefined) {
+        actualCostUsd = mergedUsage.provider_cost_usd;
+      } else {
+        const effectiveToolCall = processedToolCall || toolCall;
+        const model = typeof effectiveToolCall.args.model === 'string' ? effectiveToolCall.args.model : undefined;
+        const computedCost = this.usageExtractor.computeCost(mergedUsage, model);
+        if (computedCost !== undefined) {
+          actualCostUsd = computedCost;
+          mergedUsage.computed_cost_usd = computedCost;
+        }
+      }
+    }
+
+    // Record cost (skip budget recording when budgetCheck is missing, e.g. passthrough)
+    const estimatedCost = budgetCheck?.report?.estimated_cost_usd ?? 0;
+    const recordedCost = actualCostUsd ?? estimatedCost;
+    const effectiveToolCall = processedToolCall || toolCall;
+    if (budgetCheck) {
+      // Commit the reservation with actual cost (releases difference between estimate and actual)
+      if (reservationKey) {
+        this.budgetManager.commitReservation(reservationKey, recordedCost);
+      }
+      // Record step count and cost record metadata.
+      // Skip cost increment when reservation already accounts for the cost.
+      const costRecord: CostRecord = {
+        estimated_cost_usd: estimatedCost,
+        actual_cost_usd: actualCostUsd,
+        usage: mergedUsage,
+      };
+      this.budgetManager.record(effectiveToolCall, costRecord, !!reservationKey);
+      await this.budgetManager.flush();
+    }
+
+    // Extract model info for LLM monitoring
+    const model = this.usageExtractor.extractModelFromBody(output.body)
+      || (typeof effectiveToolCall.args.model === 'string' ? effectiveToolCall.args.model : undefined);
+
+    if (model && mergedUsage) {
+      const provider = this.usageExtractor.detectProvider(model);
+      mergedUsage.model = model;
+      mergedUsage.provider = provider;
+
+      // Record LLM-specific metrics
+      if (this.metrics) {
+        this.metrics.recordLLMUsage({
+          model,
+          provider,
+          inputTokens: mergedUsage.input_tokens,
+          outputTokens: mergedUsage.output_tokens,
+          costUsd: actualCostUsd,
+          durationSeconds: (Date.now() - startTime) / 1000,
+          status: 'ok',
+        });
+      }
+    }
+
+    // Record cost and token usage metrics
+    if (this.metrics) {
+      this.metrics.recordCost(recordedCost, mergedUsage?.provider_cost_usd !== undefined ? 'provider' : actualCostUsd !== undefined ? 'computed' : 'estimated', toolCall.tool.name);
+      if (mergedUsage) {
+        if (mergedUsage.input_tokens !== undefined) {
+          this.metrics.recordTokenUsage('input', toolCall.tool.name, mergedUsage.input_tokens);
+        }
+        if (mergedUsage.output_tokens !== undefined) {
+          this.metrics.recordTokenUsage('output', toolCall.tool.name, mergedUsage.output_tokens);
+        }
+      }
+    }
+
+    // Merge DLP reports
+    const argsDlpSafe = argsDlp || { detected: [], redactions: [], severity: 'low' as DLPSeverity };
+    const mergedDlp = {
+      detected: [...new Set([...argsDlpSafe.detected, ...outputDlp.detected])],
+      redactions: [...argsDlpSafe.redactions, ...outputDlp.redactions],
+      severity: this.maxSeverity(argsDlpSafe.severity, outputDlp.severity),
+    };
+
+    // Build final result
+    const budgetReportWithActual = budgetCheck
+      ? this.budgetManager.getReportWithActual(effectiveToolCall, estimatedCost, actualCostUsd, mergedUsage)
+      : { estimated_cost_usd: 0, spent_cost_usd_task: 0, remaining_cost_usd_task: 0 };
+    const defaultPolicy = policyResult || { decision: 'allow' as const, rule_id: 'passthrough', rule_name: 'Passthrough', reasons: [] };
+    const result = this.buildResult(toolCall, 'ok', defaultPolicy, startTime, output, undefined, undefined, mergedDlp, budgetReportWithActual);
+    const auditMeta: Record<string, unknown> = { step_timings: stepTimings };
+    if (model) {
+      auditMeta.model = model;
+      auditMeta.provider = mergedUsage?.provider;
+      auditMeta.input_tokens = mergedUsage?.input_tokens;
+      auditMeta.output_tokens = mergedUsage?.output_tokens;
+      auditMeta.cost_usd = actualCostUsd;
+    }
+    this.auditLogger.logToolResultReturned(toolCall, 'ok', Date.now() - startTime, auditMeta);
+
+    // Record successful request metrics
+    const durationSec = (Date.now() - startTime) / 1000;
+    this.metrics?.recordRequest('ok', toolCall.tool.name, toolCall.tool.capability, durationSec);
+
+    devLog.pipelineEnd('ok', Date.now() - startTime);
+    return result;
+  }
+
+  // Main execution pipeline - implements the full runtime path
+  async execute(toolCall: ToolCall, requestingApiKeyId?: string): Promise<ToolResult> {
+    const otel = this.tracer?.getTracer();
+
+    // If no tracer or not enabled, run without spans
+    if (!otel) {
+      return this._executeInternal(toolCall, undefined, requestingApiKeyId);
+    }
+
+    return otel.startActiveSpan('gateway.execute', {
+      kind: SpanKind.SERVER,
+      attributes: {
+        'palaryn.tool_call_id': toolCall.tool_call_id,
+        'palaryn.task_id': toolCall.task_id,
+        'palaryn.tool': toolCall.tool.name,
+        'palaryn.capability': toolCall.tool.capability,
+        'palaryn.actor': toolCall.actor.id,
+        'palaryn.workspace': toolCall.workspace_id,
+      },
+    }, async (span) => {
+      try {
+        const result = await this._executeInternal(toolCall, otel, requestingApiKeyId);
+        span.setAttribute('palaryn.status', result.status);
+        span.setAttribute('palaryn.duration_ms', result.timing.duration_ms);
+        if (result.status === 'error') {
+          span.setStatus({ code: SpanStatusCode.ERROR, message: result.error });
+        } else {
+          span.setStatus({ code: SpanStatusCode.OK });
+        }
+        return result;
+      } catch (err) {
+        span.setStatus({ code: SpanStatusCode.ERROR, message: String(err) });
+        span.recordException(err as Error);
+        throw err;
+      } finally {
+        span.end();
+      }
+    });
+  }
+
+  // Internal pipeline with optional tracing — delegates to preExecute/postExecute
+  private async _executeInternal(toolCall: ToolCall, otel?: Tracer, requestingApiKeyId?: string): Promise<ToolResult> {
+    const startTime = Date.now();
+
+    // A2: Compute cache key using tool_call_id + body hash
+    const bodyHash = computeBodyHash(toolCall);
+    const cacheKey = `${toolCall.tool_call_id}:${bodyHash}`;
+
+    // Step 0: Idempotency check - return cached result for duplicate tool_call_id + body
+    const cached = await asyncChildSpan(otel, 'gateway.idempotency_check', async () => {
+      return this.idempotencyStore.get(cacheKey);
+    });
+    if (cached) {
+      this.metrics?.recordIdempotencyHit();
+      devLog.idempotencyHit(toolCall.tool_call_id);
+      devLog.pipelineEnd('ok (cached)', Date.now() - startTime);
+      return cached;
+    }
+    devLog.idempotencyMiss();
+
+    // Step 0.5: TOCTOU guard — if another request with the same cache key is already
+    // in flight, await its result instead of executing a duplicate.
+    const existingFlight = this.inFlightCalls.get(cacheKey);
+    if (existingFlight) {
+      devLog.idempotencyHit(toolCall.tool_call_id);
+      return existingFlight.promise;
+    }
+
+    // S6: Register this execution as in-flight via a deferred promise with timeout.
+    let resolveInFlight!: (result: ToolResult) => void;
+    let rejectInFlight!: (err: Error) => void;
+    const flightPromise = new Promise<ToolResult>((resolve, reject) => {
+      resolveInFlight = resolve;
+      rejectInFlight = reject;
+    });
+
+    const flightTimeout = setTimeout(() => {
+      rejectInFlight(new Error('In-flight request timed out after 60s'));
+      this.inFlightCalls.delete(cacheKey);
+    }, 60_000);
+
+    this.inFlightCalls.set(cacheKey, {
+      promise: flightPromise,
+      timeout: flightTimeout,
+      createdAt: Date.now(),
+    });
+
+    const executeAndResolve = async (): Promise<ToolResult> => {
+    // Run pre-execution pipeline (rate limit, anomaly, policy, DLP args, budget)
+    const pre = await this.preExecute(toolCall, otel, requestingApiKeyId);
+    if (!pre.allowed) {
+      // Release budget reservation if pre-execute denied after reservation
+      if (pre.reservationKey) {
+        this.budgetManager.releaseReservation(pre.reservationKey);
+      }
+      return pre.result!;
+    }
+
+    const { processedToolCall, policyResult, argsDlp, budgetCheck, reservationKey, stepTimings } = pre;
+
+    // Step 6: Execute tool via executor registry
+    devLog.executing(processedToolCall!.tool.name, processedToolCall!.args.url as string | undefined);
+    try {
+      let stepStart = Date.now();
+      const output = await asyncChildSpan(otel, 'gateway.tool_execute', () => {
+        return this.executorRegistry.execute(processedToolCall!);
+      });
+      stepTimings.execute = Date.now() - stepStart;
+
+      // Run post-execution pipeline (DLP output, usage, budget recording, metrics, audit)
+      const result = await this.postExecute(toolCall, output, pre, otel);
+
+      // Cache result for idempotency (5 minute TTL) using cache key with body hash
+      this.idempotencyStore.set(cacheKey, result, 300000);
+      if (this.idempotencyStore.flush) await this.idempotencyStore.flush();
+
+      return result;
+
+    } catch (err) {
+      // S5: Release budget reservation on execution error
+      if (reservationKey) {
+        this.budgetManager.releaseReservation(reservationKey);
+      }
+
+      const errorMsg = err instanceof Error ? err.message : String(err);
+      const errorType = err instanceof Error ? err.constructor.name : 'UnknownError';
+      const executionDuration = Date.now() - pre.startTime;
+      devLog.executionError(errorMsg);
+      this.auditLogger.logToolExecuted(toolCall, 'error', executionDuration);
+      this.auditLogger.logToolResultReturned(toolCall, 'error', executionDuration, { step_timings: stepTimings });
+
+      // Record result for anomaly detection (error tracking)
+      this.anomalyDetector?.recordResult(toolCall, executionDuration, true);
+      this.anomalyDetector?.analyzeResult(toolCall, executionDuration, true);
+
+      // Record error metrics
+      const durationSec = executionDuration / 1000;
+      this.metrics?.recordExecutorError(toolCall.tool.name, errorType);
+      this.metrics?.recordRequest('error', toolCall.tool.name, toolCall.tool.capability, durationSec);
+
+      const result = this.buildResult(toolCall, 'error', policyResult!, pre.startTime, undefined, errorMsg, undefined, argsDlp, budgetCheck!.report);
+      devLog.pipelineEnd('error', Date.now() - pre.startTime);
+      return result;
+    }
+    };
+
+    try {
+      const result = await executeAndResolve();
+      clearTimeout(flightTimeout);
+      resolveInFlight(result);
+      return result;
+    } catch (err) {
+      clearTimeout(flightTimeout);
+      // Even on unexpected errors, resolve the promise so waiters don't hang
+      const errorResult = this.buildResult(toolCall, 'error', {
+        decision: 'deny', rule_id: 'internal_error', rule_name: 'Internal error', reasons: [String(err)],
+      }, startTime, undefined, String(err));
+      resolveInFlight(errorResult);
+      throw err;
+    } finally {
+      this.inFlightCalls.delete(cacheKey);
+    }
+  }
+
+  // Process an approval token
+  async processApproval(token: string, approverId: string, approved: boolean, reason?: string, approverApiKeyId?: string): Promise<{ success: boolean; result?: ToolResult; error?: string }> {
+    try {
+      if (approved) {
+        const result = await this.approvalManager.approve(token, approverId, approverApiKeyId);
+        if (!result.approved) {
+          return { success: false, error: 'Approval failed or expired' };
+        }
+        return { success: true };
+      } else {
+        await this.approvalManager.deny(token, approverId, reason || 'Denied by approver');
+        return { success: true };
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : 'Approval processing failed';
+      return { success: false, error: message };
+    }
+  }
+
+  // Report usage from a client (e.g. Android reporting actual LLM costs)
+  reportUsage(params: {
+    tool_call_id: string;
+    task_id: string;
+    workspace_id?: string;
+    actor_id?: string;
+    actual_cost_usd?: number;
+    usage?: UsageData;
+  }): void {
+    // Log audit event
+    this.auditLogger.log({
+      event_type: 'USAGE_REPORTED',
+      tool_call_id: params.tool_call_id,
+      task_id: params.task_id,
+      workspace_id: params.workspace_id || 'unknown',
+      actor_id: params.actor_id || 'unknown',
+      tool_name: 'client_report',
+      metadata: {
+        actual_cost_usd: params.actual_cost_usd,
+        usage: params.usage,
+      },
+    });
+
+    // Record metrics
+    if (this.metrics) {
+      if (params.actual_cost_usd !== undefined) {
+        this.metrics.recordCost(params.actual_cost_usd, 'client_reported', 'client_report');
+      }
+      if (params.usage) {
+        if (params.usage.input_tokens !== undefined) {
+          this.metrics.recordTokenUsage('input', 'client_report', params.usage.input_tokens);
+        }
+        if (params.usage.output_tokens !== undefined) {
+          this.metrics.recordTokenUsage('output', 'client_report', params.usage.output_tokens);
+        }
+      }
+    }
+  }
+
+  // Get trace for a task
+  getTaskTrace(taskId: string) {
+    return this.auditLogger.getTaskTrace(taskId);
+  }
+
+  // Get current policy pack
+  getCurrentPolicy() {
+    return this.policyEngine.getPack();
+  }
+
+  // Validate a policy pack
+  validatePolicy(pack: PolicyPack) {
+    return PolicyEngine.validate(pack);
+  }
+
+  // Get pending approvals
+  getPendingApprovals(workspaceId?: string) {
+    return this.approvalManager.getPendingApprovals(workspaceId);
+  }
+
+  /** Reload the policy pack from disk. Creates a new engine and swaps atomically. */
+  reloadPolicy(): { success: boolean; ruleCount: number; error?: string } {
+    try {
+      // A3: Create new engine, load it, then swap the reference atomically
+      const newEngine = new PolicyEngine(
+        this.config.policy.pack_path,
+        this.config.policy.default_effect,
+      );
+      const pack = newEngine.getPack();
+      this.policyEngine = newEngine;
+      return { success: true, ruleCount: pack.rules.length };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return { success: false, ruleCount: 0, error: message };
+    }
+  }
+
+  /** Get the file path for the active policy pack */
+  getPolicyPackPath(): string {
+    return this.config.policy.pack_path;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Store injection — replace default in-memory stores with external backends
+  // ---------------------------------------------------------------------------
+
+  /** Replace the idempotency store (default: in-memory) */
+  setIdempotencyStore(store: IdempotencyStore): void {
+    this.idempotencyStore = store;
+  }
+
+  /** Replace the rate limiter with one backed by an external store */
+  setRateLimiter(limiter: RateLimiter): void {
+    this.rateLimiter = limiter;
+  }
+
+  /** Inject all external stores at once (e.g. from Redis or Postgres) */
+  setStores(stores: {
+    idempotencyStore?: IdempotencyStore;
+    rateLimitStore?: RateLimitStore;
+    auditStore?: AuditStore;
+    budgetStore?: BudgetStore;
+    approvalStore?: ApprovalStore;
+    policyStore?: PolicyStore;
+    rateLimitConfigStore?: RateLimitConfigStore;
+    budgetConfigStore?: BudgetConfigStore;
+  }): void {
+    if (stores.idempotencyStore) {
+      this.idempotencyStore = stores.idempotencyStore;
+    }
+    if (stores.rateLimitStore) {
+      this.rateLimiter = new RateLimiter(
+        this.config.rate_limit || DEFAULT_RATE_LIMIT,
+        stores.rateLimitStore,
+      );
+    }
+    if (stores.auditStore) {
+      this.auditLogger.setStore(stores.auditStore);
+    }
+    if (stores.budgetStore) {
+      this.budgetManager = new BudgetManager(this.config.budget, stores.budgetStore);
+    }
+    if (stores.approvalStore) {
+      this.approvalManager = new ApprovalManager(this.config.approval, stores.approvalStore);
+    }
+    if (stores.policyStore) {
+      this.policyStore = stores.policyStore;
+    }
+    if (stores.rateLimitConfigStore) {
+      this.rateLimitConfigStore = stores.rateLimitConfigStore;
+    }
+    if (stores.budgetConfigStore) {
+      this.budgetConfigStore = stores.budgetConfigStore;
+    }
+  }
+
+  // Get components for testing / introspection
+  getAuditLogger() { return this.auditLogger; }
+  getBudgetManager() { return this.budgetManager; }
+  getPolicyEngine() { return this.policyEngine; }
+  getDLPScanner() { return this.dlpScanner; }
+  getApprovalManager() { return this.approvalManager; }
+  getExecutorRegistry() { return this.executorRegistry; }
+  getHttpExecutor() { return this.httpExecutor; }
+  getRateLimiter() { return this.rateLimiter; }
+  getIdempotencyStore() { return this.idempotencyStore; }
+  getAnomalyDetector() { return this.anomalyDetector; }
+  getOPAEngine() { return this.opaEngine; }
+  getPolicyStore(): PolicyStore | undefined { return this.policyStore; }
+  getRateLimitConfigStore(): RateLimitConfigStore | undefined { return this.rateLimitConfigStore; }
+  getBudgetConfigStore(): BudgetConfigStore | undefined { return this.budgetConfigStore; }
+
+  /** Return the workspace-specific policy if one exists, otherwise the global policy. */
+  getWorkspacePolicy(workspaceId: string): { policy: PolicyPack; is_custom: boolean } {
+    if (this.policyStore) {
+      const custom = this.policyStore.getByWorkspaceId(workspaceId);
+      if (custom) return { policy: custom, is_custom: true };
+    }
+    return { policy: this.policyEngine.getPack(), is_custom: false };
+  }
+
+  /** Return workspace-specific rate limit config if one exists. */
+  getWorkspaceRateLimitConfig(workspaceId: string): import('../storage/interfaces').WorkspaceRateLimitConfig | undefined {
+    return this.rateLimitConfigStore?.getByWorkspaceId(workspaceId);
+  }
+
+  /** Return workspace-specific budget config if one exists. */
+  getWorkspaceBudgetConfig(workspaceId: string): import('../storage/interfaces').WorkspaceBudgetConfig | undefined {
+    return this.budgetConfigStore?.getByWorkspaceId(workspaceId);
+  }
+
+  // Helper: Build a ToolResult
+  private buildResult(
+    toolCall: ToolCall,
+    status: ToolResultStatus,
+    policyResult: PolicyEvalResult,
+    startTime: number,
+    output?: any,
+    error?: string,
+    approvalInfo?: any,
+    dlpReport?: any,
+    budgetReport?: any,
+  ): ToolResult {
+    const result: ToolResult = {
+      tool_call_id: toolCall.tool_call_id,
+      task_id: toolCall.task_id,
+      status,
+      policy: {
+        decision: policyResult.decision,
+        rule_id: policyResult.rule_id,
+        reasons: policyResult.reasons,
+      },
+      dlp: dlpReport || { detected: [], redactions: [], severity: 'low' },
+      budget: budgetReport || { estimated_cost_usd: 0, spent_cost_usd_task: 0, remaining_cost_usd_task: 0 },
+      output: output || undefined,
+      error: error || undefined,
+      timing: {
+        started_at: new Date(startTime).toISOString(),
+        duration_ms: Date.now() - startTime,
+      },
+    };
+
+    if (approvalInfo) {
+      (result as any).approval = approvalInfo;
+    }
+
+    return result;
+  }
+
+  // Helper: Apply policy transformations to a ToolCall
+  private applyTransformations(toolCall: ToolCall, transformations: PolicyTransformation[]): ToolCall {
+    const clone: ToolCall = JSON.parse(JSON.stringify(toolCall));
+    for (const t of transformations) {
+      switch (t.type) {
+        case 'strip_header':
+          if (clone.args.headers) {
+            delete clone.args.headers[t.target];
+          }
+          break;
+        case 'redact_field':
+          this.setNestedValue(clone.args, t.target, '[REDACTED]');
+          break;
+        case 'replace_value':
+          this.setNestedValue(clone.args, t.target, t.value || '');
+          break;
+      }
+    }
+    return clone;
+  }
+
+  // Helper: Set a nested value using dot notation
+  private setNestedValue(obj: any, path: string, value: any): void {
+    const parts = path.split('.');
+    let current = obj;
+    for (let i = 0; i < parts.length - 1; i++) {
+      if (current[parts[i]] === undefined) return;
+      current = current[parts[i]];
+    }
+    current[parts[parts.length - 1]] = value;
+  }
+
+  // Helper: Classify budget block reason into a metric label
+  private classifyBudgetReason(reason: string): string {
+    if (reason.startsWith('Task budget')) return 'task';
+    if (reason.startsWith('User daily')) return 'user_daily';
+    if (reason.startsWith('User monthly')) return 'user_monthly';
+    if (reason.startsWith('Workspace daily')) return 'workspace_daily';
+    if (reason.startsWith('Workspace monthly')) return 'workspace_monthly';
+    if (reason.startsWith('Step limit')) return 'step_limit';
+    if (reason.startsWith('Wall clock')) return 'wall_clock';
+    return 'unknown';
+  }
+
+  // Helper: Get max severity
+  private maxSeverity(a: string, b: string): DLPSeverity {
+    const order: Record<string, number> = { low: 0, medium: 1, high: 2 };
+    const aVal = order[a] || 0;
+    const bVal = order[b] || 0;
+    return aVal >= bVal ? a as DLPSeverity : b as DLPSeverity;
+  }
+
+  private _shuttingDown = false;
+
+  /** Returns true if the gateway is in the process of shutting down. */
+  get isShuttingDown(): boolean {
+    return this._shuttingDown;
+  }
+
+  // Shutdown — flush pending writes, close logger, clear caches, reset limiter
+  async shutdown(): Promise<void> {
+    this._shuttingDown = true;
+
+    // Clear the in-flight cleanup interval
+    if (this.inFlightCleanupInterval) {
+      clearInterval(this.inFlightCleanupInterval);
+      this.inFlightCleanupInterval = undefined;
+    }
+
+    // Clear in-flight call timeouts
+    for (const [key, entry] of this.inFlightCalls) {
+      clearTimeout(entry.timeout);
+    }
+    this.inFlightCalls.clear();
+
+    // 1. Flush all pending async writes to storage backends
+    // Use Promise.all so errors propagate to the caller instead of being silently swallowed
+    const flushes: Promise<void>[] = [];
+    if (this.budgetManager.flush) flushes.push(this.budgetManager.flush());
+    if (this.approvalManager.flush) flushes.push(this.approvalManager.flush());
+    if (this.idempotencyStore.flush) flushes.push(this.idempotencyStore.flush());
+    if (this.rateLimiter.flush) flushes.push(this.rateLimiter.flush());
+    if (flushes.length > 0) {
+      await Promise.all(flushes);
+    }
+
+    // 2. Flush audit logger pending writes, then close file handles
+    await this.auditLogger.flush();
+    this.auditLogger.close();
+
+    // 3. Clear caches and reset limiter
+    this.idempotencyStore.clear();
+    this.rateLimiter.reset();
+  }
+}