feat(krl): DB-6 Phase A — explain keyword + structured query plan (#34)

[hyperpolymath]

Summary

Closes the Phase A gap on #34. Before this, EXPLAIN was reachable only over HTTP with raw SQL; the KRL surface the issue actually specifies did not exist — explain appeared in neither the lexer nor the parser, and there was no selectivity model at all, not even the stub the criteria permit.

What's added

• explain is a reserved word and a statement prefix: explain from … | filter … | take ….
• It parses to KRLExplainStmt — deliberately a distinct statement type rather than a flag on KRLQueryStmt, so every existing consumer of KRLQueryStmt still means "this query will actually execute" and cannot be handed a plan where it expected rows.
• ExplainPlan.jl builds the plan shape the acceptance criteria specify — an ordered scan followed by one entry per stage, each filter carrying column, comparator, value, indexed and a selectivity estimate. Conjunctions are split into separate filter operations, which is what makes the DB-7 reorder meaningful later.

explain from knots | filter colouring_count_3 = 9 and crossing < 8 | take 5

{"op" => "scan",   "table" => "knots"}
{"op" => "filter", "column" => "colouring_count_3", "comparator" => "=", "value" => 9,
                   "indexed" => true,  "selectivity_estimate" => 0.5, "selectivity_source" => "stub"}
{"op" => "filter", "column" => "crossing",          "comparator" => "<", "value" => 8,
                   "indexed" => false, "selectivity_estimate" => 0.5, "selectivity_source" => "stub"}
{"op" => "take",   "n" => 5}

Honesty properties (each asserted by a test)

• Selectivity is the stub the criteria permit pending DB-3 (DB-3: secondary indexes on colouring_count_3 / colouring_count_5 / alexander_polynomial #33) — and says so. Every estimate carries "selectivity_source" => "stub", and plan_is_costed returns false while any stub remains. That is the guard stopping a future DB-7 from silently optimising against invented numbers.
• indexed is driven by a deliberately short explicit column list. An over-claiming list would make it a fake signal, which is worse than reporting false.
• A predicate the plan cannot describe is not mis-described. Column-to-column comparisons, nested booleans and calls are reported opaquely ("predicate" => "<expression>", no column key) rather than given a fabricated column.

Verification

25 assertions in server/krl/test/explain_test.jl, wired into the dependency-free CI step alongside the other pure-Julia suites (so it runs before Pkg.instantiate and cannot be masked by a dependency breakage). The existing lexer / parser / sql / seam suites all still pass.

Scope

Phase A only. Phase B (cost-based reordering) is deliberately not attempted — it needs real selectivity, which is DB-3 (#33). The plan returned is execution order as written, with no reordering.

🤖 Generated with Claude Code

[gitar-bot]

Note

Automatic reviews are paused because your trial's included automatic processing has been used for this period. Upgrade now, or comment "Gitar review" to run a review anytime.
Learn more

Code Review ✅ Approved 1 resolved / 1 findings

Adds the explain keyword and structured query plan generation for KRL queries. However, plan_is_costed can never return true because scan, sort, take, and skip ops default to a "stub" selectivity source.

✅ 1 resolved

✅ Bug: plan_is_costed can never return true

📄 server/krl/ExplainPlan.jl:151-152
plan_is_costed iterates over every op in the plan and uses get(op, "selectivity_source", "stub"), defaulting to "stub" for ops that have no selectivity at all (scan/sort/take/skip). Since those ops never carry a selectivity_source key, the function returns false even once real histograms replace the filter stubs — so it can never fulfill its documented contract ("true only when every selectivity estimate came from real statistics") and DB-7's cost-based path could never activate. Restrict the check to ops that actually carry a selectivity estimate.

Options

Display: compact → Showing less information.

Comment with these commands to change the behavior for this request:

Compact

gitar display:verbose

_{Was this helpful? React with 👍 / 👎 | Gitar}