@evoclock/pi-agentic-driver 0.9.2 → 0.9.4

package/janus/tests/accounting.test.ts

@@ -0,0 +1,229 @@
+// SPDX-FileCopyrightText: 2026 Julen Gamboa <j.a.r.gamboa@gmail.com>
+// SPDX-License-Identifier: AGPL-3.0-only
+
+// Usage-accounting regression tests (task #44 follow-up, review fixes #11/#12):
+//
+//   1. N coalesced callers → one provider call, one usage charge.
+//   2. Retry then success → failed-attempt usage + success usage each charged once.
+//   3. All attempts fail → all accumulated usage charged despite the thrown taxonomy error.
+//   4. Provider success followed by answer-validation failure → usage still charged.
+//   5. Provider selection: typesafe-direct is the sole provider; unconfigured TypeSafe fails closed.
+//
+// Every test inspects DailyBudget.status().tokensUsed — the breaker is the
+// single accounting sink.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { Evaluator } from "../janus/evaluate.js";
+import { SingleFlight } from "../janus/single_flight.js";
+import { DailyBudget } from "../janus/budget_breaker.js";
+import { AuditLog } from "../janus/audit.js";
+import {
+  defaultAdapters,
+  ProviderChain,
+  ProviderChainError,
+  ProviderTransportError,
+  type TransportRequest,
+} from "../janus/providers.js";
+import { gatewayUnavailable, timeoutError } from "../janus/errors.js";
+import {
+  testConfig,
+  testProviders,
+  testRetryProviders,
+  fakeKeyReader,
+  mockAdapter,
+  mockChain,
+  type MockChainCall,
+} from "./helpers.js";
+
+const BODY = {
+  state: "shared state",
+  questions: [{ type: "boolean", name: "q", question: "ok?" }],
+};
+
+const USAGE_120 = { inputTokens: 100, outputTokens: 20, totalTokens: 120 };
+
+function noopAudit(): AuditLog {
+  return { append: () => {} } as unknown as AuditLog;
+}
+
+test("accounting: three coalesced callers → one provider call, ONE usage charge", async () => {
+  const calls: MockChainCall[] = [];
+  const budget = new DailyBudget(10_000, 0, 0.5);
+  const evaluator = new Evaluator({
+    config: testConfig(),
+    singleFlight: new SingleFlight(4),
+    budget,
+    audit: noopAudit(),
+    chain: mockChain({
+      answers: { q: { type: "boolean", probability: 0.95 } },
+      delayMs: 60,
+      calls,
+      usage: USAGE_120,
+    }) as never,
+  });
+  const [a, b, c] = await Promise.all([
+    evaluator.handle(BODY),
+    evaluator.handle(BODY),
+    evaluator.handle(BODY),
+  ]);
+  assert.equal(a.status, 200);
+  assert.equal(b.status, 200);
+  assert.equal(c.status, 200);
+  assert.equal(calls.length, 1, "identical requests coalesce to one provider call");
+  assert.equal(budget.status().tokensUsed, 120, "exactly one charge: 360 would mean double accounting");
+});
+
+test("accounting: retry then success → failed + successful attempt usage each charged once", async () => {
+  const calls: unknown[] = [];
+  let first = true;
+  const budget = new DailyBudget(10_000, 0, 0.5);
+  const chain = new ProviderChain(
+    testRetryProviders(),
+    [
+      mockAdapter({
+        id: "typesafe-direct",
+        calls: calls as never,
+        usage: USAGE_120,
+        answers: { q: { type: "boolean", probability: 0.9 } },
+        fail: () => {
+          if (first) {
+            first = false;
+            return new ProviderTransportError("timeout", timeoutError("slow"), {
+              inputTokens: 80,
+              outputTokens: 20,
+              totalTokens: 100,
+            });
+          }
+          return undefined;
+        },
+      }),
+    ],
+    fakeKeyReader(),
+  );
+  const evaluator = new Evaluator({
+    config: testConfig(),
+    singleFlight: new SingleFlight(4),
+    budget,
+    audit: noopAudit(),
+    chain,
+  });
+  const response = await evaluator.handle(BODY);
+  assert.equal(response.status, 200);
+  assert.equal(calls.length, 2, "one failed attempt plus one successful attempt");
+  assert.equal(budget.status().tokensUsed, 100 + 120, "failed-attempt usage is charged alongside success usage");
+});
+
+test("accounting: all attempts fail → every attempt's usage charged despite the thrown JanusError", async () => {
+  let attempt = 0;
+  const budget = new DailyBudget(10_000, 0, 0.5);
+  const usages = [
+    { inputTokens: 80, outputTokens: 20, totalTokens: 100 },
+    { inputTokens: 40, outputTokens: 40, totalTokens: 80 },
+  ];
+  const chain = new ProviderChain(
+    testRetryProviders(),
+    [
+      mockAdapter({
+        id: "typesafe-direct",
+        fail: () => {
+          const usage = usages[Math.min(attempt, usages.length - 1)]!;
+          attempt += 1;
+          return new ProviderTransportError("gateway_unavailable", gatewayUnavailable("down"), usage);
+        },
+      }),
+    ],
+    fakeKeyReader(),
+  );
+  const evaluator = new Evaluator({
+    config: testConfig(),
+    singleFlight: new SingleFlight(4),
+    budget,
+    audit: noopAudit(),
+    chain,
+  });
+  const response = await evaluator.handle(BODY);
+  assert.equal(response.status, 503, "terminal chain failure surfaces the taxonomy error");
+  assert.equal(response.payload.error, "gateway_unavailable");
+  assert.equal(attempt, 2);
+  assert.equal(budget.status().tokensUsed, 100 + 80, "failed-attempt usage survives the terminal throw");
+});
+
+test("accounting: provider success followed by answer-validation failure → usage still charged", async () => {
+  const calls: MockChainCall[] = [];
+  const budget = new DailyBudget(10_000, 0, 0.5);
+  const evaluator = new Evaluator({
+    config: testConfig(),
+    singleFlight: new SingleFlight(4),
+    budget,
+    audit: noopAudit(),
+    // Provider-level success, but no answers → enforceAnswers must fail AFTER
+    // the provider tokens are charged.
+    chain: mockChain({ answers: {}, usage: USAGE_120, calls }) as never,
+  });
+  const response = await evaluator.handle(BODY);
+  assert.equal(response.status, 400);
+  assert.equal(response.payload.error, "validation_error");
+  assert.equal(calls.length, 1);
+  assert.equal(budget.status().tokensUsed, 120, "provider usage is charged even when validation rejects the verdict");
+});
+
+test("accounting: terminal chain error carries accumulated usage at the chain boundary", async () => {
+  const usage = { inputTokens: 50, outputTokens: 50, totalTokens: 100 };
+  const chain = new ProviderChain(
+    testRetryProviders(),
+    [
+      mockAdapter({
+        id: "typesafe-direct",
+        fail: () => new ProviderTransportError("gateway_unavailable", gatewayUnavailable("down"), usage),
+      }),
+    ],
+    fakeKeyReader(),
+  );
+  const request: TransportRequest = {
+    state: "s",
+    questions: [{ name: "q", kind: "boolean", question: "ok?", instructions: "" }],
+  };
+  await assert.rejects(
+    chain.evaluate(request, new AbortController().signal),
+    (error: unknown) => {
+      assert.ok(error instanceof ProviderChainError, "terminal failures travel as ProviderChainError");
+      assert.equal(error.failure.code, "gateway_unavailable");
+      assert.equal(error.failedAttemptUsage.length, 2);
+      assert.equal(
+        error.failedAttemptUsage.reduce((sum, entry) => sum + (entry.totalTokens ?? 0), 0),
+        200,
+      );
+      return true;
+    },
+  );
+});
+
+test("accounting: typesafe-direct is the sole adapter — no Vercel/Merge path exists", () => {
+  assert.deepEqual(
+    defaultAdapters().map((adapter) => adapter.id),
+    ["typesafe-direct"],
+  );
+});
+
+test("accounting: unconfigured TypeSafe fails closed with zero usage charged", async () => {
+  const calls: unknown[] = [];
+  const budget = new DailyBudget(10_000, 0, 0.5);
+  const chain = new ProviderChain(
+    testProviders(),
+    [mockAdapter({ id: "typesafe-direct", calls: calls as never })],
+    fakeKeyReader(new Set(["typesafe-ai"])),
+  );
+  const evaluator = new Evaluator({
+    config: testConfig(),
+    singleFlight: new SingleFlight(4),
+    budget,
+    audit: noopAudit(),
+    chain,
+  });
+  const response = await evaluator.handle(BODY);
+  assert.equal(response.status, 502);
+  assert.equal(response.payload.error, "model_unauthorized");
+  assert.equal(calls.length, 0, "fail-closed: no provider attempt without a credential");
+  assert.equal(budget.status().tokensUsed, 0);
+});

package/janus/tests/allowlist.test.ts

@@ -0,0 +1,97 @@
+// SPDX-FileCopyrightText: 2026 Julen Gamboa <j.a.r.gamboa@gmail.com>
+// SPDX-License-Identifier: AGPL-3.0-only
+
+// Unit tests: provider selection is configuration-only (M8, review fix #9) —
+// request-level model/provider overrides are REJECTED, not merely checked
+// against an allowlist. Unknown request fields are rejected (closed schema).
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { Evaluator } from "../janus/evaluate.js";
+import { SingleFlight } from "../janus/single_flight.js";
+import { DailyBudget } from "../janus/budget_breaker.js";
+import { AuditLog } from "../janus/audit.js";
+import { enforceRequest } from "../janus/schema.js";
+import { JanusError } from "../janus/errors.js";
+import { testConfig, mockChain } from "./helpers.js";
+
+function makeEvaluator() {
+  const auditEntries: unknown[] = [];
+  const audit = {
+    append: (entry: unknown) => auditEntries.push(entry),
+  } as unknown as AuditLog;
+  const evaluator = new Evaluator({
+    config: testConfig(),
+    singleFlight: new SingleFlight(4),
+    budget: new DailyBudget(0, 0, 0.5),
+    audit,
+    chain: mockChain({ answers: { q: { type: "boolean", probability: 0.95 } } }) as never,
+  });
+  return { evaluator, auditEntries };
+}
+
+test("request without model/provider fields is accepted", async () => {
+  const { evaluator } = makeEvaluator();
+  const response = await evaluator.handle({
+    state: "s",
+    questions: [{ type: "boolean", name: "q", question: "ok?" }],
+  });
+  assert.equal(response.status, 200);
+  assert.equal(response.payload.provider, "typesafe-direct");
+});
+
+test("request-level model override is REJECTED (validation_error, not allowlist check)", async () => {
+  const { evaluator } = makeEvaluator();
+  for (const model of ["openai/gpt-5", "jev-latest", "typesafe-ai/jev"]) {
+    const response = await evaluator.handle({
+      state: "s",
+      model,
+      questions: [{ type: "boolean", name: "q", question: "ok?" }],
+    });
+    assert.equal(response.status, 400, `model ${model} must be rejected`);
+    assert.equal(response.payload.error, "validation_error");
+    assert.match(String(response.payload.message), /unknown request field/);
+  }
+});
+
+test("request-level provider override is REJECTED", async () => {
+  const { evaluator } = makeEvaluator();
+  const response = await evaluator.handle({
+    state: "s",
+    provider: "acme-gateway",
+    questions: [{ type: "boolean", name: "q", question: "ok?" }],
+  });
+  assert.equal(response.status, 400);
+  assert.equal(response.payload.error, "validation_error");
+});
+
+test("any other unknown request field is rejected (closed schema, review fix #9)", async () => {
+  const { evaluator } = makeEvaluator();
+  for (const field of ["apiKey", "maxTokens", "temperature", "stream", "criteria"]) {
+    const response = await evaluator.handle({
+      state: "s",
+      [field]: "x",
+      questions: [{ type: "boolean", name: "q", question: "ok?" }],
+    });
+    assert.equal(response.status, 400);
+    assert.equal(response.payload.error, "validation_error");
+  }
+});
+
+test("schema enforcement rejects unknown per-question fields", () => {
+  assert.throws(
+    () =>
+      enforceRequest({
+        state: "s",
+        questions: [{ type: "boolean", name: "q", question: "ok?", apiKey: "x" }],
+      }),
+    (error: unknown) => error instanceof JanusError && error.code === "validation_error",
+  );
+});
+
+test("schema enforcement rejects unknown top-level fields", () => {
+  assert.throws(
+    () => enforceRequest({ state: "s", model: "m", questions: [{ type: "boolean", name: "q", question: "ok?" }] }),
+    (error: unknown) => error instanceof JanusError && error.code === "validation_error",
+  );
+});

package/janus/tests/config.test.ts

@@ -0,0 +1,151 @@
+// SPDX-FileCopyrightText: 2026 Julen Gamboa <j.a.r.gamboa@gmail.com>
+// SPDX-License-Identifier: AGPL-3.0-only
+
+// Unit tests: closed config validation (review fix #9) — unknown fields and
+// invalid values are rejected, never defaulted silently; caps are enforced
+// (request budget <= 30k, max concurrency <= 4, redaction immutable-on).
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { loadConfig } from "../janus/config.js";
+import { writeFileSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+function configWith(overrides: Record<string, unknown>): string {
+  const dir = mkdtempSync(join(tmpdir(), "janus-config-test-"));
+  const path = join(dir, "janus-config.json");
+  writeFileSync(path, JSON.stringify(overrides));
+  return path;
+}
+
+function expectConfigError(path: string, fragment?: string | RegExp): void {
+  assert.throws(
+    () => loadConfig(path),
+    (error: unknown) => {
+      const message = error instanceof Error ? error.message : String(error);
+      if (fragment) {
+        if (typeof fragment === "string") assert.match(message, new RegExp(fragment));
+        else assert.match(message, fragment);
+      }
+      return /config invalid/.test(message);
+    },
+  );
+}
+
+test("default config: sole typesafe-direct provider, 30k budget, redaction on", () => {
+  const dir = mkdtempSync(join(tmpdir(), "janus-config-test-"));
+  try {
+    const { config, warnings } = loadConfig(join(dir, "missing.json"));
+    assert.equal(config.providers[0]!.id, "typesafe-direct");
+    assert.deepEqual(config.providers[0]!.keychain, { account: "typesafe-ai", service: "Typesafe AI" });
+    assert.equal(config.providers.length, 1, "the fallback providers are dropped");
+    assert.equal(config.requestBudgetTokens, 30_000);
+    assert.equal(config.maxConcurrent, 4);
+    assert.equal(config.redactSecrets, true);
+    assert.equal(config.defaultModel, "jev-latest");
+    assert.ok(warnings.length > 0, "missing file is a warning, not an error");
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("unknown top-level fields are rejected (review fix #9)", () => {
+  expectConfigError(configWith({ modelAllowlist: ["x"] }), /unknown config field/);
+  expectConfigError(configWith({ keychainService: "x" }), /unknown config field/);
+  expectConfigError(configWith({ maxTokens: 5 }), /unknown config field/);
+  expectConfigError(configWith({ redaction: "off" }), /unknown config field/);
+});
+
+test("unknown audit fields are rejected", () => {
+  expectConfigError(configWith({ audit: { path: "stdout", retentionDays: 1, extra: true } }), /audit\.extra/);
+});
+
+test("invalid values are rejected, not defaulted silently (review fix #9)", () => {
+  expectConfigError(configWith({ port: "http" }));
+  expectConfigError(configWith({ port: 99_999 }));
+  expectConfigError(configWith({ timeoutMs: 0 }));
+  expectConfigError(configWith({ maxConcurrent: 1.5 }));
+  expectConfigError(configWith({ requestBudgetTokens: -5 }));
+  expectConfigError(configWith({ audit: { retentionDays: "soon" } }));
+});
+
+test("request budget cannot be raised above 30,000 (review fix #3/#9)", () => {
+  expectConfigError(configWith({ requestBudgetTokens: 30_001 }), /hard ceiling/);
+  expectConfigError(configWith({ requestBudgetTokens: 1_000_000 }), /hard ceiling/);
+  const ok = loadConfig(configWith({ requestBudgetTokens: 29_999 }));
+  assert.equal(ok.config.requestBudgetTokens, 29_999);
+});
+
+test("max concurrency cannot be raised above 4 (review fix #9)", () => {
+  expectConfigError(configWith({ maxConcurrent: 5 }), /hard ceiling/);
+  const ok = loadConfig(configWith({ maxConcurrent: 2 }));
+  assert.equal(ok.config.maxConcurrent, 2);
+});
+
+test("timeout cannot be raised above 30s (review fix #9)", () => {
+  expectConfigError(configWith({ timeoutMs: 31_000 }), /hard ceiling/);
+});
+
+test("redaction is immutable-on: redactSecrets: false is rejected (review fix #4/#9)", () => {
+  expectConfigError(configWith({ redactSecrets: false }), /redaction is always on/);
+  const ok = loadConfig(configWith({ redactSecrets: true }));
+  assert.equal(ok.config.redactSecrets, true);
+});
+
+test("provider entries are validated closed (review fix #2)", () => {
+  expectConfigError(configWith({ providers: [{ id: "acme", model: "m", keychain: { account: "a", service: "s" } }] }), /providers\[0\]\.id/);
+  // The fallback gateways are DROPPED: their ids are not valid configuration.
+  expectConfigError(configWith({ providers: [{ id: "vercel-ai-gateway", model: "m", keychain: { account: "a", service: "s" } }] }), /providers\[0\]\.id/);
+  expectConfigError(configWith({ providers: [{ id: "merge-gateway", model: "m", keychain: { account: "a", service: "s" } }] }), /providers\[0\]\.id/);
+  expectConfigError(configWith({ providers: [{ id: "typesafe-direct", model: "", keychain: { account: "a", service: "s" } }] }), /model/);
+  expectConfigError(configWith({ providers: [{ id: "typesafe-direct", model: "m", keychain: { account: "a" } }] }), /keychain\.service/);
+  expectConfigError(configWith({ providers: [{ id: "typesafe-direct", model: "m", keychain: { account: "a", service: "s", apiKey: "x" } }] }), /unknown field/);
+  expectConfigError(configWith({ providers: [] }), /nonempty array/);
+  expectConfigError(
+    configWith({
+      providers: [
+        { id: "typesafe-direct", model: "m", keychain: { account: "a", service: "s" } },
+        { id: "typesafe-direct", model: "m2", keychain: { account: "a", service: "s" } },
+      ],
+    }),
+    /at most one provider entry is valid/,
+  );
+});
+
+test("valid custom provider chain loads; defaultModel must match a provider model", () => {
+  const ok = loadConfig(
+    configWith({
+      providers: [
+        { id: "typesafe-direct", model: "jev-latest", keychain: { account: "typesafe-ai", service: "Typesafe AI" } },
+      ],
+      defaultModel: "jev-latest",
+    }),
+  );
+  assert.equal(ok.config.defaultModel, "jev-latest");
+  expectConfigError(
+    configWith({
+      providers: [
+        { id: "typesafe-direct", model: "jev-latest", keychain: { account: "a", service: "s" } },
+      ],
+      defaultModel: "other-model",
+    }),
+    /defaultModel/,
+  );
+});
+
+test("malformed config JSON is an error, not a silent default", () => {
+  const dir = mkdtempSync(join(tmpdir(), "janus-config-test-"));
+  const path = join(dir, "bad.json");
+  writeFileSync(path, "{not json");
+  expectConfigError(path, /failed to parse/);
+  rmSync(dir, { recursive: true, force: true });
+});
+
+test("non-object config JSON is an error", () => {
+  const dir = mkdtempSync(join(tmpdir(), "janus-config-test-"));
+  const path = join(dir, "array.json");
+  writeFileSync(path, "[1,2,3]");
+  expectConfigError(path);
+  rmSync(dir, { recursive: true, force: true });
+});

package/janus/tests/errors.test.ts

@@ -0,0 +1,147 @@
+// SPDX-FileCopyrightText: 2026 Julen Gamboa <j.a.r.gamboa@gmail.com>
+// SPDX-License-Identifier: AGPL-3.0-only
+
+// Unit tests: the §5 error taxonomy — callers must distinguish "model
+// returned false" (200) from "no verdict" (timeout/gateway_unavailable) from
+// "bad request" (validation_error) — plus provider error classification with
+// FIXED public messages (review fix #5).
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import {
+  APIError,
+  APIConnectionError,
+  APITimeoutError,
+  APIUserAbortError,
+  TypeSafeError,
+} from "@typesafe-ai/sdk";
+import {
+  JanusError,
+  busyError,
+  gatewayUnavailable,
+  timeoutError,
+  validationError,
+} from "../janus/errors.js";
+import {
+  classifyGatewayError,
+  classifyTypesafeError,
+  ProviderTransportError,
+} from "../janus/providers.js";
+
+test("taxonomy codes are exactly the §5 set", () => {
+  const codes: JanusError["code"][] = [
+    "validation_error",
+    "state_too_large",
+    "unknown_question",
+    "model_unauthorized",
+    "gateway_unavailable",
+    "timeout",
+    "busy",
+    "degraded",
+  ];
+  for (const code of codes) {
+    const error = new JanusError(code, "message", 400);
+    assert.equal(error.code, code);
+    const body = error.body("req-1");
+    assert.deepEqual(
+      { error: body.error, message: body.message, request_id: body.request_id },
+      { error: code, message: "message", request_id: "req-1" },
+    );
+  }
+});
+
+test("error body shape is {error, message, request_id} with optional detail", () => {
+  const plain = validationError("bad").body("r1");
+  assert.deepEqual(plain, { error: "validation_error", message: "bad", request_id: "r1" });
+  const detailed = busyError("cap", { budget_exhausted: { kind: "tokens" } }).body("r2");
+  assert.deepEqual(detailed.detail, { budget_exhausted: { kind: "tokens" } });
+});
+
+test("status mapping separates classes", () => {
+  assert.equal(validationError("x").status, 400);
+  assert.equal(busyError("x").status, 429);
+  assert.equal(timeoutError("x").status, 504);
+  assert.equal(gatewayUnavailable("x").status, 503);
+});
+
+function apiError(status: number, body: unknown): APIError {
+  return APIError.fromResponse(status, body, new Headers());
+}
+
+test("typesafe classification: abort → timeout with fixed message", () => {
+  const failure = classifyTypesafeError(new APIUserAbortError());
+  assert.equal(failure.failure.error.code, "timeout");
+  assert.equal(failure.failure.error.message, "evaluation timed out");
+  // Timeout is a transport failure: eligible for the single failover to the
+  // NEXT provider, never retried in place on the same one.
+  assert.equal(failure.failure.failoverEligible, true);
+});
+
+test("typesafe classification: connection/timeout errors → gateway_unavailable, failover eligible", () => {
+  for (const error of [new APIConnectionError("dns broke"), new APITimeoutError(1000)]) {
+    const failure = classifyTypesafeError(error);
+    assert.equal(failure.failure.error.code, "gateway_unavailable");
+    assert.equal(failure.failure.failoverEligible, true);
+  }
+});
+
+test("typesafe classification: 401/403 → model_unauthorized, failover eligible", () => {
+  for (const status of [401, 403]) {
+    const failure = classifyTypesafeError(apiError(status, {}));
+    assert.equal(failure.failure.error.code, "model_unauthorized");
+    assert.equal(failure.failure.failoverEligible, true);
+  }
+});
+
+test("typesafe classification: 429/404/5xx → gateway_unavailable, failover eligible", () => {
+  for (const status of [429, 404, 500, 503]) {
+    const failure = classifyTypesafeError(apiError(status, {}));
+    assert.equal(failure.failure.error.code, "gateway_unavailable");
+    assert.equal(failure.failure.failoverEligible, true);
+  }
+});
+
+test("typesafe classification: client-side TypeSafeError fails closed as unavailable", () => {
+  const failure = classifyTypesafeError(new TypeSafeError("bad criteria shape"));
+  assert.equal(failure.failure.error.code, "gateway_unavailable");
+});
+
+test("gateway classification: abort → timeout; network → unavailable; auth → unauthorized", () => {
+  const abortError = new Error("Request aborted");
+  abortError.name = "AbortError";
+  assert.equal(classifyGatewayError(abortError).failure.error.code, "timeout");
+  assert.equal(
+    classifyGatewayError(new Error("fetch failed: ECONNREFUSED")).failure.error.code,
+    "gateway_unavailable",
+  );
+  assert.equal(
+    classifyGatewayError(new Error("401 Unauthorized: invalid api key")).failure.error.code,
+    "model_unauthorized",
+  );
+  assert.equal(classifyGatewayError(new Error("429 rate limit exceeded")).failure.error.code, "gateway_unavailable");
+});
+
+test("public messages never contain provider/SDK/internal error text (review fix #5)", () => {
+  const sensitive = "sk-live-abcdef0123456789 internal stack detail";
+  const errors: unknown[] = [
+    apiError(500, { message: sensitive }),
+    new APIConnectionError(sensitive),
+    new TypeSafeError(sensitive),
+    new Error(sensitive),
+  ];
+  for (const error of errors) {
+    const classified = error instanceof TypeSafeError && !(error instanceof APIError)
+      ? classifyTypesafeError(error)
+      : classifyTypesafeError(error);
+    const message = classified.failure.error.message;
+    assert.ok(!message.includes(sensitive), `message must be fixed, got: ${message}`);
+    assert.ok(!/sk-/.test(message));
+  }
+});
+
+test("ProviderTransportError preserves classification and is idempotent", () => {
+  const first = classifyTypesafeError(apiError(429, {}));
+  assert.ok(first instanceof ProviderTransportError);
+  const again = classifyTypesafeError(first);
+  assert.equal(again, first, "re-classifying a ProviderTransportError returns it unchanged");
+});