feat(analytics): BI-P014/016..022/025..026/028..031 — query contract, analyst SQL, execution, cache, cost, dbt, quality, metrics #35
sax3l
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: admin/0pt#35
Reference in New Issue
Block a user
Extends the analytics core merged in #34 (BI-P002..P012). Nothing there is rebuilt —
SiaxAnalyticsEngine, the 19 entities, the forced tenant predicate and the BI-P012 budgets are all composed, not replaced.Fourteen prompts: BI-P014, P016–P022, P025–P026, P028–P031.
Full write-up:
docs/analytics/BI_QUERY_METRIC_QUALITY.md, organised around what is proven and what is not.Five findings that changed the implementation
Each came from a test written so it could fail; each is pinned so it cannot quietly stop being true.
1. ClickHouse
readonly = 1on a user profile forbids EVERY request setting. Measured on 24.8.14.39:Code: 164. Cannot modify 'max_rows_to_read' setting in readonly mode. So BI-P012's ceilings cannot travel with an analyst statement — they are baked into the user'sSETTINGS PROFILEat provisioning. Proven both ways: over-budget scan fails with code 158 from the profile with no setting sent; raising it from the request fails with 164.2.
CREATE ROW POLICY IF NOT EXISTSis a silent no-op on re-provisioning. Dropping a user empties the policy's apply-to list; the next run sees the policy exists and does nothing, so it survives applying to nobody whilesystem.row_policiesstill shows the right filter. The restricted user read 100 of 100 rows — both tenants — from the base table. Fixed withOR REPLACEplusrowPolicyVerificationSql(), which turns "the policy is applied" into a query.CREATE SETTINGS PROFILE IF NOT EXISTShas the identical shape and stale-budgeted the whole integration suite; same fix.3. DuckDB's
allowed_directoriesALONE is a no-op. Measured on 1.5.5: with the allow-list set and nothing else,read_csv('/etc/passwd')returned the file and anhttps://URL was fetched over the network. Onlyenable_external_access = falsealongside it binds the list. The obvious spelling appears induckdb_settings(), looks like a sandbox, and permits everything. Pinned by a test that never skips.4.
pg_constraint.connameis not schema-scoped.sql/009applied into a second schema silently skipped every guardedCHECK— and the tests that should have proven them passed, because the INSERTs they expected to fail succeeded. Every guard now scopes viaconrelid = '<table>'::regclass, proven by applying topublicfirst and then running into a fresh schema.5.
describe.skipIf(flagSetInBeforeAll)skips ALWAYS. Vitest evaluatesskipIfat collection time. Ten tests reported green while skipping against a live, reachable ClickHouse.BI-P017 — the dangerous one
Four layers, and the guard is deliberately called the weakest of them. 61 bypass attempts in one shared corpus, run twice: against the guard, and against a live ClickHouse with layer 2 removed. The live assertion is not "the engine errored" — it is "no canary came back", with
BETA_CANARYseeded into the other tenant's rows andSECRET_CANARYinto an ungranted table. The counterfactual runs first: as admin the same table returns 100 rows and the canary IS readable.0 of 61 leaked. Evidence:
evidence/bi-p017/analyst-sql-live-bypass.json, pinned by a test that never skips, so adding an attack without re-running breaks the build.Honest about what the guard does NOT catch:
SELECT tenant_id FROM t_alpha_sql.salesis structurally legitimate and IS admitted — it fails at the engine because the view does not project the column. Recorded in its ownGUARD_ADMITS_ENGINE_REFUSESlist and asserted live, rather than deleted from the corpus.BI-P019 / BI-P021 — things that actually stop
Cancellation verifies, it does not request: abort, kill, then poll until the query is gone or the deadline passes — and if it passes,
verified_stopped: false, not a cheerfultrue. Live: the cancelled query had read 6,559,476,156 rows and was gone 57 ms later, withsystem.query_logrecording code 394 QUERY_WAS_CANCELLED. Counterfactual: an identical bomb left alone is still running after 2 s.The budget polls live engine counters and cancels mid-scan. Live: a 1,000,000-row window stopped the query at 130,883,409 rows, 92 ms in, verified. The 130× overshoot is documented, in the module and the evidence — this is a bound of the form "within one poll interval of engine throughput", not a hard cap, and quoting it as one would be wrong. Admission-only mode reports itself as
"NOT ENFORCED — this budget is advisory", and an unshared window store reports"with N replicas a tenant can spend up to N times this budget".The rest
tenant/project_id/catalog/tablerejected by name (INF0's Wave-2 lesson). The DoD is an equality between two compile targets, with the ClickHouse side reconstructed by parsing the emitted SQL and its bound parameters inside the test.assertNoRawSqlusing ClickHouse's own query-echoing error text as the test case. Writes at every transition.n0d#38. Refusessuccesswith zero nodes (a selector matching nothing exits 0), a branch name as revision, a runtime that is not the pin.DBT_RUNTIME_PINships with both review flags false and production runs refused until they are true.providerReadiness()returnsverified: false. MetricFlow was never executed (no Python runtime; the pin has had no licence review), and the Superset and AI-Analyst DoD surfaces are open. A test asserts the readiness report says so.Verification
957 tests pass with ClickHouse 24.8, Postgres 16 and DuckDB 1.5.5 all live.
typecheck,eslint,prettierclean. Every live suite fails rather than skipping when its env var is set and the backend is down..gitea/workflows/**and.gitignoreare untouched. One latent flaw in that workflow is reported in the docs without changing it: the integration guard'sTests [0-9]+ passedpattern never matches because vitest writes ANSI codes between the words, so the guard is stricter than it reads. It is what caught the DuckDB suite's placement, so it earned its keep either way.🤖 Generated with Claude Code
The eight-field AnalyticsQueryRequest BI-P016 names, verbatim, with the rule that makes it safe enforced structurally rather than by convention: there is no field that can carry SQL, and parseAnalyticsQueryRequest REJECTS unknown keys instead of ignoring them. Ignoring an unsupported field is how it becomes a supported one after the next refactor. `tenant`, `tenant_id`, `project_id`, `database`, `catalog` and `table` are rejected by name. INF0's Wave-2 cross-tenant hole was a tenant read out of a request body; the fix that sticks is a request type in which the field does not exist, and a parser that refuses it when a caller sends it anyway. BI-P016's DoD ("same request compiles to ClickHouse/semantic engine without consumer rewrite") is tested as an equality, not narrated: both targets are projected onto a comparable shape and compared. The ClickHouse side of that projection is obtained by PARSING the emitted SQL and its bound parameters in the test — not by reading a field the compiler helpfully returned — so a compiler that silently drops a filter fails the comparison instead of passing it. The parser throws on any condition it does not recognise, which is what would catch unbound caller text appearing in the statement. BI-P011's forced tenant predicate is re-proven against this new path: five request shapes are enumerated and each must have FORCED_TENANT_PREDICATE as condition[0]; a blank tenant refuses to compile rather than emitting no predicate; a hostile filter value appears only in params, never in sql. 45 tests, all failing-capable: every rejection assertion checks the SiaxError code, and the DoD assertions compare reconstructed meaning rather than strings. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>AnalyticsSQLSession is a SEPARATE class, not a method on SiaxAnalyticsEngine. executeMetric has no raw-SQL surface at all; on the same object the closed DSL would be one refactor away from growing one. ClickHouseAnalyticsEngine .executeQuery stays a documented refusal. FOUR LAYERS, and the guard is deliberately called the weakest: 1 role — the CL0UD analyst role is checked when the SESSION IS OPENED, so a caller without it never obtains an object that can run SQL. 2 guard — statement admission. Comments and literals removed with ClickHouse's own lexical rules, ASCII-only outside literals, one statement, SELECT/WITH only, and every table reference POSITIVELY resolved against the tenant's catalog. Deny-lists are a second opinion, never the mechanism. 3 grants — a per-tenant ClickHouse user with SELECT on that tenant's catalog alone, plus a restrictive row policy on the base tables. 4 views — the tenant catalog holds only VIEWS, each baking `WHERE tenant_id = '<tenant>'`, and tenant_id is not projected. 61 bypass attempts, in one shared corpus, run TWICE: against the guard, and against a live ClickHouse 24.8.14.39 with LAYER 2 REMOVED. The live assertion is not "the engine errored" — it is "no canary came back", with BETA_CANARY seeded into the other tenant's rows and SECRET_CANARY into an ungranted table. The counterfactual runs first: as admin the same base table returns 100 rows and BETA_CANARY IS readable, so the isolation numbers mean something. Result: 0 of 61 leaked. Evidence: evidence/bi-p017/analyst-sql-live-bypass.json. FOUR DEFECTS FOUND BY WRITING TESTS THAT CAN FAIL — three of them mine: * `CREATE ROW POLICY IF NOT EXISTS` is a SILENT NO-OP on re-provisioning. Dropping the user empties the policy's apply-to list; the next run skips re-creation, so the policy survives with `apply_to_list = []`, applying to nobody, while `system.row_policies` still shows the correct select_filter. The restricted user read 100 of 100 rows — BOTH TENANTS — from the base table. Fixed with OR REPLACE + `rowPolicyVerificationSql`, which turns "the policy is applied" from an assumption into a query, and a test that asserts applied_to_user = 1 per object. * `CREATE SETTINGS PROFILE IF NOT EXISTS` has the identical shape: a changed budget never lands. A stale 60-row ceiling survived re-provisioning and starved every legitimate statement, with the DDL reporting success throughout. Also OR REPLACE now. * `describe.skipIf(!reachable)` where `reachable` is set in `beforeAll` skips ALWAYS — vitest evaluates skipIf at collection time. Ten tests reported green while skipping against a live, reachable server. Replaced with the repo's existing env-var gate, which FAILS when CLICKHOUSE_URL is set and the server is down rather than degrading to a skip. * MEASURED, and it changes the design: a ClickHouse user whose profile carries `readonly = 1` cannot have ANY setting changed from the request (Code: 164). The BI-P012 ceilings therefore cannot travel with an analyst statement; they are baked into the user's SETTINGS PROFILE at provisioning. Proven both ways: over-budget scan fails with code 158 from the profile with no setting sent, and an attempt to raise it from the request fails with code 164. Honest about what the guard does NOT catch: `SELECT tenant_id FROM t_alpha_sql.sales` is structurally legitimate and IS admitted. It fails at the engine because the view does not project the column. Recorded in its own GUARD_ADMITS_ENGINE_REFUSES list and asserted live, rather than deleted from the corpus. evidence/bi-p017 is pinned by tests/analytics/analyst-sql-evidence.test.ts, which never skips: adding an attack without re-running the live suite breaks the build, and the pin also checks the counterfactual numbers so the evidence cannot be a recording of an empty database. 246 tests pass. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>BI-P018 — every field the prompt names, plus the one it names by its absence. The record carries `compiled_query_hash` and never the statement, and that is ENFORCED: `assertNoRawSql` runs before any record is emitted and refuses one whose `error` field looks like SQL. The realistic leak is ClickHouse's own error text, which echoes the query — the test uses exactly that string. The recorder writes at EVERY transition, because a recorder that only writes at the end loses precisely the executions worth investigating. Illegal state transitions throw rather than overwrite a terminal row. The one place raw SQL is retained stays BI-P017's analyst statement history, where a privileged human ran unreviewed SQL and "who ran what" must survive. Different record, different retention posture, stated in both files. BI-P019 — "stops" is VERIFIED, not requested. Aborting the client stops US waiting, not the server; KILL QUERY without SYNC tells you nothing; even SYNC can return while the query unwinds. So cancelAndVerify aborts, kills, then POLLS the process list until the query is GONE or the deadline passes — and if the deadline passes it returns `verified_stopped: false` rather than a cheerful `true`. The return type is an outcome object, not a boolean, so a caller cannot mistake "we asked" for "it stopped". An unreachable engine is read as "still running" (fail closed), so the kill is still attempted at the moment an operator most needs it to be. Proven live against ClickHouse 24.8.14.39, with the counterfactual first: * an identical bomb left alone IS still running after 2s — so "gone after we cancelled" is not just "the query was short"; * the cancelled query had read 6,559,476,156 rows, and was verified gone 57ms after the request; * system.query_log records ExceptionWhileProcessing with code 394, QUERY_WAS_CANCELLED — ClickHouse's verdict, not ours. BI-P021 — the honest version. A budget checked once before execution bounds nothing, and the module says so in its first paragraph. ClickHouse's max_rows_to_read bounds ONE query; it cannot express "this tenant may scan X per hour", which is what a budget is for. So enforcement polls the engine's live read_rows/read_bytes counters and CANCELS the running query, through BI-P019 with verification, when window spend would be exceeded. Measured live: a 1,000,000-row window cancelled the query at 130,883,409 rows, 92ms in, verified stopped, code 394. THE OVERSHOOT IS DOCUMENTED, in the module and in the evidence: enforcement is granular to the poll interval, so this is a bound of the form "within roughly one poll interval of engine throughput", not a hard cap. Quoting it as a hard cap would be wrong. Two more things stated rather than implied: * `enforceInFlight: false` is reported by describeEnforcement() as "NOT ENFORCED — this budget is advisory", and the constructor REFUSES to accept enforceInFlight without a process control; * an unshared window store is reported as non-binding across replicas ("with N replicas a tenant can spend up to N times this budget"). * a query the budget killed is still charged for the work it burned. Not charging is how a tenant learns the cheapest query is a cancelled one. Evidence: evidence/bi-p019-p021/cancellation-and-budget.json 268 unit tests, 7 live tests. typecheck + eslint clean. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>All six key components BI-P020 lists are REQUIRED, and the builder refuses to produce a key when one is missing rather than defaulting it. A defaulted component is how a cache serves a result computed under a metric definition that no longer exists — that answer is not stale, it is WRONG, and it looks current. "Never share tenant result cache" is enforced structurally, in three layers, because the obvious one is a naming convention: * the key is prefixed with the tenant id, derived here from the verified identity and never passed in; * the stored ENTRY records its own tenant id, and every read checks the entry against the caller — so a prefix collision or a shared backing store still cannot serve a foreign result; * a cross-tenant hit is REFUSED and the poisoned entry EVICTED, not returned as a miss. Returning undefined would hide a security event. The third point is the one the test corpus exercises directly: an entry stored under t_alpha's key carrying t_beta's id, and a forged key that a SCAN glob would happily include. ST0RE was relying on naming conventions when it turned out to have four cross-tenant paths rather than the one reported. Staleness is tested by mutating each key component ONE AT A TIME and requiring a miss for every one — and a coverage assertion compares the mutation list against the component type, so adding a field to CacheKeyComponents without adding a mutation fails the suite instead of going untested. ValkeyResultCache takes the client as an injected interface, so no dependency and no CVE surface is added — the same reason BI-P005's Arrow writer is hand-written. It sets a store-side TTL as well as recording one (a recorded timestamp alone leaves expired results resident forever), pages with SCAN rather than blocking on KEYS, and removes a corrupt entry instead of letting it become a permanent silent miss. 32 tests. typecheck + eslint clean. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>BI-P028 extends the BI-P002 MetricDefinition rather than defining a second, parallel metric — a second metric type would be the exact failure the DoD is about. `MetricSpec` is the fifteen-field shape the prompt names; explicit bridge functions map it onto the persisted row plus the six columns it adds. The DoD ("no production metric exists only inside a dashboard tool") is enforced by something that refuses: a dashboard panel carrying an inline expression, inline aggregation or inline SQL is rejected, as is one naming an unregistered or RETIRED metric. So a metric cannot come into existence inside Superset and quietly become production. Validation refuses the metrics that render as a plausible number and mean nothing: no description, no owner, no time dimension, a ratio without a denominator, a currency format with no currency (which is how SEK gets rendered as USD), a filter on a dimension the metric does not declare. BI-P031's DoD is checked on a MEANING HASH rather than a field diff, so a field this code has never heard of still counts as changing the meaning — fail-closed rather than fail-open on future additions. Eight semantic fields are each mutated and each refused; three editorial fields are each mutated and each allowed, because forcing a version bump to fix a typo is how teams learn to route around governance. A new version starts DRAFT and EXPERIMENTAL: it never inherits the certification, or a certified metric's meaning could change while still wearing the badge. BI-P030 stores the semantic model separately from any engine, and that negative is enforced two ways after the first way turned out to be insufficient: * a VOCABULARY scan rejects a model mentioning metricflow / clickhouse / trino / cube / superset anywhere in its serialized form; * a STRUCTURAL check rejects any top-level key outside BI-P030's field list. The second exists because a test expected the vocabulary scan to catch a MetricFlow-shaped manifest and it did not — the manifest never says "metricflow". The structural check holds regardless of what a document calls itself. The manifest is now also stamped with its generator so a leaked copy is detectable. The replaceability DoD is tested with TWO providers whose naming rules differ (MetricFlow-shaped and Cube-shaped, `ds_sales.amount_sek`): the canonical id set must be identical across both AND the provider bindings must differ — otherwise the equality would hold trivially for a registry that only ever had one provider. BI-P029 — WHAT IS NOT PROVEN IS STATED IN THE MODULE AND RETURNED BY THE CODE. MetricFlow is a Python package and was NOT executed: no Python runtime is provisioned here, and BI-P029's "pin a currently verified version" requires a licence/supply-chain review that has not happened. `providerReadiness()` returns `verified: false` and names all four open items, including that the Superset path is unimplemented and the AI Analyst path uncompared. The constant `METRICFLOW_PINNED_VERSION` is labelled a declared intent, not a certification. A test asserts the readiness report says so, so the honesty cannot rot silently. 353 tests. typecheck + eslint clean. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>Scope stated in the module's first paragraph: this defines the contract, it does not run dbt, and nothing in this repo does. Execution is N0D's (n0d#38), which consumes this from the other side. There is deliberately no DbtExecutor implementation here — only the interface — so "0pt can run dbt" cannot become true by accident and the two repos share one versioned shape. `analytics/dbt/` is a real reference project covering raw -> staging -> curated -> serving, with the four layers mapped onto BI-P003's existing tiers rather than inventing a fifth vocabulary. The tenant predicate is applied at the FIRST modelled layer so every downstream model inherits it and no later model has to remember — the same forced-predicate rule as the query compiler's, one layer up. Two singular tests ship with it, both aimed at false greens: * `assert_mart_is_not_empty` — without it every column test passes trivially over zero rows and the whole suite reports green while the pipeline is dead; * `assert_no_cross_tenant_rows` — which should be impossible to fail, and exists precisely for that reason. An isolation guarantee nobody tests is the one that turns out to have four holes rather than the one reported. BI-P022's version rule is a GATE. `DBT_RUNTIME_PIN` records dbt Core 1.10.13 (stable) with dbt-clickhouse 1.9.2 and BOTH review flags FALSE — no licence or supply-chain review has been performed in this repo and none is claimed. `assertDbtRuntimeCertified` refuses a production run until they are true, and refuses an alpha line in production without a separate certification reference. A version constant on its own would be the documented-but-unenforced pattern; a test pins the flags at false so flipping them is a visible deliberate act. The result is treated as UNTRUSTED INPUT, because it arrives from another repo's executor and this estate has been burned by green statuses that meant nothing. Refused: `status: success` with ZERO nodes executed (a dbt selector matching nothing exits 0 — the dbt-shaped false green); an observed runtime different from the pin (the models mean something else and nothing says so); a revision that is not an exact 40-char SHA (a branch name is not reproducible, and reproducibility is the DoD); a missing manifest.json or run_results.json, without which the run cannot be audited or its tests ingested by BI-P025. Layer dependencies are checked against the manifest GRAPH, not asserted as a convention: a mart reading a source directly, or skipping a layer, or a staging model reading a mart, are each refused. Selectors are validated rather than passed through — a free-form argument list is a shell surface, and a shell surface on a job holding warehouse credentials is the whole problem. The job also cannot name an arbitrary target schema: it must be scoped to the job's tenant. 39 tests. typecheck + eslint clean. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>BI-P014's security requirement is the whole prompt: DuckDB is a local engine with `read_csv('/etc/passwd')` built in. Two layers. LAYER 1, the mount registry: a caller names ARTIFACT IDS, never paths. The registry resolves an id, checks the artifact belongs to the caller's tenant, and realpath()s the result to confirm it is still inside the mount root once symlinks are followed. A symlink to /etc/passwd, a traversing relative path, an absolute path, and a sibling directory sharing the root's prefix (/mnt/artifacts-evil for root /mnt/artifacts) are each refused. A cross-tenant read is AUTHORIZATION_DENIED, deliberately not NOT_FOUND — an operator reading the audit trail needs to see an attempted cross-tenant read as one. LAYER 2, THE FINDING: `SET allowed_directories=[...]` ALONE IS A NO-OP. Measured on DuckDB 1.5.5. With allowed_directories set to a single mount directory and nothing else, `read_csv('/etc/passwd')` RETURNED THE FILE and an https:// URL was fetched over the network. Only when `enable_external_access = false` is ALSO set does the allow-list bind; the same reads then fail with "Permission Error: Cannot access file". `lock_configuration=true` afterwards stops a query re-opening either. So the obvious spelling of this control — set the allow-list and move on — yields a setting that appears in duckdb_settings(), looks like a sandbox, and permits everything. That is `trivy --exit-code 0` in a different costume. The bootstrap is therefore emitted as ONE unit, `assertSessionSandboxed` refuses a session missing any part of it, and the measurement itself is PINNED by a test that never skips: if someone simplifies the bootstrap, the pinned evidence (`read_etc_passwd_succeeded: true` for the naive spelling) keeps the finding attached to the build rather than to a comment that would rot. Twelve bypass attempts run against a real DuckDB with LAYER 1 REMOVED — sent straight to the engine, registry not in the picture. Zero succeeded. The counterfactual runs in the same session and is asserted: the mounted file IS readable, so "nothing succeeded" is not a sandbox that blocks everything, which would be an outage rather than a control. A locked session is then shown unable to re-open its own sandbox, all three ways. DoD, against real fixtures: Parquet aggregates correctly (SE 394.5, NO 105.5), CSV round-trips a value containing a quote, and an ICEBERG SNAPSHOT reads via iceberg_scan on an exact metadata JSON — which is not a workaround: DuckDB refuses to glob for the latest version because globbing can read uncommitted data, and an exact metadata file is what "snapshot" means. Arrow is reported UNPROVEN by `readiness()` with the reason: DuckDB's arrow extension is a network install the offline environment could not download. THREE DEFECTS IN MY OWN TESTS, found and fixed rather than tidied away: * a bypass-corpus entry was `SELECT 1 FROM (SELECT 1) t` — not an attack at all. It succeeded and was reported as a leak. A corpus entry that cannot fail is as useless as a check that cannot. Replaced with real ATTACH and COPY attempts. * the harness ran the session bootstrap outside its try block, so a statement that correctly REFUSED to re-open a locked sandbox killed the subprocess and surfaced as an unreadable "Command failed" instead of as the meaningful refusal it was. * the Iceberg fallback was `expect(evidence.iceberg ?? "unbuilt").toBeDefined()` — a check that can never fail. It let a run without the fixture ERASE the recorded Iceberg result from the evidence file while both suites stayed green. It now rebuilds the fixture when pyiceberg is available and, when it is not, asserts against the previously recorded result and marks it as carried forward. The Iceberg fixture is deliberately NOT committed: pyiceberg writes absolute paths into its metadata and Avro manifests, so a committed table resolves only on the machine that built it, and a fixture that silently fails everywhere else is worse than none. tests/fixtures/duckdb/README.md says so and gives the rebuild command; the recorded result is the artefact instead. Heavy artifacts are refused with CAPABILITY_UNAVAILABLE and pointed at N0D, per BI-P014 — silently running a 40 GB scan in the API process is how a preview engine takes down a control plane. 35 unit tests, 12 live tests. Evidence: evidence/bi-p014/duckdb-sandbox.json. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>The migration the previous commits' comments promised. Additive and idempotent throughout, so the restore drill can replay it onto a live database. BI-P018 adds principal_id, workload, compiled_query_hash, datasets, metrics, cache_status and cost_units to the execution record — and deliberately NO `query_text` column, with a CHECK pinning the hash to 64 hex characters so a statement smuggled into that field is refused by the database. A test asserts the absence of `query_text` and `sql` as columns. BI-P031's DoD gets a Postgres TRIGGER, not just the TypeScript guard: a certified metric whose meaning_hash changes without a version bump raises. That is the layer that holds when something writes without going through the application — a migration script, a psql session, an admin tool. A compiler opinion does not survive `psql`; a trigger does. BI-P030 gets a version-history table whose CONTENT is immutable (status and valid_from may still move) plus a PARTIAL UNIQUE INDEX enforcing at most one ACTIVE version per model per tenant. Two active versions is a silent correctness failure in which half the dashboards read a different model, so it is an index rather than application discipline. BI-P021's usage ledger is append-only by trigger: update and delete both raise. BI-P026's freshness table DEFAULTS TO 'UNKNOWN' — a dataset nobody has computed freshness for must not read as FRESH — and requires a non-empty disclosure, because a state with no words attached is a state a dashboard renders as a silent green dot. BI-P025's quarantine record requires a principal and a reason on release. A BUG IN THIS MIGRATION, FOUND BY RUNNING IT: `SELECT 1 FROM pg_constraint WHERE conname = '...'` is NOT schema-scoped. conname is unique per schema, not per database, so on a database that already had these tables in `public` every guarded CHECK was silently skipped when the file was applied into a second schema. The constraints simply were not there, and the tests that should have proven them PASSED — because the INSERTs they expected to fail succeeded, and `expect(message).toContain(...)` on an undefined message reads as a type error, not as "the constraint is missing". Every guard now scopes via `conrelid = '<table>'::regclass`, and the fix is proven by applying the file to `public` FIRST and then running the suite into a fresh schema: 20/20. Two flaws in my own test harness, also found by running it: * `sql.unsafe("SET search_path ...; SELECT ...")` is a multi-statement simple query, and postgres.js returns the LAST statement's result — so a SELECT silently returned the connection object and two assertions compared against nonsense. search_path is now pinned on the CONNECTION. * the fixture INSERT used column names that do not exist in sql/008's dataset table, which surfaced as a suite-level failure rather than as 20 skips. 20 tests against a real Postgres 16, gated on ANALYTICS_TEST_DATABASE_URL, and each of them attempts the write the constraint exists to refuse. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>feat(analytics): BI-P014/016..022/025..031 — query contract, analyst SQL, execution, cache, cost, dbt, quality, metricsto feat(analytics): BI-P014/016..022/025..026/028..031 — query contract, analyst SQL, execution, cache, cost, dbt, quality, metricsNeither changes behaviour; both replace an assertion with a measurement. BI-P014's escaping strategy rests on DuckDB treating a backslash as a literal character, so that doubling `'` is sufficient. Verified on 1.5.5 rather than assumed: `SELECT length('a\\b')` returns 4, and `SELECT 'a\''` is a parser error ("unterminated quoted string") — which is exactly what a NON-escaping backslash produces. In a dialect where `\'` closed the literal, doubling would not be enough, so the claim is worth pinning to a run. BI-P017's FROM/JOIN scan is conservative where it is unsure, and that has a cost worth naming rather than discovering: ClickHouse's `ARRAY JOIN arr` takes a COLUMN, not a table, and this guard refuses it. A false refusal an analyst can see and report is the right side of that trade; a false ADMISSION is not. Supporting it means teaching the scan which JOIN flavours take a non-table target, which is the direction that grows holes — so it stays refused until someone needs it and can add it WITH a corpus entry proving the narrowing did not open anything else. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>