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>
119 lines
5.0 KiB
TypeScript
119 lines
5.0 KiB
TypeScript
/**
|
|
* BI-P012 — CLICKHOUSE RESOURCE GOVERNANCE, the part provable without an
|
|
* engine. The "intentional query bomb is terminated" half of the DoD needs a
|
|
* real server and lives in
|
|
* tests/integration/analytics-resource-governance.integration.test.ts.
|
|
*/
|
|
import { describe, it, expect } from "vitest";
|
|
import {
|
|
applyQuota,
|
|
BUDGET_TIERS,
|
|
clickhouseSettings,
|
|
ConcurrencyGate,
|
|
concurrencyProfileSql,
|
|
DEFAULT_BUDGETS,
|
|
REQUIRED_GOVERNANCE_SETTINGS,
|
|
} from "@/src/analytics/engine/resource-governance";
|
|
|
|
describe("BI-P012 resource governance", () => {
|
|
it("every setting the program names has a value somewhere in the enforcement path", () => {
|
|
const settings = clickhouseSettings(DEFAULT_BUDGETS.INTERACTIVE);
|
|
const profile = concurrencyProfileSql("opt_t_alpha", DEFAULT_BUDGETS.INTERACTIVE).join(" ");
|
|
for (const name of REQUIRED_GOVERNANCE_SETTINGS) {
|
|
const present = name in settings || profile.includes(name) || name === "max_concurrent_queries";
|
|
expect(present, `${name} is not enforced anywhere`).toBe(true);
|
|
}
|
|
// The five per-statement ones must be on the STATEMENT, not only in a
|
|
// profile a future operator might forget to attach.
|
|
for (const name of [
|
|
"max_execution_time",
|
|
"max_result_rows",
|
|
"max_rows_to_read",
|
|
"max_bytes_to_read",
|
|
"max_memory_usage",
|
|
]) {
|
|
expect(settings[name], `${name} missing from per-statement settings`).toBeDefined();
|
|
}
|
|
});
|
|
|
|
it("readonly=1 rides on every SELECT so the query text cannot re-set the limits", () => {
|
|
for (const tier of BUDGET_TIERS) {
|
|
expect(clickhouseSettings(DEFAULT_BUDGETS[tier]).readonly).toBe("1");
|
|
}
|
|
});
|
|
|
|
it("overflow modes are THROW, not BREAK — a partial result must never look complete", () => {
|
|
const s = clickhouseSettings(DEFAULT_BUDGETS.INTERACTIVE);
|
|
expect(s.result_overflow_mode).toBe("throw");
|
|
expect(s.read_overflow_mode).toBe("throw");
|
|
expect(s.timeout_overflow_mode).toBe("throw");
|
|
});
|
|
|
|
it("a CL0UD quota can only TIGHTEN a tier, never loosen it", () => {
|
|
const base = DEFAULT_BUDGETS.INTERACTIVE;
|
|
const loosened = applyQuota(base, {
|
|
maxExecutionTimeSec: 100000,
|
|
maxResultRows: 10_000_000,
|
|
maxRowsToRead: Number.MAX_SAFE_INTEGER,
|
|
maxBytesToRead: Number.MAX_SAFE_INTEGER,
|
|
maxMemoryUsageBytes: Number.MAX_SAFE_INTEGER,
|
|
maxConcurrentQueries: 1000,
|
|
});
|
|
expect(loosened).toEqual(base);
|
|
|
|
const tightened = applyQuota(base, { maxResultRows: 100, maxConcurrentQueries: 1 });
|
|
expect(tightened.maxResultRows).toBe(100);
|
|
expect(tightened.maxConcurrentQueries).toBe(1);
|
|
expect(tightened.maxExecutionTimeSec).toBe(base.maxExecutionTimeSec);
|
|
});
|
|
|
|
it("a nonsense quota (zero, negative, NaN) falls back to the tier rather than to no limit", () => {
|
|
const base = DEFAULT_BUDGETS.INTERACTIVE;
|
|
expect(applyQuota(base, { maxResultRows: 0 }).maxResultRows).toBe(base.maxResultRows);
|
|
expect(applyQuota(base, { maxResultRows: -5 }).maxResultRows).toBe(base.maxResultRows);
|
|
expect(applyQuota(base, { maxResultRows: Number.NaN }).maxResultRows).toBe(base.maxResultRows);
|
|
expect(applyQuota(base, undefined)).toEqual(base);
|
|
});
|
|
|
|
it("tiers get progressively more generous, and INTERACTIVE is the mean default", () => {
|
|
expect(DEFAULT_BUDGETS.INTERACTIVE.maxExecutionTimeSec).toBeLessThan(DEFAULT_BUDGETS.ANALYTICAL.maxExecutionTimeSec);
|
|
expect(DEFAULT_BUDGETS.ANALYTICAL.maxExecutionTimeSec).toBeLessThan(DEFAULT_BUDGETS.BATCH.maxExecutionTimeSec);
|
|
expect(DEFAULT_BUDGETS.INTERACTIVE.maxRowsToRead).toBeLessThan(DEFAULT_BUDGETS.ANALYTICAL.maxRowsToRead);
|
|
});
|
|
|
|
it("the concurrency gate throttles ONE tenant without touching another", () => {
|
|
const gate = new ConcurrencyGate((t) => (t === "t_noisy" ? 2 : 5));
|
|
const a = gate.acquire("t_noisy");
|
|
const b = gate.acquire("t_noisy");
|
|
expect(gate.inFlightFor("t_noisy")).toBe(2);
|
|
expect(() => gate.acquire("t_noisy")).toThrowError(/queries in flight/);
|
|
|
|
// The quiet tenant is unaffected — BI-P012's "without degrading unrelated
|
|
// tenant" in the smallest testable form.
|
|
const quiet = gate.acquire("t_quiet");
|
|
expect(gate.inFlightFor("t_quiet")).toBe(1);
|
|
|
|
a();
|
|
expect(gate.inFlightFor("t_noisy")).toBe(1);
|
|
expect(() => gate.acquire("t_noisy")).not.toThrow();
|
|
b();
|
|
quiet();
|
|
});
|
|
|
|
it("releasing twice does not free a slot that was never taken", () => {
|
|
const gate = new ConcurrencyGate(() => 1);
|
|
const release = gate.acquire("t_x");
|
|
release();
|
|
release();
|
|
expect(gate.inFlightFor("t_x")).toBe(0);
|
|
expect(gate.totalInFlight()).toBe(0);
|
|
});
|
|
|
|
it("the settings profile SQL carries max_concurrent_queries' server-side half", () => {
|
|
const stmts = concurrencyProfileSql("opt_t_alpha", DEFAULT_BUDGETS.INTERACTIVE);
|
|
expect(stmts.join(" ")).toContain("CREATE SETTINGS PROFILE IF NOT EXISTS opt_t_alpha");
|
|
expect(stmts.join(" ")).toContain("readonly = 1");
|
|
expect(stmts.join(" ")).toContain("CREATE QUOTA IF NOT EXISTS opt_t_alpha_quota");
|
|
});
|
|
});
|