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>
165 lines
8.4 KiB
TypeScript
165 lines
8.4 KiB
TypeScript
/**
|
|
* BI-P004 — ANALYTICS DATA CONTRACT.
|
|
*
|
|
* DoD: "Breaking dataset schema changes fail compatibility gate unless
|
|
* explicitly versioned." Each breaking change class below is tested TWICE:
|
|
* once under a minor bump (must be REFUSED) and once under a major bump (must
|
|
* be ACCEPTED). A gate that only ever says yes, or only ever says no, would
|
|
* pass a one-sided test; this one cannot.
|
|
*/
|
|
import { describe, it, expect } from "vitest";
|
|
import {
|
|
assertContractCompatible,
|
|
checkContractCompatibility,
|
|
contractHash,
|
|
diffContracts,
|
|
parseSemVer,
|
|
validateContract,
|
|
type DatasetContract,
|
|
} from "@/src/analytics/domain/contract";
|
|
|
|
function base(): DatasetContract {
|
|
return {
|
|
dataset_id: "ds_vehicle_listings",
|
|
version: "1.2.0",
|
|
tier: "CURATED",
|
|
fields: [
|
|
{ name: "listing_id", type: "string", nullable: false, role: "identifier", primary_identifier: true },
|
|
{ name: "make", type: "string", nullable: false, role: "dimension" },
|
|
{ name: "asking_price", type: "int64", nullable: true, role: "measure" },
|
|
{ name: "listed_at", type: "timestamp", nullable: false, role: "attribute" },
|
|
],
|
|
primary_identifiers: ["listing_id"],
|
|
dimensions: ["make"],
|
|
measures: ["asking_price"],
|
|
freshness_slo_seconds: 3600,
|
|
retention_days: 730,
|
|
pii_classification: "none",
|
|
source_lineage: ["src_dealer_feed"],
|
|
quality_rules: [{ rule_id: "qr_listing_id_unique", kind: "unique", field_name: "listing_id", severity: "block" }],
|
|
allowed_purposes: ["market_analytics"],
|
|
};
|
|
}
|
|
|
|
/** Apply a mutation and set the version. */
|
|
function next(mutate: (c: DatasetContract) => void, version: string): DatasetContract {
|
|
const c: DatasetContract = JSON.parse(JSON.stringify(base()));
|
|
mutate(c);
|
|
c.version = version;
|
|
return c;
|
|
}
|
|
|
|
const BREAKING_CASES: { name: string; mutate: (c: DatasetContract) => void; code: string }[] = [
|
|
{ name: "field removed", mutate: (c) => { c.fields = c.fields.filter((f) => f.name !== "make"); c.dimensions = []; }, code: "field_removed" },
|
|
{ name: "field type changed", mutate: (c) => { c.fields[2].type = "float64"; }, code: "field_type_changed" },
|
|
{ name: "field became nullable", mutate: (c) => { c.fields[1].nullable = true; }, code: "field_became_nullable" },
|
|
{ name: "field role changed", mutate: (c) => { c.fields[1].role = "measure"; }, code: "field_role_changed" },
|
|
{ name: "required field added", mutate: (c) => { c.fields.push({ name: "vat_rate", type: "float64", nullable: false, role: "attribute" }); }, code: "required_field_added" },
|
|
{ name: "primary identifier changed", mutate: (c) => { c.primary_identifiers = ["make"]; }, code: "primary_identifier_changed" },
|
|
{ name: "dimension removed", mutate: (c) => { c.dimensions = []; }, code: "dimension_removed" },
|
|
{ name: "measure removed", mutate: (c) => { c.measures = []; }, code: "measure_removed" },
|
|
{ name: "freshness SLO loosened", mutate: (c) => { c.freshness_slo_seconds = 86400; }, code: "freshness_slo_loosened" },
|
|
{ name: "retention shortened", mutate: (c) => { c.retention_days = 30; }, code: "retention_shortened" },
|
|
{ name: "allowed purpose removed", mutate: (c) => { c.allowed_purposes = []; }, code: "purpose_removed" },
|
|
{ name: "PII classification raised", mutate: (c) => { c.pii_classification = "personal"; }, code: "pii_classification_raised" },
|
|
{ name: "blocking quality rule removed", mutate: (c) => { c.quality_rules = []; }, code: "blocking_quality_rule_removed" },
|
|
{ name: "blocking quality rule downgraded", mutate: (c) => { c.quality_rules[0].severity = "warn"; }, code: "blocking_quality_rule_downgraded" },
|
|
{ name: "tier changed", mutate: (c) => { c.tier = "SERVING"; }, code: "tier_changed" },
|
|
];
|
|
|
|
describe("BI-P004 compatibility gate", () => {
|
|
it.each(BREAKING_CASES)("REFUSES $name under a minor bump", ({ mutate, code }) => {
|
|
const verdict = checkContractCompatibility(base(), next(mutate, "1.3.0"));
|
|
expect(verdict.compatible).toBe(false);
|
|
expect(verdict.breaking.map((b) => b.code)).toContain(code);
|
|
expect(verdict.reason).toMatch(/MAJOR version bump/);
|
|
});
|
|
|
|
it.each(BREAKING_CASES)("ACCEPTS $name once explicitly versioned (major bump)", ({ mutate, code }) => {
|
|
const verdict = checkContractCompatibility(base(), next(mutate, "2.0.0"));
|
|
expect(verdict.compatible).toBe(true);
|
|
expect(verdict.explicitly_versioned).toBe(true);
|
|
expect(verdict.breaking.map((b) => b.code)).toContain(code);
|
|
});
|
|
|
|
it("a patch bump is equally refused — the gate is about the MAJOR, not about moving at all", () => {
|
|
const verdict = checkContractCompatibility(base(), next((c) => c.fields.pop(), "1.2.1"));
|
|
expect(verdict.compatible).toBe(false);
|
|
});
|
|
|
|
it("allows genuinely additive changes without a major bump", () => {
|
|
const additive = next((c) => {
|
|
c.fields.push({ name: "mileage_km", type: "int64", nullable: true, role: "measure" });
|
|
c.measures.push("mileage_km");
|
|
c.quality_rules.push({ rule_id: "qr_mileage_range", kind: "range", field_name: "mileage_km", severity: "warn" });
|
|
c.allowed_purposes.push("valuation");
|
|
c.retention_days = 1095;
|
|
c.freshness_slo_seconds = 1800;
|
|
}, "1.3.0");
|
|
const verdict = checkContractCompatibility(base(), additive);
|
|
expect(verdict.compatible).toBe(true);
|
|
expect(verdict.breaking).toEqual([]);
|
|
expect(verdict.explicitly_versioned).toBe(false);
|
|
});
|
|
|
|
it("refuses a version that does not move forward", () => {
|
|
expect(checkContractCompatibility(base(), next(() => {}, "1.2.0")).compatible).toBe(false);
|
|
expect(checkContractCompatibility(base(), next(() => {}, "1.1.9")).compatible).toBe(false);
|
|
expect(checkContractCompatibility(base(), next(() => {}, "0.9.0")).compatible).toBe(false);
|
|
});
|
|
|
|
it("treats date -> timestamp as a safe widening, and int64 -> float64 as NOT one", () => {
|
|
const widened = next((c) => {
|
|
c.fields.push({ name: "sold_on", type: "date", nullable: true, role: "attribute" });
|
|
}, "1.3.0");
|
|
const later = JSON.parse(JSON.stringify(widened)) as DatasetContract;
|
|
later.fields[later.fields.length - 1].type = "timestamp";
|
|
later.version = "1.4.0";
|
|
expect(checkContractCompatibility(widened, later).compatible).toBe(true);
|
|
|
|
const lossy = next((c) => { c.fields[2].type = "float64"; }, "1.3.0");
|
|
expect(checkContractCompatibility(base(), lossy).compatible).toBe(false);
|
|
});
|
|
|
|
it("assertContractCompatible throws a CONFLICT rather than returning a verdict nobody reads", () => {
|
|
expect(() => assertContractCompatible(base(), next((c) => c.fields.pop(), "1.3.0"))).toThrowError(/MAJOR/);
|
|
expect(() => assertContractCompatible(base(), next(() => {}, "1.3.0"))).not.toThrow();
|
|
});
|
|
|
|
it("refuses to compare contracts for different datasets", () => {
|
|
const other = next((c) => { c.dataset_id = "ds_other"; }, "1.3.0");
|
|
expect(() => diffContracts(base(), other)).toThrowError(/SAME dataset/);
|
|
});
|
|
|
|
it("validateContract catches internally inconsistent contracts", () => {
|
|
expect(() => validateContract(base())).not.toThrow();
|
|
expect(() => validateContract({ ...base(), version: "1.2" })).toThrowError(/major.minor.patch/);
|
|
expect(() => validateContract({ ...base(), fields: [] })).toThrowError(/no fields/);
|
|
expect(() => validateContract({ ...base(), dimensions: ["nope"] })).toThrowError(/unknown field/);
|
|
expect(() => validateContract({ ...base(), primary_identifiers: [] })).toThrowError(/no primary identifier/);
|
|
expect(() => validateContract({ ...base(), allowed_purposes: [] })).toThrowError(/allowed_purposes/);
|
|
expect(() => validateContract({ ...base(), freshness_slo_seconds: 0 })).toThrowError(/freshness/);
|
|
const dup = base();
|
|
dup.fields.push({ ...dup.fields[0] });
|
|
expect(() => validateContract(dup)).toThrowError(/duplicate field/);
|
|
});
|
|
|
|
it("contractHash is order-insensitive over fields but sensitive to meaning", () => {
|
|
const a = base();
|
|
const reordered = JSON.parse(JSON.stringify(a)) as DatasetContract;
|
|
reordered.fields.reverse();
|
|
expect(contractHash(reordered)).toBe(contractHash(a));
|
|
|
|
const changed = JSON.parse(JSON.stringify(a)) as DatasetContract;
|
|
changed.fields[1].nullable = true;
|
|
expect(contractHash(changed)).not.toBe(contractHash(a));
|
|
});
|
|
|
|
it("parseSemVer rejects anything that is not major.minor.patch", () => {
|
|
expect(parseSemVer("2.10.3")).toEqual({ major: 2, minor: 10, patch: 3 });
|
|
for (const bad of ["v1.0.0", "1.0", "1.0.0-rc1", "latest", ""]) {
|
|
expect(() => parseSemVer(bad)).toThrowError(/major.minor.patch/);
|
|
}
|
|
});
|
|
});
|