CI (SIAX Cloud) / security (push) Successful in 41s
Security Scan (SIAX Cloud) / security (push) Successful in 40s
CI (SIAX Cloud) / integration (push) Successful in 52s
CI (SIAX Cloud) / quality (push) Successful in 1m5s
CI (SIAX Cloud) / security (pull_request) Successful in 31s
Security Scan (SIAX Cloud) / security (pull_request) Successful in 29s
CI (SIAX Cloud) / integration (pull_request) Successful in 45s
CI (SIAX Cloud) / quality (pull_request) Successful in 53s
Implements the eight BI program prompts that make 0pt the canonical SIAX
analytics capability. Every file is NEW: not one existing file is modified,
and src/analytics/clickhouse-analytics.ts is byte-identical to main.
BI-P002 — the nineteen canonical entities, verbatim, with tenant_id +
project_id on every tenant-owned record. sql/008 gives each one a table.
The four version entities BI-P002 names as immutable are enforced by BEFORE
UPDATE/DELETE triggers, not by a TypeScript `readonly` — proven by direct SQL
against a live Postgres.
BI-P003 — RAW/NORMALIZED/CURATED/SERVING with the read rule enforced:
assertReadableByBiSurface refuses a RAW dataset to a dashboard unless a
recorded exception exists. All eight required declarations are NOT NULL.
BI-P004 — DatasetContract and a fail-closed compatibility gate. Fifteen
breaking-change classes are each tested twice: refused under a minor bump,
accepted under a major one.
BI-P005 — Arrow IPC alongside JSON, with a hand-written FlatBuffers writer so
no npm dependency (or CVE surface) is added. Conformance comes from three
independent implementations, not from self-agreement: pyarrow 25.0.1 and
DuckDB 1.5.5 read identical values from both ClickHouse's Arrow and ours, and
ClickHouse's own Arrow C++ ingests our 20,000-row batch with exact aggregates.
BI-P009 — SiaxAnalyticsEngine with all eight capabilities. The existing
ClickHouseAnalytics is COMPOSED, never replaced. executeQuery (analyst SQL) is
declared and deliberately refused with CAPABILITY_UNAVAILABLE until BI-P017 and
BI-P033 land, rather than opening the raw-SQL hole BI-P011 enumerates.
BI-P010 — four purpose-built tables, not one giant one, and the difference is
measured against the counterfactual: 48.8ms/40,960 rows vs 174.4ms/5,400,000
rows for the same question; 5/660 granules vs 660/1149.
BI-P011 — layered isolation, each layer proven with the layer above removed.
Without the forced predicate the same statement returns 50,050 (both tenants);
with it, t_alpha gets 50. Without a row policy an unrestricted user sees 2
tenants; the restricted user running the IDENTICAL statement sees 1.
BI-P012 — every named limit, fired individually and identified by ClickHouse
error code, plus the half usually skipped: an unrelated tenant is timed while
a real CPU bomb is in flight and must still return the CORRECT answer.
Three defects found by writing tests that can fail:
* `CHECK (array_length(purposes,1) >= 1)` can NEVER fail — array_length is
NULL for '{}' and a NULL CHECK passes. Fixed with coalesce(); the test
that caught it is pinned.
* EXPLAIN ESTIMATE run under the caller's own max_rows_to_read fails with
code 158 exactly when the estimate would be over budget. Planner calls now
use a narrower envelope.
* result_overflow_mode=break returns HTTP 200 with 65,409 of 100,000 rows
and no indication it is short. Every SELECT ships `throw`.
Verified rather than assumed: server7's ClickHouse holds `opt_scraped` (51
tables, 407,793,471 rows, `persons`/`cz_owners` included) — the b0ts plane this
module is prohibited from touching — has no `opt_analytics` database, zero
tenant_id columns and zero row policies. Nothing there was modified; every
proof ran against disposable containers.
Evidence: evidence/bi-p002-p012/{test-transcript.txt,bi-p010-benchmark.json,
bi-p005-arrow-roundtrip.json,server7-clickhouse-probe.md}
Docs: docs/analytics/BI_ANALYTICS_CORE.md
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
190 lines
7.3 KiB
TypeScript
190 lines
7.3 KiB
TypeScript
/**
|
|
* BI-P002 (domain model) + BI-P003 (data tiers), the parts provable without
|
|
* infrastructure. The Postgres half — real tables, real immutability
|
|
* triggers, real tenant scoping — is
|
|
* tests/analytics/analytics-domain-postgres.realinfra.test.ts.
|
|
*
|
|
* The registry-vs-migration test below is the one that earns its place: it
|
|
* reads sql/008_analytics_domain_model.sql from disk and asserts a CREATE
|
|
* TABLE exists for every one of the nineteen canonical entities. A future
|
|
* rename, or an entity quietly dropped from the migration, fails HERE rather
|
|
* than at 3am against a database that turns out to be missing a table.
|
|
*/
|
|
import { describe, it, expect } from "vitest";
|
|
import fs from "node:fs";
|
|
import path from "node:path";
|
|
import {
|
|
ANALYTICS_DOMAIN_ENTITIES,
|
|
ANALYTICS_ENTITY_TABLES,
|
|
IMMUTABLE_VERSION_ENTITIES,
|
|
} from "@/src/analytics/domain/entities";
|
|
import {
|
|
ANALYTICS_TIERS,
|
|
assertReadableByBiSurface,
|
|
assertTierLineageSane,
|
|
BI_READABLE_TIERS,
|
|
isAnalyticsTier,
|
|
TIER_RANK,
|
|
} from "@/src/analytics/domain/tiers";
|
|
|
|
const MIGRATION = fs.readFileSync(
|
|
path.join(process.cwd(), "sql", "008_analytics_domain_model.sql"),
|
|
"utf8",
|
|
);
|
|
|
|
describe("BI-P002 canonical entity set", () => {
|
|
it("lists exactly the nineteen entities the program names, verbatim", () => {
|
|
expect(ANALYTICS_DOMAIN_ENTITIES).toEqual([
|
|
"AnalyticsDataset",
|
|
"DatasetVersion",
|
|
"DatasetField",
|
|
"DatasetGrant",
|
|
"MetricDefinition",
|
|
"MetricVersion",
|
|
"DimensionDefinition",
|
|
"SemanticModel",
|
|
"AnalyticsQuery",
|
|
"QueryExecution",
|
|
"QueryResult",
|
|
"DashboardDefinition",
|
|
"DashboardVersion",
|
|
"ReportDefinition",
|
|
"ReportRun",
|
|
"DataQualityRule",
|
|
"DataQualityRun",
|
|
"LineageReference",
|
|
"BIApplicationBinding",
|
|
]);
|
|
expect(ANALYTICS_DOMAIN_ENTITIES).toHaveLength(19);
|
|
});
|
|
|
|
it("sql/008 defines a table for every entity (no entity is a type without storage)", () => {
|
|
const missing: string[] = [];
|
|
for (const entity of ANALYTICS_DOMAIN_ENTITIES) {
|
|
const table = ANALYTICS_ENTITY_TABLES[entity];
|
|
if (!new RegExp(`CREATE TABLE IF NOT EXISTS ${table}\\b`).test(MIGRATION)) {
|
|
missing.push(`${entity} -> ${table}`);
|
|
}
|
|
}
|
|
expect(missing).toEqual([]);
|
|
});
|
|
|
|
it("every tenant-owned table carries tenant_id AND project_id", () => {
|
|
// Split on the table definitions and check each block.
|
|
const blocks = MIGRATION.split(/CREATE TABLE IF NOT EXISTS /).slice(1);
|
|
const offenders: string[] = [];
|
|
for (const block of blocks) {
|
|
const name = block.split(/[\s(]/)[0];
|
|
if (!Object.values(ANALYTICS_ENTITY_TABLES).includes(name)) continue;
|
|
const body = block.slice(0, block.indexOf(");"));
|
|
if (!/\btenant_id TEXT NOT NULL\b/.test(body) || !/\bproject_id TEXT NOT NULL\b/.test(body)) {
|
|
offenders.push(name);
|
|
}
|
|
}
|
|
expect(offenders).toEqual([]);
|
|
});
|
|
|
|
it("the four immutable version entities have a BEFORE UPDATE OR DELETE trigger in sql/008", () => {
|
|
expect(IMMUTABLE_VERSION_ENTITIES).toEqual([
|
|
"DatasetVersion",
|
|
"MetricVersion",
|
|
"SemanticModel",
|
|
"DashboardVersion",
|
|
]);
|
|
for (const entity of IMMUTABLE_VERSION_ENTITIES) {
|
|
const table = ANALYTICS_ENTITY_TABLES[entity];
|
|
expect(
|
|
new RegExp(`BEFORE UPDATE OR DELETE ON ${table}\\b`).test(MIGRATION),
|
|
`${entity} (${table}) has no immutability trigger`,
|
|
).toBe(true);
|
|
}
|
|
});
|
|
|
|
it("BIApplicationBinding storage carries NO credential column — the ownership boundary is structural", () => {
|
|
const block = MIGRATION.split("CREATE TABLE IF NOT EXISTS opt_analytics_bi_application_binding")[1] ?? "";
|
|
const body = block.slice(0, block.indexOf(");"));
|
|
for (const forbidden of ["password", "dsn", "secret", "connection_string", "clickhouse_url", "token"]) {
|
|
expect(body.toLowerCase()).not.toContain(forbidden);
|
|
}
|
|
});
|
|
|
|
it("sql/008 is idempotent-shaped: every CREATE is IF NOT EXISTS / OR REPLACE", () => {
|
|
const creates = MIGRATION.match(/^CREATE (TABLE|INDEX|TRIGGER|FUNCTION|OR REPLACE FUNCTION)[^\n]*/gm) ?? [];
|
|
const nonIdempotent = creates.filter(
|
|
(line) => !/IF NOT EXISTS/.test(line) && !/OR REPLACE/.test(line) && !/^CREATE TRIGGER/.test(line),
|
|
);
|
|
expect(nonIdempotent).toEqual([]);
|
|
// Triggers cannot take IF NOT EXISTS in Postgres, so each one must be
|
|
// preceded by a DROP TRIGGER IF EXISTS to stay replayable.
|
|
const triggers = MIGRATION.match(/^CREATE TRIGGER (\w+)/gm) ?? [];
|
|
for (const t of triggers) {
|
|
const name = t.replace("CREATE TRIGGER ", "");
|
|
expect(MIGRATION).toContain(`DROP TRIGGER IF EXISTS ${name}`);
|
|
}
|
|
});
|
|
});
|
|
|
|
describe("BI-P003 analytics data tiers", () => {
|
|
it("canonicalizes exactly RAW / NORMALIZED / CURATED / SERVING", () => {
|
|
expect(ANALYTICS_TIERS).toEqual(["RAW", "NORMALIZED", "CURATED", "SERVING"]);
|
|
expect(isAnalyticsTier("CURATED")).toBe(true);
|
|
expect(isAnalyticsTier("raw")).toBe(false);
|
|
expect(isAnalyticsTier("BRONZE")).toBe(false);
|
|
});
|
|
|
|
it("no business dashboard reads a RAW/NORMALIZED dataset by default", () => {
|
|
expect(BI_READABLE_TIERS).toEqual(["SERVING", "CURATED"]);
|
|
for (const tier of ["RAW", "NORMALIZED"] as const) {
|
|
expect(() =>
|
|
assertReadableByBiSurface({ dataset_id: "ds_1", tier }, "dashboard:exec-overview"),
|
|
).toThrowError(/may not read/);
|
|
}
|
|
for (const tier of ["SERVING", "CURATED"] as const) {
|
|
expect(() => assertReadableByBiSurface({ dataset_id: "ds_1", tier }, "dashboard:x")).not.toThrow();
|
|
}
|
|
});
|
|
|
|
it("a recorded exception is the only way a RAW dataset reaches a BI surface", () => {
|
|
expect(() =>
|
|
assertReadableByBiSurface(
|
|
{ dataset_id: "ds_1", tier: "RAW", raw_access_exception: "INC-2026-09-06 forensic review, expires 2026-10-01" },
|
|
"dashboard:incident",
|
|
),
|
|
).not.toThrow();
|
|
// An empty/whitespace "exception" is not an exception.
|
|
expect(() =>
|
|
assertReadableByBiSurface({ dataset_id: "ds_1", tier: "RAW", raw_access_exception: " " }, "dashboard:x"),
|
|
).toThrowError(/may not read/);
|
|
});
|
|
|
|
it("tier order is enforced: a CURATED dataset cannot be built from SERVING", () => {
|
|
expect(TIER_RANK.RAW).toBeLessThan(TIER_RANK.NORMALIZED);
|
|
expect(TIER_RANK.NORMALIZED).toBeLessThan(TIER_RANK.CURATED);
|
|
expect(TIER_RANK.CURATED).toBeLessThan(TIER_RANK.SERVING);
|
|
expect(() => assertTierLineageSane("CURATED", "SERVING")).toThrowError(/tier order/);
|
|
expect(() => assertTierLineageSane("SERVING", "CURATED")).not.toThrow();
|
|
expect(() => assertTierLineageSane("CURATED", "CURATED")).not.toThrow();
|
|
});
|
|
|
|
it("sql/008 constrains tier at the DATABASE level, not only in TypeScript", () => {
|
|
expect(MIGRATION).toContain("CHECK (tier IN ('RAW','NORMALIZED','CURATED','SERVING'))");
|
|
});
|
|
|
|
it("BI-P003's eight required declarations are all NOT NULL in sql/008", () => {
|
|
const block = MIGRATION.split("CREATE TABLE IF NOT EXISTS opt_analytics_dataset ")[1] ?? "";
|
|
const body = block.slice(0, block.indexOf(");"));
|
|
for (const col of [
|
|
"tier",
|
|
"schema_contract_id",
|
|
"owner_id",
|
|
"source_ref",
|
|
"freshness_slo_seconds",
|
|
"retention_days",
|
|
"classification",
|
|
"quality_rule_ids",
|
|
]) {
|
|
expect(new RegExp(`\\b${col}\\b[^,]*NOT NULL`).test(body), `${col} is nullable`).toBe(true);
|
|
}
|
|
});
|
|
});
|