0pt/tests/analytics/analytics-engine-contract.test.ts

/**
 * BI-P009 DoD: "Provider contract tests added."
 *
 * This is the contract every `SiaxAnalyticsEngine` provider must satisfy
 * regardless of engine — ClickHouse today, DuckDB (BI-P014) and Trino
 * (BI-P015) later. It is written against the INTERFACE, so a future provider
 * imports `analyticsEngineContract` and gets the same bar.
 *
 * The identity rules here are the ones that matter most: this estate has
 * already shipped a live cross-tenant hole by reading the tenant out of a
 * REQUEST BODY (INF0 Wave 2). So the contract asserts that a request field
 * named `tenant_id` cannot influence the engine at all.
 */
import { describe, it, expect } from "vitest";
import { ClickHouseAnalyticsEngine } from "@/src/analytics/engine/clickhouse-engine";
import {
  SIAX_ANALYTICS_ENGINE_CAPABILITIES,
  type AnalyticsIdentity,
  type SiaxAnalyticsEngine,
} from "@/src/analytics/engine/siax-analytics-engine";

const IDENTITY: AnalyticsIdentity = {
  tenant_id: "t_alpha",
  project_id: "p_default",
  principal_id: "usr_1",
};

/** Reusable contract suite — future providers call this with their factory. */
export function analyticsEngineContract(name: string, make: () => SiaxAnalyticsEngine): void {
  describe(`SiaxAnalyticsEngine contract: ${name}`, () => {
    it("implements all eight BI-P009 capabilities as callable methods", () => {
      const engine = make() as unknown as Record<string, unknown>;
      for (const cap of SIAX_ANALYTICS_ENGINE_CAPABILITIES) {
        expect(typeof engine[cap], `${cap} is not a method`).toBe("function");
      }
      expect(SIAX_ANALYTICS_ENGINE_CAPABILITIES).toEqual([
        "health",
        "executeMetric",
        "executeQuery",
        "estimateQuery",
        "cancelQuery",
        "explain",
        "ingestProjection",
        "refreshProjection",
      ]);
    });

    it("names its provider", () => {
      expect(make().provider.length).toBeGreaterThan(0);
    });

    it("refuses every tenant-scoped capability without a verified identity", async () => {
      const engine = make();
      const blank = { tenant_id: "", project_id: "p", principal_id: "usr_1" };
      const noPrincipal = { tenant_id: "t_alpha", project_id: "p", principal_id: "" };
      for (const bad of [blank, noPrincipal]) {
        await expect(engine.executeMetric(bad, { metric: "m", aggregate: "sum" })).rejects.toMatchObject({
          code: "UNAUTHENTICATED",
        });
        await expect(engine.estimateQuery(bad, { metric: "m", aggregate: "sum" })).rejects.toMatchObject({
          code: "UNAUTHENTICATED",
        });
        await expect(engine.ingestProjection(bad, { dataset_id: "ds", rows: [] })).rejects.toMatchObject({
          code: "UNAUTHENTICATED",
        });
        await expect(engine.refreshProjection(bad, "ds")).rejects.toMatchObject({ code: "UNAUTHENTICATED" });
        await expect(engine.cancelQuery(bad, "q")).rejects.toMatchObject({ code: "UNAUTHENTICATED" });
      }
    });

    it("a tenant_id smuggled into the REQUEST cannot influence the engine (INF0 Wave-2 bug class)", async () => {
      const engine = make();
      const smuggled = { metric: "m", aggregate: "sum", tenant_id: "t_victim" } as never;
      // The request type has no tenant field; if a provider ever started
      // reading one, this call would target t_victim. The engine must still
      // fail on the IDENTITY, proving the request field is inert.
      await expect(
        engine.executeMetric({ tenant_id: "", project_id: "p", principal_id: "u" }, smuggled),
      ).rejects.toMatchObject({ code: "UNAUTHENTICATED" });
    });

    it("cancelQuery refuses a query id belonging to another tenant", async () => {
      const engine = make();
      await expect(engine.cancelQuery(IDENTITY, "opt_deadbeefdead_someoneelses")).rejects.toMatchObject({
        code: "AUTHORIZATION_DENIED",
      });
    });

    it("health() reports unhealthy rather than throwing when the engine is unreachable", async () => {
      const report = await make().health();
      expect(report.healthy).toBe(false);
      expect(report.provider.length).toBeGreaterThan(0);
      // Never leak an engine body or a DSN into the operator-facing detail.
      expect(report.detail ?? "").not.toMatch(/http|password|@/i);
    });
  });
}

analyticsEngineContract(
  "clickhouse (unreachable host — contract-level assertions only)",
  () =>
    new ClickHouseAnalyticsEngine({
      baseUrl: "http://clickhouse.invalid:8123",
      database: "opt_contract_test",
      timeoutMs: 500,
    }),
);

describe("BI-P009 refusals that are deliberate, not missing", () => {
  it("executeQuery (analyst SQL) is declared and REFUSED until BI-P017/BI-P033", async () => {
    const engine = new ClickHouseAnalyticsEngine({ baseUrl: "http://clickhouse.invalid:8123" });
    await expect(engine.executeQuery(IDENTITY, { sql: "SELECT 1", dataset_ids: [] })).rejects.toMatchObject({
      code: "CAPABILITY_UNAVAILABLE",
    });
  });

  it("the PRESERVED ClickHouseAnalytics is reachable through the engine, not replaced by it", () => {
    const engine = new ClickHouseAnalyticsEngine({ baseUrl: "http://clickhouse.invalid:8123" });
    expect(engine.legacyAnalytics.constructor.name).toBe("ClickHouseAnalytics");
    expect(typeof engine.legacyAnalytics.queryMetric).toBe("function");
    expect(typeof engine.legacyAnalytics.ensureSchema).toBe("function");
    expect(typeof engine.legacyAnalytics.ingest).toBe("function");
  });
});