Mainframe fact channel: SQL table usage (DML): which programs read and write which tables #3446

Problem

sql_table_data holds EXEC SQL DECLARE … TABLE columns only. There is no record of what each program does to a table, so the engine cannot answer "which programs write ACCOUNT?" or build the program↔table read/write matrix that data-migration planning starts from.

Evidence

About 227 EXEC SQL … END-EXEC statements across CBSA and CardDemo: SELECT / INSERT / UPDATE / DELETE, DECLARE / OPEN / FETCH / CLOSE CURSOR, and host variables (:WS-X). Examples: CBSA src/base/cobol_src/INQACC.cbl, CREACC.cbl, XFRFUN.cbl; CardDemo app/app-transaction-type-db2/cbl/COTRTLIC.cbl (cursors) and COTRTUPC.cbl.

Proposal

A per-file channel, sql_statement_data: one row per statement, holding the verb, the table(s) (FROM / INTO / UPDATE / JOIN), the columns referenced, the cursor name, the host variables, and the line. Resolve each table to its sql_table_data DECLARE where one exists. The statements are already delimited by EXEC SQL … END-EXEC, so extraction is bounded and mostly mechanical.

Acceptance (ground truth, as for every channel since #3210)

• An independent draft reader in tests/tools/cobol_answer_key.py. It must not import the engine; test_draft_readers_never_import_the_parsers_they_grade enforces this.
• A new answer-key section, drafted for all three pinned corpora (zopeneditor, CBSA, CardDemo).
• A blind census of that section with tests/tools/cross_verify.py census, with every disagreement ruled against the source.
• A new scored field in tests/tools/ground_truth_ledger.py, so mainframe-ground-truth.yml fails CI on any regression.
• The channel follows gitgalaxy/core/how_to_add_a_fact_channel.md: extractor, *_data table, delta restore, galaxy_ir.EngineFile reader and SCOPE update.

Part of #3445.

🤖 Generated with Claude Code