@vellumai/assistant 0.7.0 → 0.7.1

package/src/oauth/connection-resolver.test.ts

@@ -39,6 +39,14 @@ mock.module("../security/secure-keys.js", () => ({
   getSecureKeyAsync: async () => mockAccessToken,
 }));
 
+mock.module("./credential-token-resolver.js", () => ({
+  getConnectionAccessTokenResult: async () => ({
+    value: mockAccessToken,
+    unreachable: false,
+    key: "mock-key",
+  }),
+}));
+
 mock.module("../config/loader.js", () => ({
   getConfig: () => mockConfig,
 }));

package/src/oauth/connection-resolver.ts

@@ -1,15 +1,14 @@
-import { getIsPlatform } from "../config/env-registry.js";
-import { getConfig, getNestedValue, loadRawConfig } from "../config/loader.js";
+import { getConfig } from "../config/loader.js";
 import {
   getServiceMode,
   type Services,
   ServicesSchema,
 } from "../config/schemas/services.js";
 import { VellumPlatformClient } from "../platform/client.js";
-import { getSecureKeyAsync } from "../security/secure-keys.js";
 import { getLogger } from "../util/logger.js";
 import { BYOOAuthConnection } from "./byo-connection.js";
 import type { OAuthConnection } from "./connection.js";
+import { getConnectionAccessTokenResult } from "./credential-token-resolver.js";
 import { getActiveConnection, getProvider } from "./oauth-store.js";
 import { PlatformOAuthConnection } from "./platform-connection.js";
 
@@ -52,15 +51,7 @@ export async function resolveOAuthConnection(
 
   if (managedKey && managedKey in ServicesSchema.shape) {
     const services: Services = getConfig().services;
-    const explicitMode = getServiceMode(services, managedKey as keyof Services);
-    // Treat as managed when explicitly configured OR when on a platform
-    // instance and the user hasn't explicitly opted into "your-own".
-    const effectivelyManaged =
-      explicitMode === "managed" ||
-      (getIsPlatform() &&
-        getNestedValue(loadRawConfig(), `services.${managedKey}.mode`) ===
-          undefined);
-    if (effectivelyManaged) {
+    if (getServiceMode(services, managedKey as keyof Services) === "managed") {
       const client = await VellumPlatformClient.create();
       if (!client || !client.platformAssistantId) {
         const detail = !client
@@ -105,10 +96,11 @@ export async function resolveOAuthConnection(
     );
   }
 
-  const accessToken = await getSecureKeyAsync(
-    `oauth_connection/${conn.id}/access_token`,
-  );
-  if (!accessToken) {
+  const tokenResult = await getConnectionAccessTokenResult({
+    provider,
+    connectionId: conn.id,
+  });
+  if (!tokenResult.value) {
     throw new Error(
       `OAuth connection for "${provider}" exists but has no access token. Re-authorize with \`assistant oauth connect ${provider}\`.`,
     );

package/src/oauth/credential-token-resolver.ts

@@ -0,0 +1,97 @@
+/**
+ * Centralized access-token key resolution for OAuth and manual-token providers.
+ *
+ * All code that needs to read or check the presence of a provider's access
+ * token should go through {@link getConnectionAccessTokenResult} rather than
+ * inlining provider-specific path logic. This ensures that `oauth status`,
+ * `oauth ping`, credential health checks, and runtime token lookups all
+ * agree on where the access token lives.
+ *
+ * Manual-token providers (e.g. slack_channel, telegram) store their primary
+ * token under `credential/<provider>/<field>` via the generic credential
+ * store, while standard OAuth providers use `oauth_connection/<id>/access_token`.
+ */
+
+import { oauthConnectionAccessTokenPath } from "@vellumai/credential-storage";
+
+import { credentialKey } from "../security/credential-key.js";
+import {
+  getSecureKeyResultAsync,
+  type SecureKeyResult,
+} from "../security/secure-keys.js";
+
+// ── Types ─────────────────────────────────────────────────────────────
+
+export interface ConnectionAccessTokenResult {
+  /** The access token value, or undefined if not found / backend unreachable. */
+  value: string | undefined;
+  /** True when the credential backend is temporarily unreachable. */
+  unreachable: boolean;
+  /** The secure-store key that was resolved for this provider + connection. */
+  key: string;
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────
+
+/**
+ * Return the secure-store key holding the primary access token for a
+ * manual-token provider, or null for OAuth providers whose tokens live at
+ * `oauth_connection/<id>/access_token`.
+ *
+ * Manual-token providers store their tokens under `credential/<provider>/<field>`
+ * via the generic credential store, so any code that validates tokens for these
+ * providers (e.g. credential-health checks) must resolve the path through here
+ * rather than assuming the OAuth access-token path.
+ */
+export function manualTokenAccessCredentialKey(
+  provider: string,
+): string | null {
+  switch (provider) {
+    case "slack_channel":
+      return credentialKey("slack_channel", "bot_token");
+    case "telegram":
+      return credentialKey("telegram", "bot_token");
+    default:
+      return null;
+  }
+}
+
+/**
+ * Resolve the secure-store key for a provider's access token.
+ *
+ * - `slack_channel` -> `credential/slack_channel/bot_token`
+ * - `telegram`      -> `credential/telegram/bot_token`
+ * - all normal OAuth -> `oauth_connection/<connectionId>/access_token`
+ */
+export function resolveAccessTokenKey(
+  provider: string,
+  connectionId: string,
+): string {
+  return (
+    manualTokenAccessCredentialKey(provider) ??
+    oauthConnectionAccessTokenPath(connectionId)
+  );
+}
+
+// ── Public API ───────────────────────────────────────────────────────
+
+/**
+ * Look up the access token for a provider/connection pair, resolving the
+ * correct secure-store key automatically.
+ *
+ * Returns the token value, whether the backend was unreachable, and the
+ * key that was used — giving callers everything they need to diagnose
+ * token-path mismatches.
+ */
+export async function getConnectionAccessTokenResult(opts: {
+  provider: string;
+  connectionId: string;
+}): Promise<ConnectionAccessTokenResult> {
+  const key = resolveAccessTokenKey(opts.provider, opts.connectionId);
+  const result: SecureKeyResult = await getSecureKeyResultAsync(key);
+  return {
+    value: result.value,
+    unreachable: result.unreachable,
+    key,
+  };
+}

package/src/oauth/manual-token-connection.ts

@@ -9,7 +9,8 @@
  */
 
 import { credentialKey } from "../security/credential-key.js";
-import { getSecureKeyAsync } from "../security/secure-keys.js";
+import { getSecureKeyResultAsync } from "../security/secure-keys.js";
+import { getLogger } from "../util/logger.js";
 import {
   createConnection,
   deleteConnection,
@@ -18,32 +19,15 @@ import {
   upsertApp,
 } from "./oauth-store.js";
 
+// Re-export from the centralized resolver so existing callers that import
+// from this module continue to work without changes.
+export { manualTokenAccessCredentialKey } from "./credential-token-resolver.js";
+
+const log = getLogger("manual-token-connection");
+
 /** Sentinel client_id used for non-OAuth providers that don't have a real app. */
 const MANUAL_TOKEN_CLIENT_ID = "manual-config";
 
-/**
- * Return the secure-store key holding the primary access token for a
- * manual-token provider, or null for OAuth providers whose tokens live at
- * `oauth_connection/<id>/access_token`.
- *
- * Manual-token providers store their tokens under `credential/<provider>/<field>`
- * via the generic credential store, so any code that validates tokens for these
- * providers (e.g. credential-health checks) must resolve the path through here
- * rather than assuming the OAuth access-token path.
- */
-export function manualTokenAccessCredentialKey(
-  provider: string,
-): string | null {
-  switch (provider) {
-    case "slack_channel":
-      return credentialKey("slack_channel", "bot_token");
-    case "telegram":
-      return credentialKey("telegram", "bot_token");
-    default:
-      return null;
-  }
-}
-
 /**
  * Ensure an active oauth_connection row exists for the given manual-token
  * provider. Creates the synthetic oauth_app row on first use.
@@ -101,13 +85,19 @@ export async function syncManualTokenConnection(
 ): Promise<void> {
   switch (provider) {
     case "telegram": {
-      const hasBotToken = !!(await getSecureKeyAsync(
+      const botTokenResult = await getSecureKeyResultAsync(
         credentialKey("telegram", "bot_token"),
-      ));
-      const hasWebhookSecret = !!(await getSecureKeyAsync(
+      );
+      const webhookSecretResult = await getSecureKeyResultAsync(
         credentialKey("telegram", "webhook_secret"),
-      ));
-      if (hasBotToken && hasWebhookSecret) {
+      );
+      if (botTokenResult.unreachable || webhookSecretResult.unreachable) {
+        log.warn(
+          "Skipping telegram manual-token reconciliation — credential backend unreachable",
+        );
+        return;
+      }
+      if (botTokenResult.value && webhookSecretResult.value) {
         await ensureManualTokenConnection(provider, accountInfo);
       } else {
         removeManualTokenConnection(provider);
@@ -116,13 +106,19 @@ export async function syncManualTokenConnection(
     }
 
     case "slack_channel": {
-      const hasBotToken = !!(await getSecureKeyAsync(
+      const botTokenResult = await getSecureKeyResultAsync(
         credentialKey("slack_channel", "bot_token"),
-      ));
-      const hasAppToken = !!(await getSecureKeyAsync(
+      );
+      const appTokenResult = await getSecureKeyResultAsync(
         credentialKey("slack_channel", "app_token"),
-      ));
-      if (hasBotToken && hasAppToken) {
+      );
+      if (botTokenResult.unreachable || appTokenResult.unreachable) {
+        log.warn(
+          "Skipping slack_channel manual-token reconciliation — credential backend unreachable",
+        );
+        return;
+      }
+      if (botTokenResult.value && appTokenResult.value) {
         await ensureManualTokenConnection(provider, accountInfo);
       } else {
         removeManualTokenConnection(provider);

package/src/oauth/oauth-store.ts

@@ -33,6 +33,7 @@ import {
 } from "../security/secure-keys.js";
 import { getLogger } from "../util/logger.js";
 import type { AvailableScopes } from "./connect-types.js";
+import { getConnectionAccessTokenResult } from "./credential-token-resolver.js";
 import { tryRevokeOAuthToken } from "./revoke.js";
 
 const log = getLogger("oauth-store");
@@ -895,10 +896,11 @@ export function listActiveConnectionsByProvider(
 export async function isProviderConnected(provider: string): Promise<boolean> {
   const conn = getActiveConnection(provider);
   if (!conn || conn.status !== "active") return false;
-  return (
-    (await getSecureKeyAsync(oauthConnectionAccessTokenPath(conn.id))) !==
-    undefined
-  );
+  const tokenResult = await getConnectionAccessTokenResult({
+    provider,
+    connectionId: conn.id,
+  });
+  return tokenResult.value !== undefined;
 }
 
 /**

package/src/outbound-proxy/certs.ts

@@ -269,13 +269,6 @@ export async function ensureCombinedCABundle(
   }
 }
 
-/**
- * Return the path to the combined CA bundle for use as SSL_CERT_FILE.
- */
-export function getCombinedCAPath(dataDir: string): string {
-  return join(dataDir, "proxy-ca", COMBINED_CA_FILENAME);
-}
-
 /**
  * Return the path to the local CA cert for use as NODE_EXTRA_CA_CERTS.
  */

package/src/outbound-proxy/config.ts

@@ -18,77 +18,3 @@ export interface SidecarConfig {
   /** Log level for the sidecar process. */
   logLevel: "debug" | "info" | "warn" | "error";
 }
-
-/**
- * Parse and validate sidecar configuration from environment variables.
- *
- * Environment variables:
- *   PROXY_PORT            - Port to listen on (default: 8080)
- *   PROXY_HOST            - Host to bind to (default: "0.0.0.0")
- *   PROXY_HEALTH_PORT     - Port for health/readiness endpoints (default: 8081)
- *   PROXY_CA_DIR          - Path to CA directory for MITM (optional)
- *   PROXY_LOG_LEVEL       - Log level: debug | info | warn | error (default: "info")
- */
-export function loadConfig(
-  env: Record<string, string | undefined> = process.env,
-): SidecarConfig {
-  const port = parsePort(env.PROXY_PORT, "PROXY_PORT");
-  const defaultHealthPort = port === 8081 ? 8082 : 8081;
-  const healthPort = parsePort(
-    env.PROXY_HEALTH_PORT,
-    "PROXY_HEALTH_PORT",
-    defaultHealthPort,
-  );
-  if (healthPort === port) {
-    throw new ConfigError(
-      `PROXY_HEALTH_PORT (${healthPort}) must differ from PROXY_PORT (${port})`,
-    );
-  }
-  const host = env.PROXY_HOST ?? "0.0.0.0";
-  const caDir = env.PROXY_CA_DIR ?? null;
-  const logLevel = parseLogLevel(env.PROXY_LOG_LEVEL);
-
-  return { port, host, healthPort, caDir, logLevel };
-}
-
-function parsePort(
-  raw: string | undefined,
-  envName: string = "PROXY_PORT",
-  defaultPort: number = 8080,
-): number {
-  if (raw === undefined || raw === "") return defaultPort;
-
-  const port = Number(raw);
-  if (!Number.isInteger(port) || port < 1 || port > 65535) {
-    throw new ConfigError(
-      `${envName} must be an integer between 1 and 65535, got "${raw}"`,
-    );
-  }
-  return port;
-}
-
-const VALID_LOG_LEVELS = new Set(["debug", "info", "warn", "error"] as const);
-type LogLevel = "debug" | "info" | "warn" | "error";
-
-function parseLogLevel(raw: string | undefined): LogLevel {
-  if (raw === undefined || raw === "") return "info";
-
-  const lower = raw.toLowerCase();
-  if (!VALID_LOG_LEVELS.has(lower as LogLevel)) {
-    throw new ConfigError(
-      `PROXY_LOG_LEVEL must be one of debug, info, warn, error — got "${raw}"`,
-    );
-  }
-  return lower as LogLevel;
-}
-
-/**
- * Dedicated error class for configuration validation failures.
- * The entrypoint catches this to print a clean message without a stack trace.
- */
-export class ConfigError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = "ConfigError";
-  }
-}

package/src/outbound-proxy/health.ts

@@ -9,8 +9,6 @@
  * All other paths return 404. Non-GET methods return 405.
  */
 
-import { createServer, type Server } from "node:http";
-
 export interface HealthServerOptions {
   /**
    * Callback that returns `true` when the proxy server is ready to accept
@@ -18,45 +16,3 @@ export interface HealthServerOptions {
    */
   isReady: () => boolean;
 }
-
-/**
- * Create an HTTP server that serves health and readiness endpoints.
- *
- * The returned server is not yet listening -- the caller is responsible for
- * calling `.listen()`.
- */
-export function createHealthServer(options: HealthServerOptions): Server {
-  const { isReady } = options;
-
-  const server = createServer((req, res) => {
-    // Only support GET requests
-    if (req.method !== "GET") {
-      res.writeHead(405, { "Content-Type": "text/plain", Allow: "GET" });
-      res.end("Method Not Allowed\n");
-      return;
-    }
-
-    switch (req.url) {
-      case "/healthz": {
-        res.writeHead(200, { "Content-Type": "application/json" });
-        res.end(JSON.stringify({ status: "ok" }));
-        return;
-      }
-
-      case "/readyz": {
-        const ready = isReady();
-        const statusCode = ready ? 200 : 503;
-        res.writeHead(statusCode, { "Content-Type": "application/json" });
-        res.end(JSON.stringify({ status: ready ? "ready" : "not_ready" }));
-        return;
-      }
-
-      default: {
-        res.writeHead(404, { "Content-Type": "text/plain" });
-        res.end("Not Found\n");
-      }
-    }
-  });
-
-  return server;
-}

package/src/outbound-proxy/index.ts

@@ -27,19 +27,6 @@ export type {
 // ---------------------------------------------------------------------------
 
 export type { ManagedSession, SessionStartHooks } from "@vellumai/egress-proxy";
-export {
-  cloneSession,
-  createSession,
-  credentialIdsMatch,
-  getActiveSession,
-  getOrStartSession,
-  getSessionEnv,
-  getSessionsForConversation,
-  SessionStore,
-  startSession,
-  stopAllSessions,
-  stopSession,
-} from "@vellumai/egress-proxy";
 
 // ---------------------------------------------------------------------------
 // Host pattern matching
@@ -49,36 +36,28 @@ export type {
   HostMatchKind,
   MatchHostPatternOptions,
 } from "./host-pattern-match.js";
-export {
-  compareMatchSpecificity,
-  matchHostPattern,
-} from "./host-pattern-match.js";
 
 // Certificate management
 export {
   ensureCombinedCABundle,
   ensureLocalCA,
   getCAPath,
-  getCombinedCAPath,
   issueLeafCert,
 } from "./certs.js";
 
 // MITM handler
 export type { RewriteCallback } from "./mitm-handler.js";
-export { handleMitm } from "./mitm-handler.js";
 
 // Router
 export type { RouteDecision, RouteReason } from "./router.js";
 export { routeConnection } from "./router.js";
 
 // CONNECT tunnel
-export { handleConnect } from "./connect-tunnel.js";
 
 // Policy engine
 export { evaluateRequest, evaluateRequestWithApproval } from "./policy.js";
 
 // HTTP forwarder
-export { forwardHttpRequest } from "./http-forwarder.js";
 
 // Proxy server
 export type { MitmHandlerConfig, ProxyServerConfig } from "./server.js";
@@ -89,7 +68,6 @@ export type { SidecarConfig } from "./config.js";
 
 // Health / readiness server
 export type { HealthServerOptions } from "./health.js";
-export { createHealthServer } from "./health.js";
 
 // Logging/diagnostics
 export type { CredentialRefTrace, ProxyDecisionTrace } from "./logging.js";

package/src/permissions/approval-provenance.test.ts

@@ -0,0 +1,184 @@
+import { describe, expect, test } from "bun:test";
+
+import { mapApprovalProvenance } from "./approval-provenance.js";
+import type { ApprovalMode, RiskThreshold } from "./types.js";
+import { RISK_ORDINAL, THRESHOLD_ORDINAL } from "./types.js";
+
+// ── mapApprovalProvenance — one test per row of the decision mapping table ────
+
+describe("mapApprovalProvenance", () => {
+  test("platform_auto_approve → auto / platform_auto_approve", () => {
+    const r = mapApprovalProvenance("platform_auto_approve", {});
+    expect(r.approvalMode).toBe("auto");
+    expect(r.approvalReason).toBe("platform_auto_approve");
+  });
+
+  test("guardian_auto_approve → auto / within_threshold", () => {
+    const r = mapApprovalProvenance("guardian_auto_approve", {});
+    expect(r.approvalMode).toBe("auto");
+    expect(r.approvalReason).toBe("within_threshold");
+  });
+
+  test("allow + sandbox → auto / sandbox_auto_approve", () => {
+    const r = mapApprovalProvenance("allow", { hasSandboxAutoApprove: true });
+    expect(r.approvalMode).toBe("auto");
+    expect(r.approvalReason).toBe("sandbox_auto_approve");
+  });
+
+  test("allow + trust rule → auto / trust_rule_allowed", () => {
+    const r = mapApprovalProvenance("allow", { matchedTrustRuleId: "rule-abc" });
+    expect(r.approvalMode).toBe("auto");
+    expect(r.approvalReason).toBe("trust_rule_allowed");
+  });
+
+  test("allow (no trust rule, no sandbox) → auto / within_threshold", () => {
+    const r = mapApprovalProvenance("allow", {});
+    expect(r.approvalMode).toBe("auto");
+    expect(r.approvalReason).toBe("within_threshold");
+  });
+
+  test("allow + wasPrompted → prompted / user_approved", () => {
+    const r = mapApprovalProvenance("allow", { wasPrompted: true });
+    expect(r.approvalMode).toBe("prompted");
+    expect(r.approvalReason).toBe("user_approved");
+  });
+
+  test("deny (user pressed deny) → prompted / user_denied", () => {
+    const r = mapApprovalProvenance("deny", {});
+    expect(r.approvalMode).toBe("prompted");
+    expect(r.approvalReason).toBe("user_denied");
+  });
+
+  test("deny + wasTimeout → prompted / timed_out", () => {
+    const r = mapApprovalProvenance("deny", { wasTimeout: true });
+    expect(r.approvalMode).toBe("prompted");
+    expect(r.approvalReason).toBe("timed_out");
+  });
+
+  test("deny + wasSystemCancel → prompted / system_cancelled", () => {
+    const r = mapApprovalProvenance("deny", { wasSystemCancel: true });
+    expect(r.approvalMode).toBe("prompted");
+    expect(r.approvalReason).toBe("system_cancelled");
+  });
+
+  test("wasSystemCancel takes priority over wasTimeout", () => {
+    const r = mapApprovalProvenance("deny", { wasSystemCancel: true, wasTimeout: true });
+    expect(r.approvalReason).toBe("system_cancelled");
+  });
+
+  test("denied + matchedTrustRuleId → blocked / trust_rule_denied", () => {
+    const r = mapApprovalProvenance("denied", { matchedTrustRuleId: "rule-abc" });
+    expect(r.approvalMode).toBe("blocked");
+    expect(r.approvalReason).toBe("trust_rule_denied");
+  });
+
+  test("denied (no matchedTrustRuleId) → blocked / no_interactive_client", () => {
+    const r = mapApprovalProvenance("denied", {});
+    expect(r.approvalMode).toBe("blocked");
+    expect(r.approvalReason).toBe("no_interactive_client");
+  });
+
+  test("unknown decision → unknown / unknown", () => {
+    const r = mapApprovalProvenance("something_unexpected", {});
+    expect(r.approvalMode).toBe("unknown");
+    expect(r.approvalReason).toBe("unknown");
+  });
+
+  test("sandbox takes priority over trust rule when both present", () => {
+    const r = mapApprovalProvenance("allow", {
+      hasSandboxAutoApprove: true,
+      matchedTrustRuleId: "rule-xyz",
+    });
+    expect(r.approvalReason).toBe("sandbox_auto_approve");
+  });
+
+  test("wasPrompted takes priority over sandbox when both set", () => {
+    const r = mapApprovalProvenance("allow", {
+      wasPrompted: true,
+      hasSandboxAutoApprove: true,
+    });
+    expect(r.approvalMode).toBe("prompted");
+    expect(r.approvalReason).toBe("user_approved");
+  });
+});
+
+// ── RISK_ORDINAL — unknown riskLevel must not map to a safe value ─────────────
+
+describe("RISK_ORDINAL semantics", () => {
+  test("known risk levels have expected ordinals", () => {
+    expect(RISK_ORDINAL["low"]).toBe(0);
+    expect(RISK_ORDINAL["medium"]).toBe(1);
+    expect(RISK_ORDINAL["high"]).toBe(2);
+  });
+
+  test("unknown riskLevel is absent so callers fall through to ?? 2 (high)", () => {
+    expect(RISK_ORDINAL["unknown"]).toBeUndefined();
+  });
+});
+
+// ── wasExpected derivation — all combinations ─────────────────────────────────
+
+function wasExpected(
+  approvalMode: ApprovalMode,
+  riskLevel: string,
+  riskThreshold: RiskThreshold,
+): boolean {
+  if (approvalMode !== "auto") return true;
+  return RISK_ORDINAL[riskLevel] <= THRESHOLD_ORDINAL[riskThreshold];
+}
+
+describe("wasExpected derivation", () => {
+  test("prompted outcomes are always expected", () => {
+    expect(wasExpected("prompted", "high", "none")).toBe(true);
+    expect(wasExpected("prompted", "high", "low")).toBe(true);
+  });
+
+  test("blocked outcomes are always expected", () => {
+    expect(wasExpected("blocked", "high", "none")).toBe(true);
+    expect(wasExpected("blocked", "medium", "low")).toBe(true);
+  });
+
+  test("unknown (legacy) outcomes are always expected", () => {
+    expect(wasExpected("unknown", "high", "none")).toBe(true);
+  });
+
+  test("auto: risk within threshold → expected", () => {
+    expect(wasExpected("auto", "low", "low")).toBe(true);
+    expect(wasExpected("auto", "low", "medium")).toBe(true);
+    expect(wasExpected("auto", "medium", "medium")).toBe(true);
+    expect(wasExpected("auto", "high", "high")).toBe(true);
+  });
+
+  test("auto: risk above threshold → unexpected", () => {
+    expect(wasExpected("auto", "high", "low")).toBe(false);
+    expect(wasExpected("auto", "high", "medium")).toBe(false);
+    expect(wasExpected("auto", "medium", "low")).toBe(false);
+    expect(wasExpected("auto", "high", "none")).toBe(false);
+    expect(wasExpected("auto", "medium", "none")).toBe(false);
+    expect(wasExpected("auto", "low", "none")).toBe(false);
+  });
+});
+
+// ── Invariant: new records must not emit approvalMode: "unknown" ──────────────
+
+describe("approvalMode unknown invariant", () => {
+  const knownDecisions = [
+    "allow",
+    "deny",
+    "denied",
+    "platform_auto_approve",
+    "guardian_auto_approve",
+  ];
+
+  test("every known decision produces a non-unknown approvalMode", () => {
+    for (const decision of knownDecisions) {
+      const r = mapApprovalProvenance(decision, {});
+      expect(r.approvalMode).not.toBe("unknown");
+    }
+  });
+
+  test("only unrecognised decision strings emit unknown", () => {
+    const r = mapApprovalProvenance("__legacy_unknown__", {});
+    expect(r.approvalMode).toBe("unknown");
+  });
+});