Skip to content

Claude Code. Any Model. The most powerful AI coding agent now speaks every language.

test(catalog): cover the contract-incompatibility guard

Jack Rudenko70665a18c37a
diff --git a/packages/cli/src/adapters/model-catalog.test.ts b/packages/cli/src/adapters/model-catalog.test.ts
index bf53e3e7..6e9f7790 100644
--- a/packages/cli/src/adapters/model-catalog.test.ts
+++ b/packages/cli/src/adapters/model-catalog.test.ts
@@ -79,7 +79,72 @@ function writeCatalog(entries: SlimModelEntry[], plans: CachedSubscriptionPlan[]
}
describe("resolveSubscriptionRouting", () => {
- test("returns unknown when an unrouted sibling makes the provider plan view partial", () => {
+ test("returns serves only when every Qwen plan sharing the route includes the model", () => {
+ writeCatalog(
+ [
+ modelEntry(
+ "qwen3-coder-plus",
+ ["alibaba-token-plan-individual", "alibaba-token-plan-team-edition"],
+ "qwen-cloud",
+ "qwen3-coder-plus-wire"
+ ),
+ ],
+ [
+ routedPlan("alibaba-token-plan-individual", "alibaba", "qwen-cloud"),
+ routedPlan("alibaba-token-plan-team-edition", "alibaba", "qwen-cloud"),
+ ]
+ );
+
+ expect(resolveSubscriptionRouting("qwen3-coder-plus", "qwen-cloud", cachePath)).toEqual({
+ kind: "serves",
+ externalId: "qwen3-coder-plus-wire",
+ });
+ });
+
+ test("returns unknown when only some Qwen plans sharing the route include the model", () => {
+ writeCatalog(
+ [
+ modelEntry(
+ "qwen3-coder-plus",
+ ["alibaba-token-plan-team-edition"],
+ "qwen-cloud",
+ "qwen3-coder-plus-wire"
+ ),
+ ],
+ [
+ routedPlan("alibaba-token-plan-individual", "alibaba", "qwen-cloud"),
+ routedPlan("alibaba-token-plan-team-edition", "alibaba", "qwen-cloud"),
+ ]
+ );
+
+ expect(resolveSubscriptionRouting("qwen3-coder-plus", "qwen-cloud", cachePath)).toEqual({
+ kind: "unknown",
+ });
+ });
+
+ test("preserves not-served when no Qwen plan includes the model and both rosters are catalog-authoritative", () => {
+ writeCatalog(
+ [
+ modelEntry("qwen3-coder-plus", [], "qwen-cloud"),
+ modelEntry("qwen-roster-proof", [
+ "alibaba-token-plan-individual",
+ "alibaba-token-plan-team-edition",
+ ]),
+ ],
+ [
+ routedPlan("alibaba-token-plan-individual", "alibaba", "qwen-cloud"),
+ routedPlan("alibaba-token-plan-team-edition", "alibaba", "qwen-cloud"),
+ ]
+ );
+
+ // This is not a new destructive verdict: the pre-bc7fd79 implementation
+ // already returned not-served for a complete, catalog-authoritative view.
+ expect(resolveSubscriptionRouting("qwen3-coder-plus", "qwen-cloud", cachePath)).toEqual({
+ kind: "not-served",
+ });
+ });
+
+ test("keeps the v9.0.4 guard: a same-vendor plan without routing forces unknown", () => {
writeCatalog(
[
modelEntry("qwen3-coder-plus", [], "qwen-cloud"),
diff --git a/packages/cli/src/providers/catalog-client-contract.test.ts b/packages/cli/src/providers/catalog-client-contract.test.ts
new file mode 100644
index 00000000..dbb82b23
--- /dev/null
+++ b/packages/cli/src/providers/catalog-client-contract.test.ts
@@ -0,0 +1,224 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+interface EndpointReply {
+ status: number;
+ body?: unknown;
+}
+
+interface RefreshChildResult {
+ outcome: unknown;
+ sentinel: unknown;
+}
+
+interface WarmCacheChildResult {
+ before: unknown;
+ after: unknown;
+}
+
+let tempHome = "";
+let server: ReturnType<typeof Bun.serve> | undefined;
+
+beforeEach(() => {
+ tempHome = mkdtempSync(join(tmpdir(), "claudish-catalog-client-contract-"));
+});
+
+afterEach(() => {
+ server?.stop(true);
+ server = undefined;
+ rmSync(tempHome, { recursive: true, force: true });
+ tempHome = "";
+});
+
+function startCatalogServer(
+ modelsReply: EndpointReply,
+ plansReply: EndpointReply = { status: 200, body: { contractVersion: 2, plans: [] } }
+): { catalogUrl: string; plansUrl: string } {
+ server = Bun.serve({
+ port: 0,
+ fetch(request) {
+ const { pathname } = new URL(request.url);
+ const reply = pathname === "/queryPlans" ? plansReply : modelsReply;
+ return new Response(reply.body === undefined ? undefined : JSON.stringify(reply.body), {
+ status: reply.status,
+ headers: reply.body === undefined ? undefined : { "content-type": "application/json" },
+ });
+ },
+ });
+
+ return {
+ catalogUrl: `http://127.0.0.1:${server.port}/queryModels`,
+ plansUrl: `http://127.0.0.1:${server.port}/queryPlans`,
+ };
+}
+
+async function runRefreshChild(urls: {
+ catalogUrl: string;
+ plansUrl: string;
+}): Promise<RefreshChildResult> {
+ const clientUrl = pathToFileURL(join(import.meta.dir, "catalog-client.ts")).href;
+ const compatibilityUrl = pathToFileURL(join(import.meta.dir, "catalog-compatibility.ts")).href;
+ const sentinelPath = join(tempHome, ".claudish", "catalog-incompatible.json");
+ const source = `
+ const compatibility = await import(${JSON.stringify(compatibilityUrl)});
+ const client = await import(${JSON.stringify(clientUrl)});
+ compatibility._resetCatalogCompatibilityForTest();
+ client._resetCatalogClient();
+ const outcome = await client.refreshCatalog(2_000);
+ const sentinel = compatibility.readCatalogIncompatibility(
+ ${JSON.stringify(sentinelPath)}
+ );
+ console.log(JSON.stringify({ outcome, sentinel }));
+ `;
+ const child = Bun.spawn([process.execPath, "-e", source], {
+ cwd: import.meta.dir,
+ env: {
+ ...process.env,
+ HOME: tempHome,
+ CLAUDISH_CATALOG_URL: urls.catalogUrl,
+ CLAUDISH_PLANS_URL: urls.plansUrl,
+ },
+ stdout: "pipe",
+ stderr: "pipe",
+ });
+ const [stdout, stderr, exitCode] = await Promise.all([
+ new Response(child.stdout).text(),
+ new Response(child.stderr).text(),
+ child.exited,
+ ]);
+ if (exitCode !== 0) {
+ throw new Error(`catalog child exited ${exitCode}: ${stderr || stdout}`);
+ }
+ return JSON.parse(stdout.trim()) as RefreshChildResult;
+}
+
+async function runWarmCacheChild(urls: {
+ catalogUrl: string;
+ plansUrl: string;
+}): Promise<WarmCacheChildResult> {
+ const clientUrl = pathToFileURL(join(import.meta.dir, "catalog-client.ts")).href;
+ const compatibilityUrl = pathToFileURL(join(import.meta.dir, "catalog-compatibility.ts")).href;
+ const sentinelPath = join(tempHome, ".claudish", "catalog-incompatible.json");
+ const source = `
+ const compatibility = await import(${JSON.stringify(compatibilityUrl)});
+ const client = await import(${JSON.stringify(clientUrl)});
+ compatibility._resetCatalogCompatibilityForTest();
+ client._resetCatalogClient();
+ const before = client.getCatalogEntries();
+ compatibility.markCatalogIncompatible(
+ { serverContractVersion: 3, minimumContractVersion: 3 },
+ ${JSON.stringify(sentinelPath)}
+ );
+ const after = client.getCatalogEntries();
+ console.log(JSON.stringify({ before, after }));
+ `;
+ const child = Bun.spawn([process.execPath, "-e", source], {
+ cwd: import.meta.dir,
+ env: {
+ ...process.env,
+ HOME: tempHome,
+ CLAUDISH_CATALOG_URL: urls.catalogUrl,
+ CLAUDISH_PLANS_URL: urls.plansUrl,
+ },
+ stdout: "pipe",
+ stderr: "pipe",
+ });
+ const [stdout, stderr, exitCode] = await Promise.all([
+ new Response(child.stdout).text(),
+ new Response(child.stderr).text(),
+ child.exited,
+ ]);
+ if (exitCode !== 0) {
+ throw new Error(`catalog child exited ${exitCode}: ${stderr || stdout}`);
+ }
+ return JSON.parse(stdout.trim()) as WarmCacheChildResult;
+}
+
+describe("catalog contract compatibility over HTTP", () => {
+ test("refreshCatalog returns incompatible for a body-less 426 response", async () => {
+ const urls = startCatalogServer({ status: 426 });
+
+ const result = await runRefreshChild(urls);
+
+ expect(result.outcome).toEqual({ kind: "incompatible", serverContractVersion: null });
+ expect(result.sentinel).toMatchObject({ serverContractVersion: null });
+ });
+
+ test("any non-2xx response is incompatible when its body reports a newer contract", async () => {
+ for (const status of [400, 410, 429, 503]) {
+ server?.stop(true);
+ server = undefined;
+ const urls = startCatalogServer({
+ status,
+ body: {
+ contractVersion: 3,
+ error: {
+ code: "catalog_unavailable",
+ minimumContractVersion: 3,
+ },
+ },
+ });
+
+ const result = await runRefreshChild(urls);
+
+ expect(result.outcome).toEqual({ kind: "incompatible", serverContractVersion: 3 });
+ expect(result.sentinel).toMatchObject({
+ serverContractVersion: 3,
+ minimumContractVersion: 3,
+ });
+ }
+ });
+
+ test("never writes a v3 success body into the existing v2 disk cache", async () => {
+ const cacheDir = join(tempHome, ".claudish");
+ const cachePath = join(cacheDir, "all-models.json");
+ const originalBytes = Buffer.from(
+ '{\n "version": 2,\n "lastUpdated": "2026-09-10T00:00:00.000Z",\n "entries": [{"modelId":"safe-v2-model","aliases":[],"sources":{}}],\n "models": []\n}\n',
+ "utf8"
+ );
+ mkdirSync(cacheDir, { recursive: true });
+ writeFileSync(cachePath, originalBytes);
+ const urls = startCatalogServer({
+ status: 200,
+ body: {
+ contractVersion: 3,
+ total: 1,
+ models: [{ modelId: "unsafe-v3-model", aliases: [], sources: {} }],
+ },
+ });
+
+ const result = await runRefreshChild(urls);
+
+ expect(result.outcome).toEqual({ kind: "incompatible", serverContractVersion: 3 });
+ expect(readFileSync(cachePath).equals(originalBytes)).toBe(true);
+ });
+
+ test("returns null after the sentinel is set even when the module cache is warm", async () => {
+ const cacheDir = join(tempHome, ".claudish");
+ mkdirSync(cacheDir, { recursive: true });
+ writeFileSync(
+ join(cacheDir, "all-models.json"),
+ JSON.stringify({
+ version: 2,
+ lastUpdated: "2026-09-10T00:00:00.000Z",
+ entries: [{ modelId: "warm-v2-model", aliases: [], sources: {} }],
+ models: [],
+ }),
+ "utf8"
+ );
+ // This path does not fetch; the URLs only ensure module evaluation stays
+ // hermetic from production endpoints while the disk cache is warmed.
+ const urls = {
+ catalogUrl: "http://127.0.0.1:1/queryModels",
+ plansUrl: "http://127.0.0.1:1/queryPlans",
+ };
+
+ const result = await runWarmCacheChild(urls);
+
+ expect(result.before).toEqual([{ modelId: "warm-v2-model", aliases: [], sources: {} }]);
+ expect(result.after).toBeNull();
+ });
+});
diff --git a/packages/cli/src/providers/catalog-compatibility.test.ts b/packages/cli/src/providers/catalog-compatibility.test.ts
new file mode 100644
index 00000000..d4b709a2
--- /dev/null
+++ b/packages/cli/src/providers/catalog-compatibility.test.ts
@@ -0,0 +1,131 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+ type CatalogIncompatibility,
+ SUPPORTED_CONTRACT_VERSION,
+ _resetCatalogCompatibilityForTest,
+ clearCatalogIncompatibility,
+ markCatalogIncompatible,
+ parseContractEnvelope,
+ readCatalogIncompatibility,
+} from "./catalog-compatibility.js";
+
+let tempDir = "";
+
+beforeEach(() => {
+ tempDir = mkdtempSync(join(tmpdir(), "claudish-catalog-compatibility-"));
+ _resetCatalogCompatibilityForTest();
+});
+
+afterEach(() => {
+ _resetCatalogCompatibilityForTest();
+ rmSync(tempDir, { recursive: true, force: true });
+ tempDir = "";
+});
+
+describe("parseContractEnvelope", () => {
+ test("reads the frozen backend envelope with a top-level version and nested minimum", () => {
+ expect(
+ parseContractEnvelope({
+ contractVersion: SUPPORTED_CONTRACT_VERSION + 1,
+ error: {
+ code: "catalog_client_upgrade_required",
+ message: "Upgrade required",
+ minimumContractVersion: SUPPORTED_CONTRACT_VERSION + 1,
+ },
+ })
+ ).toEqual({
+ contractVersion: SUPPORTED_CONTRACT_VERSION + 1,
+ minimumContractVersion: SUPPORTED_CONTRACT_VERSION + 1,
+ });
+ });
+
+ test("returns an unknown version when the body declares neither envelope field", () => {
+ expect(parseContractEnvelope({ models: [] })).toEqual({ contractVersion: null });
+ });
+
+ test("returns an unknown version for null and non-object bodies", () => {
+ for (const body of [null, undefined, "not-json", 3, true]) {
+ expect(parseContractEnvelope(body)).toEqual({ contractVersion: null });
+ }
+ });
+});
+
+describe("catalog incompatibility sentinel", () => {
+ test("keeps the process blocked in memory when the disk write fails", () => {
+ const fileWhereDirectoryIsRequired = join(tempDir, "not-a-directory");
+ writeFileSync(fileWhereDirectoryIsRequired, "blocks mkdir", "utf8");
+ const unwritableSentinel = join(fileWhereDirectoryIsRequired, "catalog-incompatible.json");
+ const unrelatedMissingPath = join(tempDir, "missing", "catalog-incompatible.json");
+
+ markCatalogIncompatible(
+ {
+ serverContractVersion: SUPPORTED_CONTRACT_VERSION + 1,
+ minimumContractVersion: SUPPORTED_CONTRACT_VERSION + 1,
+ },
+ unwritableSentinel
+ );
+
+ expect(existsSync(unwritableSentinel)).toBe(false);
+ expect(readCatalogIncompatibility(unrelatedMissingPath)).toMatchObject({
+ serverContractVersion: SUPPORTED_CONTRACT_VERSION + 1,
+ minimumContractVersion: SUPPORTED_CONTRACT_VERSION + 1,
+ });
+ });
+
+ test("memoizes the first disk read for the supplied path", () => {
+ const sentinelPath = join(tempDir, "catalog-incompatible.json");
+ const firstRecord: CatalogIncompatibility = {
+ detectedAt: "2026-09-10T00:00:00.000Z",
+ serverContractVersion: 3,
+ minimumContractVersion: 3,
+ };
+ const replacementRecord: CatalogIncompatibility = {
+ detectedAt: "2026-09-10T01:00:00.000Z",
+ serverContractVersion: 4,
+ minimumContractVersion: 4,
+ };
+ writeFileSync(sentinelPath, JSON.stringify(firstRecord), "utf8");
+
+ expect(readCatalogIncompatibility(sentinelPath)).toEqual(firstRecord);
+ writeFileSync(sentinelPath, JSON.stringify(replacementRecord), "utf8");
+ expect(readCatalogIncompatibility(sentinelPath)).toEqual(firstRecord);
+ });
+
+ test("reset clears both the in-memory flag and the memoized disk read", () => {
+ const blocker = join(tempDir, "reset-blocker");
+ writeFileSync(blocker, "blocks mkdir", "utf8");
+ const unwritableSentinel = join(blocker, "catalog-incompatible.json");
+ const missingPath = join(tempDir, "missing-after-reset.json");
+ markCatalogIncompatible({ serverContractVersion: 3 }, unwritableSentinel);
+
+ _resetCatalogCompatibilityForTest();
+ expect(readCatalogIncompatibility(missingPath)).toBeNull();
+
+ const memoPath = join(tempDir, "memoized-before-reset.json");
+ const record: CatalogIncompatibility = {
+ detectedAt: "2026-09-10T02:00:00.000Z",
+ serverContractVersion: 3,
+ };
+ writeFileSync(memoPath, JSON.stringify(record), "utf8");
+ expect(readCatalogIncompatibility(memoPath)).toEqual(record);
+ rmSync(memoPath);
+
+ _resetCatalogCompatibilityForTest();
+ expect(readCatalogIncompatibility(memoPath)).toBeNull();
+ });
+
+ test("clear removes the supplied sentinel path and clears its cached value", () => {
+ const sentinelPath = join(tempDir, "custom", "catalog-incompatible.json");
+ markCatalogIncompatible({ serverContractVersion: 3 }, sentinelPath);
+ expect(existsSync(sentinelPath)).toBe(true);
+ expect(readCatalogIncompatibility(sentinelPath)).not.toBeNull();
+
+ clearCatalogIncompatibility(sentinelPath);
+
+ expect(existsSync(sentinelPath)).toBe(false);
+ expect(readCatalogIncompatibility(sentinelPath)).toBeNull();
+ });
+});