feat(providers): add fail-closed env config guardrails

Adds src/ai/providers/env.ts with readProviderEnvConfig() that validates
CE_AI_PROVIDER, CE_AI_ENABLE_EXPERIMENTAL_PROVIDERS, CE_AI_ENABLE_SHADOW,
and CE_AI_ENABLE_CANARY independently. Non-openai_session providers,
shadow mode, and canary routing all require the experimental gate to be
enabled separately, so CE_AI_PROVIDER alone cannot activate them.

Pure module -- not yet wired into factory.ts. Parity fence remains green.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: Kirachon

src/ai/providers/env.ts

@@ -0,0 +1,72 @@
+/**
+ * Fail-closed environment configuration for the multi-provider framework.
+ *
+ * Pure module: no I/O, no mutation of the input env. Other slices will consume
+ * this to decide which provider to construct and whether shadow/canary lanes
+ * are eligible. CE_AI_PROVIDER alone is intentionally insufficient to activate
+ * any experimental behavior; the experimental gate must be set independently.
+ */
+
+const DEFAULT_PROVIDER_ID = 'openai_session';
+const EXPERIMENTAL_FLAG = 'CE_AI_ENABLE_EXPERIMENTAL_PROVIDERS';
+const SHADOW_FLAG = 'CE_AI_ENABLE_SHADOW';
+const CANARY_FLAG = 'CE_AI_ENABLE_CANARY';
+const PROVIDER_KEY = 'CE_AI_PROVIDER';
+
+export interface ProviderEnvConfig {
+  readonly providerId: 'openai_session' | string;
+  readonly experimentalEnabled: boolean;
+  readonly shadowEnabled: boolean;
+  readonly canaryEnabled: boolean;
+}
+
+function readTrimmed(env: NodeJS.ProcessEnv, key: string): string | undefined {
+  const raw = env[key];
+  if (typeof raw !== 'string') return undefined;
+  const trimmed = raw.trim();
+  return trimmed.length === 0 ? undefined : trimmed;
+}
+
+function readBool(env: NodeJS.ProcessEnv, key: string): boolean {
+  const v = readTrimmed(env, key);
+  if (v === undefined) return false;
+  const lower = v.toLowerCase();
+  return lower === '1' || lower === 'true';
+}
+
+export function readProviderEnvConfig(env: NodeJS.ProcessEnv = process.env): ProviderEnvConfig {
+  const experimentalEnabled = readBool(env, EXPERIMENTAL_FLAG);
+
+  const rawProvider = readTrimmed(env, PROVIDER_KEY);
+  const providerId = rawProvider ?? DEFAULT_PROVIDER_ID;
+
+  if (providerId !== DEFAULT_PROVIDER_ID && !experimentalEnabled) {
+    throw new Error(
+      `Provider '${providerId}' requires ${EXPERIMENTAL_FLAG}=1 to be enabled. ` +
+        `CE_AI_PROVIDER alone cannot activate non-${DEFAULT_PROVIDER_ID} providers.`,
+    );
+  }
+
+  const shadowRequested = readBool(env, SHADOW_FLAG);
+  if (shadowRequested && !experimentalEnabled) {
+    throw new Error(
+      `${SHADOW_FLAG} requires ${EXPERIMENTAL_FLAG}=1 to be enabled separately.`,
+    );
+  }
+  const shadowEnabled = shadowRequested && experimentalEnabled;
+
+  const canaryRequested = readBool(env, CANARY_FLAG);
+  if (canaryRequested && !experimentalEnabled) {
+    throw new Error(
+      `${CANARY_FLAG} requires ${EXPERIMENTAL_FLAG}=1 to be enabled separately.`,
+    );
+  }
+  const canaryEnabled = canaryRequested && experimentalEnabled;
+
+  return Object.freeze({
+    providerId,
+    experimentalEnabled,
+    shadowEnabled,
+    canaryEnabled,
+  });
+}

tests/ai/providers/env.test.ts

@@ -0,0 +1,132 @@
+import { describe, it, expect } from '@jest/globals';
+import { readProviderEnvConfig } from '../../../src/ai/providers/env.js';
+
+describe('readProviderEnvConfig', () => {
+  it('returns defaults when env is empty', () => {
+    const cfg = readProviderEnvConfig({});
+    expect(cfg.providerId).toBe('openai_session');
+    expect(cfg.experimentalEnabled).toBe(false);
+    expect(cfg.shadowEnabled).toBe(false);
+    expect(cfg.canaryEnabled).toBe(false);
+  });
+
+  it('treats explicit openai_session as default-safe', () => {
+    const cfg = readProviderEnvConfig({ CE_AI_PROVIDER: 'openai_session' });
+    expect(cfg.providerId).toBe('openai_session');
+    expect(cfg.experimentalEnabled).toBe(false);
+  });
+
+  it('treats whitespace-only CE_AI_PROVIDER as unset', () => {
+    const cfg = readProviderEnvConfig({ CE_AI_PROVIDER: '   ' });
+    expect(cfg.providerId).toBe('openai_session');
+  });
+
+  it('throws when non-default provider requested without experimental gate', () => {
+    expect(() => readProviderEnvConfig({ CE_AI_PROVIDER: 'copilot' })).toThrow(
+      /copilot[\s\S]*CE_AI_ENABLE_EXPERIMENTAL_PROVIDERS|CE_AI_ENABLE_EXPERIMENTAL_PROVIDERS[\s\S]*copilot/
+    );
+    try {
+      readProviderEnvConfig({ CE_AI_PROVIDER: 'copilot' });
+    } catch (err) {
+      const msg = (err as Error).message;
+      expect(msg).toContain('copilot');
+      expect(msg).toContain('CE_AI_ENABLE_EXPERIMENTAL_PROVIDERS');
+    }
+  });
+
+  it('allows non-default provider when experimental=1', () => {
+    const cfg = readProviderEnvConfig({
+      CE_AI_PROVIDER: 'copilot',
+      CE_AI_ENABLE_EXPERIMENTAL_PROVIDERS: '1',
+    });
+    expect(cfg.providerId).toBe('copilot');
+    expect(cfg.experimentalEnabled).toBe(true);
+  });
+
+  it('accepts true (case-insensitive) for experimental flag', () => {
+    expect(readProviderEnvConfig({ CE_AI_ENABLE_EXPERIMENTAL_PROVIDERS: 'true' }).experimentalEnabled).toBe(true);
+    expect(readProviderEnvConfig({ CE_AI_ENABLE_EXPERIMENTAL_PROVIDERS: 'TRUE' }).experimentalEnabled).toBe(true);
+    expect(readProviderEnvConfig({ CE_AI_ENABLE_EXPERIMENTAL_PROVIDERS: 'True' }).experimentalEnabled).toBe(true);
+    expect(readProviderEnvConfig({ CE_AI_ENABLE_EXPERIMENTAL_PROVIDERS: '1' }).experimentalEnabled).toBe(true);
+  });
+
+  it('rejects 0/false/yes/garbage for experimental flag', () => {
+    expect(readProviderEnvConfig({ CE_AI_ENABLE_EXPERIMENTAL_PROVIDERS: '0' }).experimentalEnabled).toBe(false);
+    expect(readProviderEnvConfig({ CE_AI_ENABLE_EXPERIMENTAL_PROVIDERS: 'false' }).experimentalEnabled).toBe(false);
+    expect(readProviderEnvConfig({ CE_AI_ENABLE_EXPERIMENTAL_PROVIDERS: 'yes' }).experimentalEnabled).toBe(false);
+    expect(readProviderEnvConfig({ CE_AI_ENABLE_EXPERIMENTAL_PROVIDERS: 'garbage' }).experimentalEnabled).toBe(false);
+    expect(readProviderEnvConfig({ CE_AI_ENABLE_EXPERIMENTAL_PROVIDERS: '' }).experimentalEnabled).toBe(false);
+  });
+
+  it('throws when shadow enabled without experimental', () => {
+    try {
+      readProviderEnvConfig({ CE_AI_ENABLE_SHADOW: '1' });
+      throw new Error('expected throw');
+    } catch (err) {
+      const msg = (err as Error).message;
+      expect(msg).toContain('CE_AI_ENABLE_SHADOW');
+      expect(msg).toContain('CE_AI_ENABLE_EXPERIMENTAL_PROVIDERS');
+    }
+  });
+
+  it('enables shadow when both shadow and experimental are set', () => {
+    const cfg = readProviderEnvConfig({
+      CE_AI_ENABLE_SHADOW: '1',
+      CE_AI_ENABLE_EXPERIMENTAL_PROVIDERS: '1',
+    });
+    expect(cfg.shadowEnabled).toBe(true);
+    expect(cfg.experimentalEnabled).toBe(true);
+  });
+
+  it('throws when canary enabled without experimental', () => {
+    try {
+      readProviderEnvConfig({ CE_AI_ENABLE_CANARY: '1' });
+      throw new Error('expected throw');
+    } catch (err) {
+      const msg = (err as Error).message;
+      expect(msg).toContain('CE_AI_ENABLE_CANARY');
+      expect(msg).toContain('CE_AI_ENABLE_EXPERIMENTAL_PROVIDERS');
+    }
+  });
+
+  it('enables canary when both canary and experimental are set', () => {
+    const cfg = readProviderEnvConfig({
+      CE_AI_ENABLE_CANARY: '1',
+      CE_AI_ENABLE_EXPERIMENTAL_PROVIDERS: '1',
+    });
+    expect(cfg.canaryEnabled).toBe(true);
+    expect(cfg.experimentalEnabled).toBe(true);
+  });
+
+  it('does not mutate the input env object', () => {
+    const env = {
+      CE_AI_PROVIDER: 'openai_session',
+      CE_AI_ENABLE_EXPERIMENTAL_PROVIDERS: '1',
+      CE_AI_ENABLE_SHADOW: '1',
+      CE_AI_ENABLE_CANARY: '1',
+      OTHER: 'keep',
+    };
+    const before = JSON.stringify(env);
+    const beforeKeys = Object.keys(env).sort();
+    readProviderEnvConfig(env);
+    expect(JSON.stringify(env)).toBe(before);
+    expect(Object.keys(env).sort()).toEqual(beforeKeys);
+  });
+
+  it('reads from process.env when called with no args', () => {
+    const KEY = 'CE_AI_ENABLE_EXPERIMENTAL_PROVIDERS';
+    const original = process.env[KEY];
+    try {
+      process.env[KEY] = '1';
+      expect(readProviderEnvConfig().experimentalEnabled).toBe(true);
+      delete process.env[KEY];
+      expect(readProviderEnvConfig().experimentalEnabled).toBe(false);
+    } finally {
+      if (original === undefined) {
+        delete process.env[KEY];
+      } else {
+        process.env[KEY] = original;
+      }
+    }
+  });
+});