@ryanfw/prompt-orchestration-pipeline 1.3.3 → 1.3.5

package/src/cli/index.ts

@@ -1,14 +1,19 @@
 #!/usr/bin/env bun
 import { Command } from "commander";
 import { mkdir, access } from "node:fs/promises";
-import { resolve, join } from "node:path";
+import { join } from "node:path";
 
 import { STAGE_NAMES, getStagePurpose, KEBAB_CASE_REGEX } from "./constants.ts";
 import { buildReexecArgs, isCompiledBinary } from "./self-reexec.ts";
 import { updatePipelineJson } from "./update-pipeline-json.ts";
 import { analyzeTaskFile } from "./analyze-task.ts";
 import { submitJobWithValidation, PipelineOrchestrator } from "../api/index.ts";
-import type { Registry } from "./types.ts";
+import { resolveWorkspaceRoot } from "../config/paths.ts";
+import {
+  writeRegistry,
+  registerPipeline,
+  REGISTRY_VERSION,
+} from "../config/pipeline-registry.ts";
 import pkg from "../../package.json";
 
 // ─── init ─────────────────────────────────────────────────────────────────────
@@ -21,10 +26,7 @@ export async function handleInit(root: string): Promise<void> {
     await mkdir(join(root, "pipeline-data", sub), { recursive: true });
     await Bun.write(join(root, "pipeline-data", sub, ".gitkeep"), "");
   }
-  await Bun.write(
-    join(root, "registry.json"),
-    JSON.stringify({ pipelines: {} }, null, 2) + "\n"
-  );
+  await writeRegistry(root, { version: REGISTRY_VERSION, pipelines: {} });
 }
 
 // ─── start ────────────────────────────────────────────────────────────────────
@@ -43,18 +45,49 @@ export function buildUiCorsEnv(opts: StartOptions): Record<string, string> {
   return env;
 }
 
+/**
+ * Build the child env objects passed to the spawned `_start-ui` and
+ * `_start-orchestrator` processes. The parent `handleStart` resolves the
+ * workspace root once via `resolveWorkspaceRoot` and transports the absolute
+ * value to the children via `PO_ROOT`; the children perform their own boot
+ * resolution from that transported value.
+ */
+export function buildStartChildEnv(
+  absoluteRoot: string,
+  port: string,
+  opts?: StartOptions,
+): { uiEnv: Record<string, string>; orchEnv: Record<string, string> } {
+  const uiEnv: Record<string, string> = Object.fromEntries(
+    Object.entries({ ...process.env, NODE_ENV: "production", PO_ROOT: absoluteRoot, PORT: port }).filter(
+      (entry): entry is [string, string] => entry[1] !== undefined,
+    ),
+  );
+  delete uiEnv["PO_UI_PORT"];
+
+  const corsEnv = opts ? buildUiCorsEnv(opts) : {};
+  Object.assign(uiEnv, corsEnv);
+
+  const orchEnv: Record<string, string> = Object.fromEntries(
+    Object.entries({ ...process.env, NODE_ENV: "production", PO_ROOT: absoluteRoot }).filter(
+      (entry): entry is [string, string] => entry[1] !== undefined,
+    ),
+  );
+
+  return { uiEnv, orchEnv };
+}
+
 export async function handleStart(
   root: string | undefined,
   port: string,
   opts?: StartOptions,
 ): Promise<void> {
-  const rawRoot = root ?? process.env["PO_ROOT"];
-  if (!rawRoot) {
-    console.error("Error: --root or PO_ROOT environment variable is required");
+  let absoluteRoot: string;
+  try {
+    absoluteRoot = resolveWorkspaceRoot(root);
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
     process.exit(1);
   }
-
-  const absoluteRoot = resolve(rawRoot);
   process.env["PO_ROOT"] = absoluteRoot;
 
   if (!isCompiledBinary()) {
@@ -69,21 +102,7 @@ export async function handleStart(
     }
   }
 
-  const uiEnv: Record<string, string> = Object.fromEntries(
-    Object.entries({ ...process.env, NODE_ENV: "production", PO_ROOT: absoluteRoot, PORT: port }).filter(
-      (entry): entry is [string, string] => entry[1] !== undefined
-    )
-  );
-  delete uiEnv["PO_UI_PORT"];
-
-  const corsEnv = opts ? buildUiCorsEnv(opts) : {};
-  Object.assign(uiEnv, corsEnv);
-
-  const orchEnv: Record<string, string> = Object.fromEntries(
-    Object.entries({ ...process.env, NODE_ENV: "production", PO_ROOT: absoluteRoot }).filter(
-      (entry): entry is [string, string] => entry[1] !== undefined
-    )
-  );
+  const { uiEnv, orchEnv } = buildStartChildEnv(absoluteRoot, port, opts);
 
   const uiReexec = buildReexecArgs(["_start-ui"]);
   const orchReexec = buildReexecArgs(["_start-orchestrator"]);
@@ -182,7 +201,10 @@ export async function handleStart(
 
 // ─── submit ───────────────────────────────────────────────────────────────────
 
-export async function handleSubmit(seedFile: string): Promise<void> {
+export async function handleSubmit(
+  seedFile: string,
+  opts: { root?: string } = {},
+): Promise<void> {
   let seedObject: unknown;
   try {
     const text = await Bun.file(seedFile).text();
@@ -192,8 +214,9 @@ export async function handleSubmit(seedFile: string): Promise<void> {
     process.exit(1);
   }
 
+  const root = opts.root ?? process.env["PO_ROOT"] ?? process.cwd();
   try {
-    const result = await submitJobWithValidation({ dataDir: process.cwd(), seedObject });
+    const result = await submitJobWithValidation({ root, seedObject });
     if (result.success) {
       console.log(`Job submitted: ${result.jobId} (${result.jobName})`);
     } else {
@@ -208,8 +231,12 @@ export async function handleSubmit(seedFile: string): Promise<void> {
 
 // ─── status ───────────────────────────────────────────────────────────────────
 
-export async function handleStatus(jobName: string | undefined): Promise<void> {
-  const orchestrator = new PipelineOrchestrator({ autoStart: false });
+export async function handleStatus(
+  jobName: string | undefined,
+  opts: { root?: string } = {},
+): Promise<void> {
+  const root = opts.root ?? process.env["PO_ROOT"] ?? process.cwd();
+  const orchestrator = new PipelineOrchestrator({ autoStart: false, root });
   if (jobName) {
     const result = await orchestrator.getStatus(jobName);
     console.log(JSON.stringify(result, null, 2));
@@ -245,25 +272,7 @@ export async function handleAddPipeline(slug: string, root: string): Promise<voi
     );
     await Bun.write(join(tasksDir, "index.ts"), "export default {};\n");
 
-    const registryPath = join(root, "registry.json");
-    let registry: Registry = { pipelines: {} };
-    try {
-      const text = await Bun.file(registryPath).text();
-      registry = JSON.parse(text) as Registry;
-    } catch {
-      // fallback to empty registry
-    }
-
-    const pipelinePath = join(pipelineDir, "pipeline.json");
-    const taskRegistryPath = join(tasksDir, "index.ts");
-    registry.pipelines[slug] = {
-      name: slug,
-      description: "New pipeline",
-      pipelinePath,
-      taskRegistryPath,
-    };
-
-    await Bun.write(registryPath, JSON.stringify(registry, null, 2) + "\n");
+    await registerPipeline(root, slug, { name: slug, description: "New pipeline" });
   } catch (err) {
     console.error(`Error creating pipeline: ${err instanceof Error ? err.message : String(err)}`);
     process.exit(1);
@@ -393,21 +402,21 @@ export async function handleAnalyze(taskPath: string): Promise<void> {
 
 // ─── Hidden: _start-ui ───────────────────────────────────────────────────────
 
-async function handleStartUi(): Promise<void> {
+export async function handleStartUi(): Promise<void> {
+  // PO_ROOT is the inter-process transport set by `handleStart`; the boot
+  // function (startServer) owns the runtime resolution.
   const { startServer } = await import("../ui/server/index.ts");
   await startServer({
-    dataDir: process.env["PO_ROOT"] ?? process.cwd(),
+    dataDir: process.env["PO_ROOT"],
     port: parseInt(process.env["PORT"] ?? "4000", 10),
   });
 }
 
 // ─── Hidden: _start-orchestrator ─────────────────────────────────────────────
 
-async function handleStartOrchestrator(): Promise<void> {
-  if (!process.env["PO_ROOT"]) {
-    console.error("Error: PO_ROOT environment variable is required");
-    process.exit(1);
-  }
+export async function handleStartOrchestrator(): Promise<void> {
+  // PO_ROOT is the inter-process transport set by `handleStart`; the boot
+  // function (startOrchestrator) owns the runtime resolution.
   const { startOrchestrator } = await import("../core/orchestrator.ts");
   const handle = await startOrchestrator({ dataDir: process.env["PO_ROOT"] });
   process.on("SIGINT", () => {
@@ -420,7 +429,8 @@ async function handleStartOrchestrator(): Promise<void> {
 
 // ─── Hidden: _run-job ─────────────────────────────────────────────────────────
 
-async function handleRunJob(jobId: string): Promise<void> {
+export async function handleRunJob(jobId: string): Promise<void> {
+  // Boot resolution happens inside runPipelineJob; this handler only forwards.
   const { runPipelineJob } = await import("../core/pipeline-runner.ts");
   await runPipelineJob(jobId);
 }
@@ -456,15 +466,17 @@ program
 program
   .command("submit <seed-file>")
   .description("Submit a job from a seed JSON file")
-  .action(async (seedFile: string) => {
-    await handleSubmit(seedFile);
+  .option("--root <path>", "Workspace root")
+  .action(async (seedFile: string, opts: { root?: string }) => {
+    await handleSubmit(seedFile, opts);
   });
 
 program
   .command("status [job-name]")
   .description("Query job status")
-  .action(async (jobName: string | undefined) => {
-    await handleStatus(jobName);
+  .option("--root <path>", "Workspace root")
+  .action(async (jobName: string | undefined, opts: { root?: string }) => {
+    await handleStatus(jobName, opts);
   });
 
 program

package/src/cli/types.ts

@@ -1,16 +1,3 @@
-/** Central index of all pipelines in the workspace. */
-export interface Registry {
-  pipelines: Record<string, PipelineRegistryEntry>;
-}
-
-/** A single pipeline's entry in the registry. */
-export interface PipelineRegistryEntry {
-  name: string;
-  description: string;
-  pipelinePath: string;
-  taskRegistryPath: string;
-}
-
 /** A pipeline's configuration file. */
 export interface PipelineConfig {
   name: string;

package/src/cli/update-pipeline-json.ts

@@ -1,3 +1,4 @@
+import { readJsonFile, writeJsonFile } from "../core/json-file.ts";
 import type { PipelineConfig } from "./types.ts";
 
 export async function updatePipelineJson(
@@ -7,19 +8,7 @@ export async function updatePipelineJson(
 ): Promise<void> {
   const filePath = `${root}/pipeline-config/${pipelineSlug}/pipeline.json`;
 
-  let config: PipelineConfig;
-  try {
-    const text = await Bun.file(filePath).text();
-    const parsed = JSON.parse(text) as PipelineConfig;
-    config = parsed;
-  } catch {
-    config = {
-      name: pipelineSlug,
-      version: "1.0.0",
-      description: "New pipeline",
-      tasks: [],
-    };
-  }
+  const config = await readJsonFile<PipelineConfig>(filePath);
 
   if (!Array.isArray(config.tasks)) {
     config.tasks = [];
@@ -29,5 +18,5 @@ export async function updatePipelineJson(
     config.tasks.push(taskSlug);
   }
 
-  await Bun.write(filePath, JSON.stringify(config, null, 2) + "\n");
+  await writeJsonFile(filePath, config);
 }

package/src/config/__tests__/config-schema.test.ts

@@ -0,0 +1,42 @@
+import { describe, it, expect } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import Ajv from "ajv";
+
+const schemaPath = join(process.cwd(), "config.schema.json");
+const schema = JSON.parse(readFileSync(schemaPath, "utf-8")) as {
+  properties: { llm: { properties: { defaultProvider: { enum: string[] } } } };
+};
+
+const ajv = new Ajv({ allErrors: true, strict: false });
+const validate = ajv.compile(schema);
+
+function llmConfig(defaultProvider: string): unknown {
+  return { llm: { defaultProvider } };
+}
+
+describe("config.schema.json defaultProvider enum", () => {
+  it("accepts canonical provider ids", () => {
+    expect(validate(llmConfig("openai"))).toBe(true);
+    expect(validate(llmConfig("zai"))).toBe(true);
+    expect(validate(llmConfig("claude-code"))).toBe(true);
+    expect(validate(llmConfig("moonshot"))).toBe(true);
+  });
+
+  it("rejects legacy provider ids", () => {
+    expect(validate(llmConfig("zhipu"))).toBe(false);
+    expect(validate(llmConfig("claudecode"))).toBe(false);
+  });
+
+  it("rejects unknown provider ids", () => {
+    expect(validate(llmConfig("neverheard"))).toBe(false);
+  });
+
+  it("enum matches the canonical ProviderName set (no legacy spellings)", () => {
+    const enumValues = schema.properties.llm.properties.defaultProvider.enum;
+    expect(enumValues).not.toContain("zhipu");
+    expect(enumValues).not.toContain("claudecode");
+    expect(enumValues).toContain("zai");
+    expect(enumValues).toContain("claude-code");
+  });
+});

package/src/config/__tests__/legacy-literal-guard.test.ts

@@ -0,0 +1,156 @@
+import { describe, it, expect } from "bun:test";
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative, resolve, sep } from "node:path";
+
+const FORBIDDEN_LITERALS: ReadonlySet<string> = new Set([
+  "zhipu",
+  "claudecode",
+]);
+
+const STRING_LITERAL_RE = /"(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'/g;
+
+const ALLOWED_FILES: ReadonlySet<string> = new Set([
+  "src/config/models.ts",
+  "src/config/__tests__/models.test.ts",
+  "src/config/__tests__/config-schema.test.ts",
+  "src/config/__tests__/legacy-literal-guard.test.ts",
+  "src/llm/__tests__/legacy-normalization.test.ts",
+  "src/llm/__tests__/index.test.ts",
+  "src/providers/__tests__/types.test.ts",
+  "src/task-analysis/__tests__/analyzer.test.ts",
+  "src/task-analysis/__tests__/enrichers-schema-deducer.test.ts",
+]);
+
+export interface LegacyLiteralViolation {
+  path: string;
+  literal: string;
+}
+
+export interface SourceFile {
+  path: string;
+  content: string;
+}
+
+export function extractStringLiterals(source: string): string[] {
+  const out: string[] = [];
+  for (const match of source.matchAll(STRING_LITERAL_RE)) {
+    const raw = match[0] as string;
+    out.push(raw.slice(1, -1));
+  }
+  return out;
+}
+
+export function scanFiles(
+  files: SourceFile[],
+  allowlist: ReadonlySet<string>,
+): LegacyLiteralViolation[] {
+  const violations: LegacyLiteralViolation[] = [];
+  for (const file of files) {
+    if (allowlist.has(file.path)) continue;
+    for (const literal of extractStringLiterals(file.content)) {
+      if (FORBIDDEN_LITERALS.has(literal)) {
+        violations.push({ path: file.path, literal });
+      }
+    }
+  }
+  return violations;
+}
+
+export function listSourceTsFiles(scanRoot: string, base: string): SourceFile[] {
+  const rootAbs = resolve(scanRoot);
+  const baseAbs = resolve(base);
+  const out: SourceFile[] = [];
+
+  function walk(dir: string): void {
+    for (const entry of readdirSync(dir)) {
+      const full = join(dir, entry);
+      const st = statSync(full);
+      if (st.isDirectory()) {
+        walk(full);
+      } else if (st.isFile() && /\.(ts|tsx)$/.test(entry)) {
+        const rel = relative(baseAbs, full).split(sep).join("/");
+        out.push({ path: rel, content: readFileSync(full, "utf-8") });
+      }
+    }
+  }
+
+  walk(rootAbs);
+  return out;
+}
+
+describe("extractStringLiterals", () => {
+  it("captures a double-quoted forbidden literal", () => {
+    expect(extractStringLiterals('const p = "zhipu";')).toContain("zhipu");
+  });
+
+  it("ignores the bare legacy word in a comment", () => {
+    expect(extractStringLiterals("// legacy zhipu id\nconst x = 1;")).toEqual([]);
+  });
+});
+
+describe("scanFiles — forbidden literal detection", () => {
+  it('flags "zhipu" outside the allowlist', () => {
+    const violations = scanFiles(
+      [{ path: "src/x.ts", content: 'const p = "zhipu";' }],
+      new Set(),
+    );
+    expect(violations).toEqual([{ path: "src/x.ts", literal: "zhipu" }]);
+  });
+
+  it('flags "claudecode" outside the allowlist', () => {
+    const violations = scanFiles(
+      [{ path: "src/y.ts", content: "const q = \"claudecode\";" }],
+      new Set(),
+    );
+    expect(violations).toEqual([{ path: "src/y.ts", literal: "claudecode" }]);
+  });
+
+  it("skips files listed in the allowlist", () => {
+    const violations = scanFiles(
+      [{ path: "src/config/models.ts", content: 'legacyAliases: ["zhipu"]' }],
+      new Set(["src/config/models.ts"]),
+    );
+    expect(violations).toEqual([]);
+  });
+});
+
+describe("scanFiles — legitimate substrings are not flagged", () => {
+  it("ignores the ZHIPU_API_KEY env-var name", () => {
+    const violations = scanFiles(
+      [{ path: "src/env.ts", content: 'const k = "ZHIPU_API_KEY";' }],
+      new Set(),
+    );
+    expect(violations).toEqual([]);
+  });
+
+  it("ignores an import path that ends in zhipu.ts", () => {
+    const violations = scanFiles(
+      [
+        {
+          path: "src/llm/index.ts",
+          content: 'import { zaiChat } from "../providers/zhipu.ts";',
+        },
+      ],
+      new Set(),
+    );
+    expect(violations).toEqual([]);
+  });
+
+  it("ignores the legacy word inside a comment", () => {
+    const violations = scanFiles(
+      [{ path: "src/cmt.ts", content: "// legacy zhipu id\nconst x = 1;" }],
+      new Set(),
+    );
+    expect(violations).toEqual([]);
+  });
+});
+
+describe("legacy-literal source guard (AC-3)", () => {
+  it("src/ has no forbidden legacy literals outside the allowlist", () => {
+    const cwd = process.cwd();
+    const files = listSourceTsFiles(join(cwd, "src"), cwd);
+    const violations = scanFiles(files, ALLOWED_FILES);
+
+    expect(violations).toEqual([]);
+  });
+});

package/src/config/__tests__/models.test.ts

@@ -6,17 +6,20 @@ import {
   DEFAULT_MODEL_BY_PROVIDER,
   FUNCTION_NAME_BY_ALIAS,
   PROVIDER_FUNCTIONS,
+  PROVIDERS,
   aliasToFunctionName,
   getProviderFromAlias,
   getModelFromAlias,
   getModelConfig,
   buildProviderFunctionsIndex,
+  normalizeLegacyProvider,
   validateModelRegistry,
 } from "../models";
-import type { ModelConfigEntry } from "../models";
+import type { ModelConfigEntry, ProviderName, ProviderMeta } from "../models";
 
 const MODEL_COUNT = 51;
 const PROVIDER_COUNT = 9;
+const REGISTRY_PROVIDER_COUNT = 10;
 
 describe("ModelAlias", () => {
   it(`has exactly ${MODEL_COUNT} entries`, () => {
@@ -378,3 +381,138 @@ describe("validateModelRegistry — invariant failures", () => {
     expect(() => validateModelRegistry(config, set)).not.toThrow();
   });
 });
+
+describe("normalizeLegacyProvider", () => {
+  it('maps legacy "zhipu" to canonical "zai"', () => {
+    expect(normalizeLegacyProvider("zhipu")).toBe("zai");
+  });
+
+  it('maps legacy "claudecode" to canonical "claude-code"', () => {
+    expect(normalizeLegacyProvider("claudecode")).toBe("claude-code");
+  });
+
+  it('returns canonical "zai" for itself', () => {
+    expect(normalizeLegacyProvider("zai")).toBe("zai");
+  });
+
+  it('returns canonical "claude-code" for itself', () => {
+    expect(normalizeLegacyProvider("claude-code")).toBe("claude-code");
+  });
+
+  it('returns canonical "openai" for itself', () => {
+    expect(normalizeLegacyProvider("openai")).toBe("openai");
+  });
+
+  it("returns null for an unknown provider string", () => {
+    expect(normalizeLegacyProvider("unknown")).toBeNull();
+  });
+
+  it("returns null for the empty string", () => {
+    expect(normalizeLegacyProvider("")).toBeNull();
+  });
+
+  it("returns null for Object.prototype property names", () => {
+    expect(normalizeLegacyProvider("constructor")).toBeNull();
+    expect(normalizeLegacyProvider("toString")).toBeNull();
+    expect(normalizeLegacyProvider("valueOf")).toBeNull();
+    expect(normalizeLegacyProvider("hasOwnProperty")).toBeNull();
+    expect(normalizeLegacyProvider("__proto__")).toBeNull();
+  });
+});
+
+describe("PROVIDERS registry invariants", () => {
+  const CANONICAL_PROVIDER_IDS: ProviderName[] = [
+    "openai",
+    "anthropic",
+    "deepseek",
+    "gemini",
+    "zai",
+    "claude-code",
+    "moonshot",
+    "alibaba",
+    "opencode",
+    "mock",
+  ];
+
+  it(`has exactly ${REGISTRY_PROVIDER_COUNT} rows, one per canonical ProviderName`, () => {
+    expect(Object.keys(PROVIDERS).length).toBe(REGISTRY_PROVIDER_COUNT);
+    for (const id of CANONICAL_PROVIDER_IDS) {
+      expect(id in PROVIDERS).toBe(true);
+    }
+  });
+
+  it("table is frozen", () => {
+    expect(Object.isFrozen(PROVIDERS)).toBe(true);
+  });
+
+  it("legacyAliases are unique across the registry (no alias maps to two providers)", () => {
+    const seen = new Map<string, ProviderName>();
+    for (const [canonical, meta] of Object.entries(PROVIDERS) as [ProviderName, ProviderMeta][]) {
+      for (const alias of meta.legacyAliases) {
+        const prior = seen.get(alias);
+        if (prior !== undefined) {
+          throw new Error(
+            `legacy alias "${alias}" is claimed by both "${prior}" and "${canonical}"`,
+          );
+        }
+        seen.set(alias, canonical);
+      }
+    }
+  });
+
+  it("no legacy alias collides with a canonical id", () => {
+    const canonicalSet = new Set<string>(CANONICAL_PROVIDER_IDS);
+    for (const meta of Object.values(PROVIDERS)) {
+      for (const alias of meta.legacyAliases) {
+        expect(canonicalSet.has(alias)).toBe(false);
+      }
+    }
+  });
+
+  it("MODEL_CONFIG providers are all registered catalog providers (no orphans, no mock)", () => {
+    for (const entry of Object.values(MODEL_CONFIG)) {
+      expect(entry.provider in PROVIDERS).toBe(true);
+      expect(entry.provider).not.toBe("mock");
+    }
+  });
+
+  it("MODEL_CONFIG / DEFAULT_MODEL_BY_PROVIDER / PROVIDER_FUNCTIONS exclude only mock from the registry", () => {
+    const registryKeys = new Set<string>(Object.keys(PROVIDERS));
+    const catalogKeys = new Set<string>(Object.keys(PROVIDER_FUNCTIONS));
+    const defaultKeys = new Set<string>(
+      Object.keys(DEFAULT_MODEL_BY_PROVIDER) as string[],
+    );
+
+    for (const key of catalogKeys) expect(registryKeys.has(key)).toBe(true);
+    for (const key of defaultKeys) expect(registryKeys.has(key)).toBe(true);
+
+    const missingFromCatalog = [...registryKeys].filter(
+      (k) => !catalogKeys.has(k),
+    );
+    const missingFromDefaults = [...registryKeys].filter(
+      (k) => !defaultKeys.has(k),
+    );
+    expect(missingFromCatalog).toEqual(["mock"]);
+    expect(missingFromDefaults).toEqual(["mock"]);
+  });
+
+  it("canonical<->alias round-trip via normalizeLegacyProvider", () => {
+    for (const [canonical, meta] of Object.entries(PROVIDERS) as [ProviderName, ProviderMeta][]) {
+      expect(normalizeLegacyProvider(canonical)).toBe(canonical);
+      for (const alias of meta.legacyAliases) {
+        expect(normalizeLegacyProvider(alias)).toBe(canonical);
+      }
+    }
+  });
+
+  it("CLI providers declare sampling: []", () => {
+    expect(PROVIDERS["claude-code"]!.sampling).toEqual([]);
+    expect(PROVIDERS.opencode!.sampling).toEqual([]);
+  });
+
+  it("mock is runtime-only: empty envKeys/sampling, isCLI false", () => {
+    expect(PROVIDERS.mock!.envKeys).toEqual([]);
+    expect(PROVIDERS.mock!.sampling).toEqual([]);
+    expect(PROVIDERS.mock!.isCLI).toBe(false);
+  });
+});