fix(knowledge): the code↔DB map invented 33 of the 39 tables it named

[sshlg]

This is the product's core promise for a repository added to a dashboard: the agent goes to the code and knows how it uses the data. Measured in production on 2026-08-26 against the one real customer project — a Laravel repository against a 213-table MySQL database — the map named 39 tables, of which six exist.

real   catalog_phone_numbers  purchases  unlimit_wallets  sentry_samplers
       coverage_rule_import_exceptions  partner_phone_number_tests

noise  the to if an a get one ever every group its ends cascade
       current_timestamp 31 any ases whatever
       bs ls ns os pts res rs ses sts us xts zes

All three rows surfaced as sync_status='mismatch' — the headline signal, your code says one thing and your database says another — were noise: tables any, ases, whatever, columns e and now.

A customer opening that screen was told their code used a table called whatever.

Two mechanisms, compounding

TABLE_REF_SQL matches FROM|JOIN|INTO|UPDATE|TABLE followed by a word — and prose does that ("update to the latest", "insert into if needed"), as do keywords that legitimately follow (ON DELETE CASCADE). Six SQL keywords were the only filter.

Then _model_name_to_table pluralised whatever it was handed: z → zes, s → ses, pt → pts. Every one of the twelve suffix fragments is that function applied to a one- or two-character token — and it was handed them because _extract_model_names takes every class \w+ in a non-Python file while ORM_PATTERNS["sqlalchemy"] matches the bare word Column anywhere, so generated PHP reached the ORM branch and each of its classes became a "model".

The guard

is_plausible_table_name() on every recording site. Four shape rules — length ≥ 3, starts with a letter, not a keyword or common word, not a bare plural suffix on a fragment or a keyword: ases is as pluralised, ends is end.

Every reading is checked, not the first that matches. ends parses as en+ds and as end+s; taking whichever ending matched first let it through, and that was a real bug in my first attempt.

Deliberately shape, not a blocklist — a list of the 33 words that appeared would pass that repository and fail the next.

Measured on the production shapes:

SQL path    raw: 31 catalog_phone_numbers ever every group if purchases
                 sentry_samplers to unlimit_wallets
SQL path   kept: catalog_phone_numbers purchases sentry_samplers unlimit_wallets

pluraliser before: zes ses es us pts res sts xts bs ls ns os rs xes
pluraliser  after: [] — none invented

Second half: a migration states its table

The previous migration parser found nothing in a Laravel repository. It was (?:create_table|CreateTable|CREATE TABLE)\s+['"]?(\w+)— whitespace required before the name — so it missedSchema::create(entirely, missedop.create_table("x")because a paren is not whitespace, and missedcreate_table :xbecause:is not\w`. The map fell back to inference for every table the app has.

eloquent was absent from ORM_PATTERNS. Laravel reached the ORM branch only by accident. It is a first-class entry now, and protected $table = '…' outranks the pluralised class name for the same reason __tablename__ does.

tables_declared_in_migration() reads Laravel, Rails, Alembic, raw DDL and Django. A declaration carries more authority than a guess, which makes a false one worse — so its output passes the same shape test.

Tests

36 across two files, every fixture a real name from that repository rather than an invented one — including the six that were right, which the guard must not remove.

Suite: 6912 passed, 4 skipped, 1 xfailed.

Note on CI: main is unprotected and GitHub has not dispatched a workflow since 2026-08-26T00:30Z (audit findings A-6 / A-7), so this PR may show no checks through no fault of its own. The suite above was run locally in full.

🤖 Generated with Claude Code

https://claude.ai/code/session_01XtEZboEDbEXLYrLf1owRXB