Schema Contract Table-Matching Blind Spot Automation: A Test That Only Read Half Its Own Sentence

An automated check built to scan source code for a specific pattern is only as complete as its own definition of that pattern. Recognizing a table name written directly, as a literal string, inside a query is a completely reasonable first implementation — it is simple, and it correctly catches the pattern in every file that happens to be written that way. The gap appears specifically when a DIFFERENT, equally common way of expressing the identical underlying fact — naming a constant once and reusing it — exists throughout the actual codebase being scanned, and the check has no way to see past the indirection to the same fact underneath. The check is not wrong about what it verifies; it is simply blind to the majority of the places that fact actually appears.

Writing a verification tool that recognizes ONE specific way of expressing a fact in source code is the natural starting point, and it produces a genuinely working, genuinely useful check for every file that happens to follow that specific style. The risk is invisible from inside the tool itself: a pattern-matcher has no way to report "I don't understand 80% of the codebase's actual style" — it simply doesn't match anything in those files, contributes nothing to the count, and produces no signal distinguishing "this file has nothing to check" from "this file has plenty to check, written in a way I cannot see." The tool's own passing result looks identical in both cases.

Centriu Helix's schema contract exists specifically to catch a database column referenced by a query that does not actually exist on the underlying table — a failure mode the data layer itself only reports at the exact moment a query runs, since no type in the application's own code asserts anything specific about a table's real columns. The contract worked by scanning every source file for calls matching a table name written directly, as a literal string, inside the query call itself.

Measuring the module's actual repository layer against that pattern found a structural mismatch: the 57 files responsible for the bulk of the module's database access do not write table names directly inside their queries at all. Each one instead declares a single named constant near the top of the file — holding the actual table name as its value — and reuses that constant in every query the file makes. The contract's literal-string pattern had no visibility into this indirection whatsoever; a file written this way contributed nothing to what the contract believed it was checking, regardless of how many real queries against real tables the file actually contained. Measured precisely: the contract was actively verifying 16 tables, while the module's repository layer genuinely queries 71 — fifty-five tables, spanning job execution, agent orchestration, integrations, deployment rollout, data persistence, audit evidence and incident tracking, had never been checked even once.

The consequence was not hypothetical. It was through exactly this style of blind spot that a real, already-live compliance-audit screen's own invalid-column error had reached production undetected — a query built against a table using the constant-declaration style, referencing two columns that table does not actually have, shipped without the contract ever having a chance to catch it, since the table in question was never among the 16 the contract could see.

The fix teaches the contract's own matching logic a second pattern: before matching a query against the fixture of known tables, it first scans the SAME file for any constant declaration assigning a literal table name, builds a lookup from constant name to actual table name, and resolves any `.from(CONSTANT)` call through that lookup before checking it — collapsing the indirection back down to the same literal value the contract already knew how to verify. The underlying reference snapshot of real database columns was simultaneously regenerated directly from the project's own live API schema, expanding from 16 to 71 tracked tables. No invalid column was found among the 55 newly-visible tables — the actual data being queried was correct — but the contract can now genuinely say so, rather than having never actually looked. The fix's own correctness was proven by deliberately introducing a fake, non-existent column into one of the newly-visible repositories and confirming the contract now fails, correctly naming the specific file, table and column responsible.

Before the fix, a repository file declaring `const TABLE = "helix_job_runs"` and querying through that constant in every call was invisible to the schema contract regardless of how many columns it referenced or whether any of them were genuinely invalid — the contract's pattern simply never matched anything in that file. After the fix, the same file's queries are resolved through the constant to the real table name and checked exactly as thoroughly as a file that had always written the table name directly.

Centriu Helix's automated schema contract now genuinely verifies 71 of the module's real database tables, up from 16, closing the specific blind spot that had already let one real, invalid-column error reach a live production screen undetected. The fifty-five newly-covered tables span the module's job execution, agent orchestration, integration, rollout, persistence, audit-evidence and incident-tracking areas.

This automation governs only Centriu Helix's own internal schema-verification tooling — it does not change what data any screen actually displays, and does not itself fix any specific invalid-column error beyond confirming none currently exists among the 55 newly-covered tables. A codebase that never uses a named-constant pattern for table references would have no equivalent gap for this specific fix to close.

Matching only a table name written directly inside a query is the simplest possible implementation of a schema contract, and it correctly verifies every file written in exactly that style with no additional logic required. Its blind spot is specifically proportional to how much of the actual codebase uses a DIFFERENT, equally valid style — in this case, the majority of it. Resolving a named constant to its literal value before matching costs a genuinely more involved implementation (a first pass to build the constant-to-value lookup, before the matching pass can run), but is the only way to verify code written in the module's own dominant, and entirely reasonable, convention.