From 5cc6a363e22c22a6ee770be83225e4c0c9ccc195 Mon Sep 17 00:00:00 2001
From: Marcus Henriksson <kuseman80@gmail.com>
Date: Sun, 7 Jun 2026 10:30:46 +0200
Subject: [PATCH] feat: Let catalogs be able to handle TOP to avoid streaming
 whole tables back. This only works for single select queries feat: Add code
 coverage subsystem that lets queries be hooked in into Junit to assert and
 view missed operators / expression branches etc. feat: Add PlanRule system to
 assets can be made to a compiled query. Like a TableSacan as a child to a
 Join, forcing all joins to be indexed etc.

---
 .../api/catalog/DatasourceData.java           |  18 +
 .../catalog/jdbc/JdbcCatalog.java             |   2 +-
 .../catalog/jdbc/JdbcDatasource.java          |  31 +-
 .../jdbc/dialect/MySqlMariaDbDialect.java     |   7 +
 .../catalog/jdbc/dialect/PostgreDialect.java  |   7 +
 .../catalog/jdbc/dialect/SqlDialect.java      |  28 +-
 .../jdbc/dialect/SqlServerDialect.java        |   6 +
 .../catalog/jdbc/BaseJDBCTest.java            |  30 ++
 payloadbuilder-core/pom.xml                   |  45 ++-
 .../payloadbuilder/core/CompiledQuery.java    |   9 +-
 .../payloadbuilder/core/Payloadbuilder.java   |  13 +-
 .../payloadbuilder/core/cache/MBeanUtils.java |   4 +
 .../core/execution/CaseCoverageData.java      |  61 ++++
 .../execution/LogicalBinaryCoverageData.java  |  53 +++
 .../core/execution/PlanOperatorInfo.java      |  84 +++++
 .../core/execution/PlanRule.java              |  16 +
 .../core/execution/PlanRuleRegistry.java      |  47 +++
 .../execution/PlanRuleViolationException.java |  10 +
 .../core/execution/QueryCoverageData.java     | 304 +++++++++++++++++
 .../core/execution/QueryCoverageRegistry.java |  53 +++
 .../expression/ARewriteExpressionVisitor.java |   3 +-
 .../core/expression/CaseExpression.java       |  14 +
 .../InstrumentedCaseExpression.java           | 129 ++++++++
 .../InstrumentedLogicalBinaryExpression.java  | 107 ++++++
 .../expression/LogicalBinaryExpression.java   |  13 +
 .../core/expression/PredicateAnalyzer.java    |  39 ++-
 .../core/logicalplan/Filter.java              |  13 +
 .../payloadbuilder/core/logicalplan/Join.java |  13 +
 .../core/logicalplan/Projection.java          |  13 +
 .../payloadbuilder/core/logicalplan/Sort.java |  13 +
 .../optimization/ALogicalPlanOptimizer.java   |   8 +-
 .../optimization/ColumnOrdinalResolver.java   |   8 +-
 .../optimization/ColumnResolver.java          |   8 +-
 .../ComputedExpressionPushDown.java           |   8 +-
 .../optimization/PredicatePushDown.java       |  15 +-
 .../SubQueryExpressionPushDown.java           |   2 +-
 .../core/parser/QueryParser.java              |  37 +--
 .../core/physicalplan/AnalyzeInterceptor.java |   6 +
 .../core/physicalplan/CoveragePlan.java       | 243 ++++++++++++++
 .../physicalplan/CoverageTupleVector.java     |  64 ++++
 .../core/physicalplan/TableScan.java          |   5 +
 .../planning/CoverageExpressionRewriter.java  |  66 ++++
 .../core/planning/QueryPlanner.java           | 135 +++++++-
 .../core/planning/StatementPlanner.java       |  23 ++
 .../core/planning/StatementRewriter.java      | 109 +++++-
 .../core/physicalplan/CoveragePlanTest.java   | 278 ++++++++++++++++
 .../core/planning/QueryPlannerTest.java       |  41 ++-
 payloadbuilder-test/.gitignore                |   1 +
 payloadbuilder-test/README.md                 | 263 +++++++++++++++
 payloadbuilder-test/pom.xml                   |  38 +++
 .../test/CoverageAccumulator.java             |  52 +++
 .../payloadbuilder/test/CoverageReport.java   | 312 ++++++++++++++++++
 .../test/CoverageTestFactory.java             | 288 ++++++++++++++++
 .../test/QueryCoverageExtension.java          | 195 +++++++++++
 .../QueryCoverageExtensionExampleTest.java    | 152 +++++++++
 .../test/resources/queries/filter-example.sql |   3 +
 pom.xml                                       |   1 +
 57 files changed, 3466 insertions(+), 80 deletions(-)
 create mode 100644 payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/execution/CaseCoverageData.java
 create mode 100644 payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/execution/LogicalBinaryCoverageData.java
 create mode 100644 payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/execution/PlanOperatorInfo.java
 create mode 100644 payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/execution/PlanRule.java
 create mode 100644 payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/execution/PlanRuleRegistry.java
 create mode 100644 payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/execution/PlanRuleViolationException.java
 create mode 100644 payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/execution/QueryCoverageData.java
 create mode 100644 payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/execution/QueryCoverageRegistry.java
 create mode 100644 payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/expression/InstrumentedCaseExpression.java
 create mode 100644 payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/expression/InstrumentedLogicalBinaryExpression.java
 create mode 100644 payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/physicalplan/CoveragePlan.java
 create mode 100644 payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/physicalplan/CoverageTupleVector.java
 create mode 100644 payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/planning/CoverageExpressionRewriter.java
 create mode 100644 payloadbuilder-core/src/test/java/se/kuseman/payloadbuilder/core/physicalplan/CoveragePlanTest.java
 create mode 100644 payloadbuilder-test/.gitignore
 create mode 100644 payloadbuilder-test/README.md
 create mode 100644 payloadbuilder-test/pom.xml
 create mode 100644 payloadbuilder-test/src/main/java/se/kuseman/payloadbuilder/test/CoverageAccumulator.java
 create mode 100644 payloadbuilder-test/src/main/java/se/kuseman/payloadbuilder/test/CoverageReport.java
 create mode 100644 payloadbuilder-test/src/main/java/se/kuseman/payloadbuilder/test/CoverageTestFactory.java
 create mode 100644 payloadbuilder-test/src/main/java/se/kuseman/payloadbuilder/test/QueryCoverageExtension.java
 create mode 100644 payloadbuilder-test/src/test/java/se/kuseman/payloadbuilder/test/QueryCoverageExtensionExampleTest.java
 create mode 100644 payloadbuilder-test/src/test/resources/queries/filter-example.sql

diff --git a/payloadbuilder-api/src/main/java/se/kuseman/payloadbuilder/api/catalog/DatasourceData.java b/payloadbuilder-api/src/main/java/se/kuseman/payloadbuilder/api/catalog/DatasourceData.java
index 3d16be95f..8ce94eb0a 100644
--- a/payloadbuilder-api/src/main/java/se/kuseman/payloadbuilder/api/catalog/DatasourceData.java
+++ b/payloadbuilder-api/src/main/java/se/kuseman/payloadbuilder/api/catalog/DatasourceData.java
@@ -21,6 +21,8 @@ public class DatasourceData
     private final List<? extends ISortItem> sortItems;
     private final Projection projection;
     private final List<Option> options;
+    /** Top count hint from a TOP/LIMIT operator. -1 means no limit. Catalogs may use this to append TOP/LIMIT to their generated SQL. */
+    private int topCount = -1;
 
     public DatasourceData(int nodeId, List<IPredicate> predicates, List<? extends ISortItem> sortItems, Projection projection, List<Option> options)
     {
@@ -84,6 +86,22 @@ public List<Option> getOptions()
         return options;
     }
 
+    /**
+     * Return the top count hint pushed down from a TOP/LIMIT operator. Returns -1 if no limit is set. Catalogs that support row limiting (e.g. JDBC) may append TOP/LIMIT to their generated SQL for
+     * efficiency. The physical Limit operator remains in the plan and provides correctness; this is purely a performance hint.
+     */
+    public int getTopCount()
+    {
+        return topCount;
+    }
+
+    /** Set the top count hint. Called by the planner when a TOP/LIMIT operator is pushed down. */
+    public DatasourceData withTopCount(int n)
+    {
+        this.topCount = n;
+        return this;
+    }
+
     /**
      * Convenience method for extracting a equals predicate for specific column.
      *
diff --git a/payloadbuilder-catalog/src/main/java/se/kuseman/payloadbuilder/catalog/jdbc/JdbcCatalog.java b/payloadbuilder-catalog/src/main/java/se/kuseman/payloadbuilder/catalog/jdbc/JdbcCatalog.java
index b67686600..430d70687 100644
--- a/payloadbuilder-catalog/src/main/java/se/kuseman/payloadbuilder/catalog/jdbc/JdbcCatalog.java
+++ b/payloadbuilder-catalog/src/main/java/se/kuseman/payloadbuilder/catalog/jdbc/JdbcCatalog.java
@@ -234,7 +234,7 @@ private IDatasource getDataSource(IQuerySession session, String catalogAlias, Qu
                 .findAny()
                 .orElse(null);
 
-        return new JdbcDatasource(this, catalogAlias, table, seekPredicate, projection, predicates, sortItems, tableHintsOption, data.getOptions());
+        return new JdbcDatasource(this, catalogAlias, table, seekPredicate, projection, predicates, sortItems, tableHintsOption, data.getOptions(), data.getTopCount());
     }
 
     private Projection getOptionProjection(List<Option> options)
diff --git a/payloadbuilder-catalog/src/main/java/se/kuseman/payloadbuilder/catalog/jdbc/JdbcDatasource.java b/payloadbuilder-catalog/src/main/java/se/kuseman/payloadbuilder/catalog/jdbc/JdbcDatasource.java
index e2a8d272b..8db9e3ecb 100644
--- a/payloadbuilder-catalog/src/main/java/se/kuseman/payloadbuilder/catalog/jdbc/JdbcDatasource.java
+++ b/payloadbuilder-catalog/src/main/java/se/kuseman/payloadbuilder/catalog/jdbc/JdbcDatasource.java
@@ -48,6 +48,7 @@
 class JdbcDatasource implements IDatasource
 {
     private static final Logger LOGGER = LoggerFactory.getLogger(JdbcDatasource.class);
+    static final String QUERY = "Query";
     private final JdbcCatalog catalog;
     private final String catalogAlias;
     private final QualifiedName table;
@@ -58,9 +59,10 @@ class JdbcDatasource implements IDatasource
     private final IExpression tableHintsOption;
     private final List<Option> options;
     private final Map<String, ColumnOption> columnOptions;
+    private final int topCount;
 
     JdbcDatasource(JdbcCatalog catalog, String catalogAlias, QualifiedName table, ISeekPredicate indexPredicate, Projection projection, List<IPredicate> predicates, List<ISortItem> sortItems,
-            IExpression tableHintsOption, List<Option> options)
+            IExpression tableHintsOption, List<Option> options, int topCount)
     {
         this.catalog = catalog;
         this.catalogAlias = catalogAlias;
@@ -72,6 +74,7 @@ class JdbcDatasource implements IDatasource
         this.tableHintsOption = tableHintsOption;
         this.options = options;
         this.columnOptions = ColumnOption.extract(options);
+        this.topCount = topCount;
     }
 
     @Override
@@ -94,7 +97,7 @@ public Map<String, Object> getDescribeProperties(IExecutionContext context)
                     .collect(joining(",")));
         }
 
-        result.put("Query", buildSql(dialect, context, true));
+        result.put(QUERY, buildSql(dialect, context, true));
 
         return result;
     }
@@ -129,6 +132,15 @@ private String buildSql(SqlDialect dialect, IExecutionContext context, boolean d
                     .collect(joining(","));
         };
         StringBuilder sb = new StringBuilder("SELECT ");
+        // Dialect-specific TOP at the beginning of SELECT (e.g. SQL Server TOP(n))
+        if (topCount >= 0)
+        {
+            String selectTop = dialect.selectTopN(topCount);
+            if (!selectTop.isEmpty())
+            {
+                sb.append(selectTop);
+            }
+        }
         sb.append(projectionString);
         sb.append(" FROM ");
         sb.append(table.toString())
@@ -266,6 +278,14 @@ public ValueVector getValue()
             }
         }
 
+        // Dialect-specific trailing TOP/LIMIT (e.g. LIMIT n for MySQL/PostgreSQL, FETCH FIRST n ROWS ONLY for ANSI)
+        if (topCount >= 0
+                && dialect.selectTopN(topCount)
+                        .isEmpty())
+        {
+            dialect.appendTopN(sb, topCount);
+        }
+
         return sb.toString();
     }
 
@@ -456,6 +476,9 @@ public void close()
                         .getPrintWriter());
                 JdbcUtils.printWarnings(connection, context.getSession()
                         .getPrintWriter());
+                // Cancel any in-progress query so the server stops executing and data transfer halts
+                // (important when a TOP/LIMIT operator closes the iterator before all rows are consumed)
+                JdbcUtils.cancelQuiet(statement);
                 JdbcUtils.closeQuiet(connection, statement, rs);
                 schemaResult = null;
                 vectors = null;
@@ -502,6 +525,10 @@ private Statement getStatement() throws SQLException
                         statement = connection.createStatement(ResultSet.TYPE_FORWARD_ONLY, ResultSet.CONCUR_READ_ONLY);
                     }
 
+                    // Enable streaming so drivers that support it (SQL Server adaptive, MySQL useCursorFetch, etc.) fetch
+                    // rows on demand. Combined with close() → cancel() this stops data transfer as soon as caller is done.
+                    statement.setFetchSize(batchSize);
+
                     JdbcUtils.printWarnings(statement, context.getSession()
                             .getPrintWriter());
                 }
diff --git a/payloadbuilder-catalog/src/main/java/se/kuseman/payloadbuilder/catalog/jdbc/dialect/MySqlMariaDbDialect.java b/payloadbuilder-catalog/src/main/java/se/kuseman/payloadbuilder/catalog/jdbc/dialect/MySqlMariaDbDialect.java
index f99103b6e..ed0b42db8 100644
--- a/payloadbuilder-catalog/src/main/java/se/kuseman/payloadbuilder/catalog/jdbc/dialect/MySqlMariaDbDialect.java
+++ b/payloadbuilder-catalog/src/main/java/se/kuseman/payloadbuilder/catalog/jdbc/dialect/MySqlMariaDbDialect.java
@@ -13,6 +13,13 @@ class MySqlMariaDbDialect implements SqlDialect
 {
     private static final ZoneId UTC = ZoneId.of("UTC");
 
+    @Override
+    public void appendTopN(StringBuilder sb, int n)
+    {
+        sb.append(" LIMIT ")
+                .append(n);
+    }
+
     @Override
     public ColumnMeta getColumnMeta(ResultSetMetaData rsmd, int jdbcType, int ordinal) throws SQLException
     {
diff --git a/payloadbuilder-catalog/src/main/java/se/kuseman/payloadbuilder/catalog/jdbc/dialect/PostgreDialect.java b/payloadbuilder-catalog/src/main/java/se/kuseman/payloadbuilder/catalog/jdbc/dialect/PostgreDialect.java
index 247a849b5..83fb2d059 100644
--- a/payloadbuilder-catalog/src/main/java/se/kuseman/payloadbuilder/catalog/jdbc/dialect/PostgreDialect.java
+++ b/payloadbuilder-catalog/src/main/java/se/kuseman/payloadbuilder/catalog/jdbc/dialect/PostgreDialect.java
@@ -11,6 +11,13 @@ class PostgreDialect implements SqlDialect
 {
     private static final String TIMESTAMPTZ = "TIMESTAMPTZ";
 
+    @Override
+    public void appendTopN(StringBuilder sb, int n)
+    {
+        sb.append(" LIMIT ")
+                .append(n);
+    }
+
     @Override
     public String getIdentifierQuoteString(Connection connection) throws SQLException
     {
diff --git a/payloadbuilder-catalog/src/main/java/se/kuseman/payloadbuilder/catalog/jdbc/dialect/SqlDialect.java b/payloadbuilder-catalog/src/main/java/se/kuseman/payloadbuilder/catalog/jdbc/dialect/SqlDialect.java
index bbdf343fa..cca112033 100644
--- a/payloadbuilder-catalog/src/main/java/se/kuseman/payloadbuilder/catalog/jdbc/dialect/SqlDialect.java
+++ b/payloadbuilder-catalog/src/main/java/se/kuseman/payloadbuilder/catalog/jdbc/dialect/SqlDialect.java
@@ -318,9 +318,33 @@ default String getDropTableStatement(QualifiedName qname, boolean lenient)
                 : "DROP TABLE %s").formatted(qname.toDotDelimited());
     }
 
+    /**
+     * Returns the TOP-N fragment inserted right after "SELECT " in the SELECT clause (SQL Server style). Return empty string if this dialect uses a trailing clause instead.
+     * <p>
+     * Example for SQL Server: {@code "TOP(500) "}
+     * </p>
+     */
+    default String selectTopN(int n)
+    {
+        return "";
+    }
+
+    /**
+     * Appends a trailing row-limiting clause to the query (MySQL/PostgreSQL/ANSI style). Only called when {@link #selectTopN(int)} returns an empty string.
+     * <p>
+     * Default: ANSI SQL {@code FETCH FIRST n ROWS ONLY}.
+     * </p>
+     */
+    default void appendTopN(StringBuilder sb, int n)
+    {
+        sb.append(" FETCH FIRST ")
+                .append(n)
+                .append(" ROWS ONLY");
+    }
+
     /**
      * Appends join statement for provided seek keys.
-     * 
+     *
      * <pre>
      * This is the SQL that we need
      *
@@ -329,7 +353,7 @@ default String getDropTableStatement(QualifiedName qname, boolean lenient)
      *         SELECT 1 col1, 2 col2
      *   UNION SELECT 2,      4
      *   UNION SELECT 3,      6
-     * 
+     *
      * ) xx
      *   ON xx.col1 = y.col1
      *   AND xx.col2 = y.col2
diff --git a/payloadbuilder-catalog/src/main/java/se/kuseman/payloadbuilder/catalog/jdbc/dialect/SqlServerDialect.java b/payloadbuilder-catalog/src/main/java/se/kuseman/payloadbuilder/catalog/jdbc/dialect/SqlServerDialect.java
index 28363b84d..0179823fc 100644
--- a/payloadbuilder-catalog/src/main/java/se/kuseman/payloadbuilder/catalog/jdbc/dialect/SqlServerDialect.java
+++ b/payloadbuilder-catalog/src/main/java/se/kuseman/payloadbuilder/catalog/jdbc/dialect/SqlServerDialect.java
@@ -69,6 +69,12 @@ else if (type == Type.Any)
         return SqlDialect.super.getColumnDeclaration(type, scale, precision);
     }
 
+    @Override
+    public String selectTopN(int n)
+    {
+        return "TOP(" + n + ") ";
+    }
+
     @Override
     public String getDropTableStatement(QualifiedName qname, boolean lenient)
     {
diff --git a/payloadbuilder-catalog/src/test/java/se/kuseman/payloadbuilder/catalog/jdbc/BaseJDBCTest.java b/payloadbuilder-catalog/src/test/java/se/kuseman/payloadbuilder/catalog/jdbc/BaseJDBCTest.java
index a2be033a9..467c82eb6 100644
--- a/payloadbuilder-catalog/src/test/java/se/kuseman/payloadbuilder/catalog/jdbc/BaseJDBCTest.java
+++ b/payloadbuilder-catalog/src/test/java/se/kuseman/payloadbuilder/catalog/jdbc/BaseJDBCTest.java
@@ -757,6 +757,36 @@ void test_datasource_index_seek_multiple_columns_asterisk_with_sortitems()
         assertEquals(1, rowCount);
     }
 
+    @Test
+    void test_datasource_table_scan_with_top_count()
+    {
+        IExecutionContext context = mockExecutionContext();
+        // Table has 5 rows — request only 3 via topCount push-down
+        IDatasource ds = catalog.getScanDataSource(context.getSession(), CATALOG_ALIAS, TEST_TABLE, new DatasourceData(0, emptyList(), emptyList(), Projection.ALL, emptyList()).withTopCount(3));
+
+        // Verify the generated SQL contains the dialect-specific row-limiting clause
+        Map<String, Object> describe = ds.getDescribeProperties(context);
+        String query = String.valueOf(describe.get(JdbcDatasource.QUERY));
+        assertTrue(query.toLowerCase()
+                .contains("top")
+                || query.toLowerCase()
+                        .contains("limit")
+                || query.toLowerCase()
+                        .contains("fetch first"),
+                "Expected TOP/LIMIT/FETCH FIRST in query: " + query);
+
+        TupleIterator it = ds.execute(context);
+        int rowCount = 0;
+        while (it.hasNext())
+        {
+            rowCount += it.next()
+                    .getRowCount();
+        }
+        it.close();
+
+        assertEquals(3, rowCount);
+    }
+
     protected IExecutionContext mockExecutionContext()
     {
         return mockExecutionContext(null);
diff --git a/payloadbuilder-core/pom.xml b/payloadbuilder-core/pom.xml
index 985ff1820..3cd2ee1ec 100644
--- a/payloadbuilder-core/pom.xml
+++ b/payloadbuilder-core/pom.xml
@@ -127,7 +127,7 @@
                     <plugin>
                         <groupId>se.bjurr.gitchangelog</groupId>
                         <artifactId>git-changelog-maven-plugin</artifactId>
-                        <version>1.92</version>
+                        <version>2.2.11</version>
                         <executions>
                             <execution>
                                 <id>GenerateChangelog</id>
@@ -145,25 +145,54 @@
 {{#ifReleaseTag .}}
 ## [{{name}}](https://github.com/kuseman/payloadbuilder/releases/tag/{{name}}) ({{tagDate .}})
 
-  {{#ifContainsType commits type='feat'}}
+{{#ifContainsBreaking commits}}
+### Breaking Changes
+    {{#commits}}
+      {{#ifCommitBreaking .}}
+ - {{#eachCommitScope .}} **{{.}}** {{/eachCommitScope}} {{{commitDescription .}}} ([{{hash}}](https://github.com/kuseman/payloadbuilder/commit/{{hashFull}}))
+      {{/ifCommitBreaking}}
+    {{/commits}}
+{{/ifContainsBreaking}}
+{{#ifContainsType commits type='feat'}}
 ### Features
-
     {{#commits}}
       {{#ifCommitType . type='feat'}}
  - {{#eachCommitScope .}} **{{.}}** {{/eachCommitScope}} {{{commitDescription .}}} ([{{hash}}](https://github.com/kuseman/payloadbuilder/commit/{{hashFull}}))
       {{/ifCommitType}}
     {{/commits}}
-  {{/ifContainsType}}
-
-  {{#ifContainsType commits type='fix'}}
+{{/ifContainsType}}
+{{#ifContainsType commits type='fix'}}
 ### Bug Fixes
-
     {{#commits}}
       {{#ifCommitType . type='fix'}}
  - {{#eachCommitScope .}} **{{.}}** {{/eachCommitScope}} {{{commitDescription .}}} ([{{hash}}](https://github.com/kuseman/payloadbuilder/commit/{{hashFull}}))
       {{/ifCommitType}}
     {{/commits}}
-  {{/ifContainsType}}
+{{/ifContainsType}}
+{{#ifContainsType commits type='perf'}}
+### Performance Improvements
+    {{#commits}}
+      {{#ifCommitType . type='perf'}}
+ - {{#eachCommitScope .}} **{{.}}** {{/eachCommitScope}} {{{commitDescription .}}} ([{{hash}}](https://github.com/kuseman/payloadbuilder/commit/{{hashFull}}))
+      {{/ifCommitType}}
+    {{/commits}}
+{{/ifContainsType}}
+{{#ifContainsType commits type='refactor'}}
+### Refactoring
+    {{#commits}}
+      {{#ifCommitType . type='refactor'}}
+ - {{#eachCommitScope .}} **{{.}}** {{/eachCommitScope}} {{{commitDescription .}}} ([{{hash}}](https://github.com/kuseman/payloadbuilder/commit/{{hashFull}}))
+      {{/ifCommitType}}
+    {{/commits}}
+{{/ifContainsType}}
+{{#ifContainsType commits type='docs'}}
+### Documentation
+    {{#commits}}
+      {{#ifCommitType . type='docs'}}
+ - {{#eachCommitScope .}} **{{.}}** {{/eachCommitScope}} {{{commitDescription .}}} ([{{hash}}](https://github.com/kuseman/payloadbuilder/commit/{{hashFull}}))
+      {{/ifCommitType}}
+    {{/commits}}
+{{/ifContainsType}}
 
 {{/ifReleaseTag}}
 {{/tags}}
diff --git a/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/CompiledQuery.java b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/CompiledQuery.java
index a55762658..78fac72c4 100644
--- a/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/CompiledQuery.java
+++ b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/CompiledQuery.java
@@ -14,15 +14,22 @@
  */
 public class CompiledQuery
 {
+    private final String name;
     private final QueryStatement query;
     private final List<Warning> warnings;
 
-    CompiledQuery(QueryStatement query, List<Warning> warnings)
+    CompiledQuery(QueryStatement query, List<Warning> warnings, String name)
     {
+        this.name = name;
         this.query = requireNonNull(query);
         this.warnings = warnings;
     }
 
+    public String getName()
+    {
+        return name;
+    }
+
     /** Execute this query with provided session */
     public QueryResult execute(QuerySession session)
     {
diff --git a/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/Payloadbuilder.java b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/Payloadbuilder.java
index c4c2bc3ec..1e0eb2a43 100644
--- a/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/Payloadbuilder.java
+++ b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/Payloadbuilder.java
@@ -38,10 +38,19 @@ public static CompiledQuery compile(CatalogRegistry registry, String query)
      * </pre>
      */
     public static CompiledQuery compile(QuerySession session, String query)
+    {
+        return compile(session, query, null);
+    }
+
+    /**
+     * Compile query with a stable name. The name is embedded in coverage reports, allowing test code to register a source file for it via
+     * {@link se.kuseman.payloadbuilder.core.execution.QueryCoverageRegistry#registerQuerySource(String, String)}.
+     */
+    public static CompiledQuery compile(QuerySession session, String query, String queryName)
     {
         List<CompiledQuery.Warning> warnings = new ArrayList<>();
         QueryStatement queryStatement = PARSER.parseQuery(query, warnings);
-        queryStatement = StatementPlanner.plan(session, queryStatement);
-        return new CompiledQuery(queryStatement, warnings);
+        queryStatement = StatementPlanner.plan(session, queryStatement, queryName);
+        return new CompiledQuery(queryStatement, warnings, queryName);
     }
 }
diff --git a/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/cache/MBeanUtils.java b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/cache/MBeanUtils.java
index d91d41582..4cf980271 100644
--- a/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/cache/MBeanUtils.java
+++ b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/cache/MBeanUtils.java
@@ -26,6 +26,10 @@ public static void registerCacheMBean(CacheType type, String providerName, Quali
                             : "",
                     name));
             MBeanServer mbs = ManagementFactory.getPlatformMBeanServer();
+            if (mbs.isRegistered(objectName))
+            {
+                mbs.unregisterMBean(objectName);
+            }
             mbs.registerMBean(new CacheMBeanImpl(cache), objectName);
         }
         catch (Exception e)
diff --git a/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/execution/CaseCoverageData.java b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/execution/CaseCoverageData.java
new file mode 100644
index 000000000..0282275af
--- /dev/null
+++ b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/execution/CaseCoverageData.java
@@ -0,0 +1,61 @@
+package se.kuseman.payloadbuilder.core.execution;
+
+import se.kuseman.payloadbuilder.api.execution.NodeData;
+import se.kuseman.payloadbuilder.core.parser.Location;
+
+/** Per-CASE-expression coverage data tracking which WHEN branches were hit during execution */
+public class CaseCoverageData extends NodeData
+{
+    private final String expressionText;
+    private final long[] whenHits;
+    private long elseHits;
+    private final Location location;
+
+    public CaseCoverageData(int whenClauseCount, String expressionText, Location location)
+    {
+        this.whenHits = new long[whenClauseCount];
+        this.expressionText = expressionText;
+        this.location = location != null ? location
+                : Location.EMPTY;
+    }
+
+    public String getExpressionText()
+    {
+        return expressionText;
+    }
+
+    public Location getLocation()
+    {
+        return location;
+    }
+
+    /** Record that a specific WHEN branch was matched for the given row count. */
+    public void recordWhenHit(int branchIndex, long count)
+    {
+        if (branchIndex >= 0
+                && branchIndex < whenHits.length
+                && count > 0)
+        {
+            whenHits[branchIndex] += count;
+        }
+    }
+
+    /** Record that the ELSE branch was matched for the given row count. */
+    public void recordElseHit(long count)
+    {
+        if (count > 0)
+        {
+            elseHits += count;
+        }
+    }
+
+    public long[] getWhenHits()
+    {
+        return whenHits;
+    }
+
+    public long getElseHits()
+    {
+        return elseHits;
+    }
+}
diff --git a/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/execution/LogicalBinaryCoverageData.java b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/execution/LogicalBinaryCoverageData.java
new file mode 100644
index 000000000..6451176c3
--- /dev/null
+++ b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/execution/LogicalBinaryCoverageData.java
@@ -0,0 +1,53 @@
+package se.kuseman.payloadbuilder.core.execution;
+
+import se.kuseman.payloadbuilder.api.execution.NodeData;
+import se.kuseman.payloadbuilder.core.parser.Location;
+
+/** Per-AND/OR-expression coverage data tracking how many times the condition evaluated to true vs. false. */
+public class LogicalBinaryCoverageData extends NodeData
+{
+    private final String expressionText;
+    private long trueHits;
+    private long falseHits;
+    private final Location location;
+
+    public LogicalBinaryCoverageData(String expressionText, Location location)
+    {
+        this.expressionText = expressionText;
+        this.location = location != null ? location
+                : Location.EMPTY;
+    }
+
+    public String getExpressionText()
+    {
+        return expressionText;
+    }
+
+    public Location getLocation()
+    {
+        return location;
+    }
+
+    /** Records that the condition evaluated to true for {@code trueCount} rows and false for {@code falseCount} rows. */
+    public void recordHits(long trueCount, long falseCount)
+    {
+        if (trueCount > 0)
+        {
+            trueHits += trueCount;
+        }
+        if (falseCount > 0)
+        {
+            falseHits += falseCount;
+        }
+    }
+
+    public long getTrueHits()
+    {
+        return trueHits;
+    }
+
+    public long getFalseHits()
+    {
+        return falseHits;
+    }
+}
diff --git a/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/execution/PlanOperatorInfo.java b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/execution/PlanOperatorInfo.java
new file mode 100644
index 000000000..dc83e6d49
--- /dev/null
+++ b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/execution/PlanOperatorInfo.java
@@ -0,0 +1,84 @@
+package se.kuseman.payloadbuilder.core.execution;
+
+import se.kuseman.payloadbuilder.core.physicalplan.IPhysicalPlan;
+
+/**
+ * Structured information about a single operator node in a compiled physical plan, passed to {@link PlanRule#check(PlanOperatorInfo)} during compilation. The underlying {@link IPhysicalPlan} is
+ * exposed directly so rules can use {@code instanceof} pattern matching to access type-specific properties.
+ *
+ * <pre>
+ * op -&gt;
+ * {
+ *     if (op.plan() instanceof TableScan ts
+ *             &amp;&amp; ts.getCatalogAlias() != null
+ *             &amp;&amp; !ts.getCatalogAlias()
+ *                     .startsWith("#"))
+ *     {
+ *         throw new PlanRuleViolationException("Full scan on catalog '" + ts.getCatalogAlias() + "' in '" + op.queryName() + "' line " + op.sourceLine());
+ *     }
+ * }
+ * </pre>
+ *
+ * <p>
+ * Use {@link #parent()} to walk up the ancestor chain and distinguish contexts — e.g. a scan inside a join vs a scan inside a SELECT INTO:
+ * </p>
+ *
+ * <pre>
+ * op -&gt;
+ * {
+ *     if (op.plan() instanceof IndexSeek
+ *             &amp;&amp; op.hasAncestor(NestedLoop.class))
+ *     {
+ *         // scan is the inner side of a join
+ *     }
+ * }
+ * </pre>
+ *
+ * @param plan the physical plan node — use {@code instanceof} to access type-specific fields
+ * @param sourceLine source line in the SQL text; {@code 0} when location information is unavailable
+ * @param queryName the compile-time name passed to {@code Payloadbuilder.compile(session, sql, name)}, or {@code null} for unnamed queries
+ * @param parent the parent operator info, or {@code null} if this is the root operator
+ */
+public record PlanOperatorInfo(IPhysicalPlan plan, int sourceLine, String queryName, PlanOperatorInfo parent)
+{
+    /** Convenience constructor for the root operator (no parent). */
+    public PlanOperatorInfo(IPhysicalPlan plan, int sourceLine, String queryName)
+    {
+        this(plan, sourceLine, queryName, null);
+    }
+
+    /**
+     * Returns {@code true} if any ancestor in the parent chain is an instance of the given physical plan type. Useful for distinguishing execution contexts — e.g. whether a scan is the inner side of
+     * a join, or directly under a SELECT INTO.
+     */
+    public boolean hasAncestor(Class<? extends IPhysicalPlan> type)
+    {
+        PlanOperatorInfo p = parent;
+        while (p != null)
+        {
+            if (type.isInstance(p.plan()))
+            {
+                return true;
+            }
+            p = p.parent();
+        }
+        return false;
+    }
+
+    /**
+     * Returns the nearest ancestor whose plan is an instance of the given type, or {@code null} if none exists.
+     */
+    public PlanOperatorInfo firstAncestor(Class<? extends IPhysicalPlan> type)
+    {
+        PlanOperatorInfo p = parent;
+        while (p != null)
+        {
+            if (type.isInstance(p.plan()))
+            {
+                return p;
+            }
+            p = p.parent();
+        }
+        return null;
+    }
+}
diff --git a/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/execution/PlanRule.java b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/execution/PlanRule.java
new file mode 100644
index 000000000..702fddec4
--- /dev/null
+++ b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/execution/PlanRule.java
@@ -0,0 +1,16 @@
+package se.kuseman.payloadbuilder.core.execution;
+
+/**
+ * Rule evaluated against every operator in a compiled physical plan. Register via {@link PlanRuleRegistry} or via {@code QueryCoverageExtension.addRule(rule)} in JUnit tests. Throw
+ * {@link PlanRuleViolationException} to reject the plan and propagate a test failure to the {@code @Test} method that triggered the compile.
+ */
+@FunctionalInterface
+public interface PlanRule
+{
+    /**
+     * Called once for every operator node in the compiled physical plan tree. Throw {@link PlanRuleViolationException} to reject the plan.
+     *
+     * @param operator structured information about this operator — name, catalog alias, source line, query name
+     */
+    void check(PlanOperatorInfo operator);
+}
diff --git a/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/execution/PlanRuleRegistry.java b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/execution/PlanRuleRegistry.java
new file mode 100644
index 000000000..a119844eb
--- /dev/null
+++ b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/execution/PlanRuleRegistry.java
@@ -0,0 +1,47 @@
+package se.kuseman.payloadbuilder.core.execution;
+
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * Thread-local registry that connects the plan rule engine to rules registered by test extensions (e.g. {@code QueryCoverageExtension}). Rules are registered per thread so parallel test execution
+ * works without interference.
+ */
+public class PlanRuleRegistry
+{
+    private static final ThreadLocal<List<PlanRule>> RULES = ThreadLocal.withInitial(ArrayList::new);
+
+    private PlanRuleRegistry()
+    {
+    }
+
+    /** Registers a rule that will be checked against every compiled physical plan on this thread. */
+    public static void register(PlanRule rule)
+    {
+        RULES.get()
+                .add(rule);
+    }
+
+    /** Deregisters a previously registered rule. */
+    public static void deregister(PlanRule rule)
+    {
+        RULES.get()
+                .remove(rule);
+    }
+
+    /** Returns {@code true} if at least one rule is registered on the current thread. */
+    public static boolean isActive()
+    {
+        return !RULES.get()
+                .isEmpty();
+    }
+
+    /** Invokes all registered rules with the given operator info. Called by the plan-rule walk in {@link se.kuseman.payloadbuilder.core.planning.StatementRewriter}. */
+    public static void check(PlanOperatorInfo operator)
+    {
+        for (PlanRule rule : RULES.get())
+        {
+            rule.check(operator);
+        }
+    }
+}
diff --git a/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/execution/PlanRuleViolationException.java b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/execution/PlanRuleViolationException.java
new file mode 100644
index 000000000..1d625f423
--- /dev/null
+++ b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/execution/PlanRuleViolationException.java
@@ -0,0 +1,10 @@
+package se.kuseman.payloadbuilder.core.execution;
+
+/** Thrown by a {@link PlanRule} to indicate that the compiled physical plan violates a rule. */
+public class PlanRuleViolationException extends RuntimeException
+{
+    public PlanRuleViolationException(String message)
+    {
+        super(message);
+    }
+}
diff --git a/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/execution/QueryCoverageData.java b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/execution/QueryCoverageData.java
new file mode 100644
index 000000000..a32dd7d64
--- /dev/null
+++ b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/execution/QueryCoverageData.java
@@ -0,0 +1,304 @@
+package se.kuseman.payloadbuilder.core.execution;
+
+import java.util.List;
+import java.util.Map;
+import java.util.function.Function;
+import java.util.stream.Collectors;
+
+import se.kuseman.payloadbuilder.core.parser.Location;
+
+/**
+ * Coverage data gathered for a single query execution. Contains per-operator row statistics, per-branch hit counts for CASE/IF expressions, and per-condition true/false counts for AND/OR expressions.
+ * Multiple executions of the same query are aggregated via {@link #merge(QueryCoverageData)}.
+ */
+public class QueryCoverageData
+{
+    /** Stable key derived from the query name or physical plan structure. Used by the accumulator to aggregate repeated executions. */
+    private final String queryKey;
+    private final List<OperatorCoverage> operators;
+    private final List<BranchCoverage> branches;
+    private final List<ConditionCoverage> conditions;
+
+    /** Creates coverage data with an explicit query key. */
+    public QueryCoverageData(String queryKey, List<OperatorCoverage> operators, List<BranchCoverage> branches, List<ConditionCoverage> conditions)
+    {
+        this.queryKey = queryKey;
+        this.operators = operators;
+        this.branches = branches;
+        this.conditions = conditions;
+    }
+
+    /** Returns the stable key identifying this query — the compile-time name if set, otherwise a plan-structure hash. */
+    public String getQueryKey()
+    {
+        return queryKey;
+    }
+
+    /** Returns per-operator coverage entries. */
+    public List<OperatorCoverage> getOperators()
+    {
+        return operators;
+    }
+
+    /** Returns per-branch coverage entries (CASE/IF expressions). */
+    public List<BranchCoverage> getBranches()
+    {
+        return branches;
+    }
+
+    /** Returns per-condition coverage entries (AND/OR expressions). */
+    public List<ConditionCoverage> getConditions()
+    {
+        return conditions;
+    }
+
+    /** Merges another execution's coverage data into this object in place. Sums all counts. */
+    public void merge(QueryCoverageData other)
+    {
+        Map<Integer, OperatorCoverage> byId = operators.stream()
+                .collect(Collectors.toMap(o -> o.nodeId, Function.identity()));
+        for (OperatorCoverage otherOp : other.operators)
+        {
+            OperatorCoverage existing = byId.get(otherOp.nodeId);
+            if (existing != null)
+            {
+                existing.executionCount += otherOp.executionCount;
+                existing.rowsOut += otherOp.rowsOut;
+                existing.covered = existing.covered
+                        || otherOp.covered;
+            }
+        }
+
+        Map<Integer, BranchCoverage> branchById = branches.stream()
+                .collect(Collectors.toMap(b -> b.nodeId, Function.identity()));
+        for (BranchCoverage otherBr : other.branches)
+        {
+            BranchCoverage existing = branchById.get(otherBr.nodeId);
+            if (existing != null)
+            {
+                for (int i = 0; i < existing.whenHits.length
+                        && i < otherBr.whenHits.length; i++)
+                {
+                    existing.whenHits[i] += otherBr.whenHits[i];
+                }
+                existing.elseHits += otherBr.elseHits;
+            }
+        }
+
+        Map<Integer, ConditionCoverage> condById = conditions.stream()
+                .collect(Collectors.toMap(c -> c.nodeId, Function.identity()));
+        for (ConditionCoverage otherCond : other.conditions)
+        {
+            ConditionCoverage existing = condById.get(otherCond.nodeId);
+            if (existing != null)
+            {
+                existing.trueHits += otherCond.trueHits;
+                existing.falseHits += otherCond.falseHits;
+            }
+        }
+    }
+
+    /** Serialize coverage data to a compact JSON string. */
+    public String toJson()
+    {
+        StringBuilder sb = new StringBuilder();
+        sb.append("{\"operators\":{");
+        boolean firstOp = true;
+        for (OperatorCoverage op : operators)
+        {
+            if (!firstOp)
+            {
+                sb.append(",");
+            }
+            firstOp = false;
+            sb.append("\"")
+                    .append(op.nodeId)
+                    .append("\":{");
+            sb.append("\"name\":\"")
+                    .append(escapeJson(op.name))
+                    .append("\"");
+            sb.append(",\"execution_count\":")
+                    .append(op.executionCount);
+            sb.append(",\"rows_out\":")
+                    .append(op.rowsOut);
+            sb.append(",\"covered\":")
+                    .append(op.covered);
+            if (op.location != null
+                    && op.location.line() > 0)
+            {
+                sb.append(",\"location\":{\"line\":")
+                        .append(op.location.line())
+                        .append(",\"start\":")
+                        .append(op.location.startOffset())
+                        .append(",\"end\":")
+                        .append(op.location.endOffset())
+                        .append("}");
+            }
+            sb.append("}");
+        }
+        sb.append("}");
+
+        if (!branches.isEmpty())
+        {
+            sb.append(",\"branches\":{");
+            boolean firstBr = true;
+            for (BranchCoverage br : branches)
+            {
+                if (!firstBr)
+                {
+                    sb.append(",");
+                }
+                firstBr = false;
+                sb.append("\"")
+                        .append(br.nodeId)
+                        .append("\":{");
+                sb.append("\"expression\":\"")
+                        .append(escapeJson(br.expressionText))
+                        .append("\"");
+                sb.append(",\"when_hits\":[");
+                for (int i = 0; i < br.whenHits.length; i++)
+                {
+                    if (i > 0)
+                    {
+                        sb.append(",");
+                    }
+                    sb.append(br.whenHits[i]);
+                }
+                sb.append("]");
+                sb.append(",\"else_hits\":")
+                        .append(br.elseHits);
+                if (br.location != null
+                        && br.location.line() > 0)
+                {
+                    sb.append(",\"location\":{\"line\":")
+                            .append(br.location.line())
+                            .append(",\"start\":")
+                            .append(br.location.startOffset())
+                            .append(",\"end\":")
+                            .append(br.location.endOffset())
+                            .append("}");
+                }
+                sb.append("}");
+            }
+            sb.append("}");
+        }
+
+        if (!conditions.isEmpty())
+        {
+            sb.append(",\"conditions\":{");
+            boolean firstCond = true;
+            for (ConditionCoverage cond : conditions)
+            {
+                if (!firstCond)
+                {
+                    sb.append(",");
+                }
+                firstCond = false;
+                sb.append("\"")
+                        .append(cond.nodeId)
+                        .append("\":{");
+                sb.append("\"expression\":\"")
+                        .append(escapeJson(cond.expressionText))
+                        .append("\"");
+                sb.append(",\"true_hits\":")
+                        .append(cond.trueHits);
+                sb.append(",\"false_hits\":")
+                        .append(cond.falseHits);
+                if (cond.location != null
+                        && cond.location.line() > 0)
+                {
+                    sb.append(",\"location\":{\"line\":")
+                            .append(cond.location.line())
+                            .append(",\"start\":")
+                            .append(cond.location.startOffset())
+                            .append(",\"end\":")
+                            .append(cond.location.endOffset())
+                            .append("}");
+                }
+                sb.append("}");
+            }
+            sb.append("}");
+        }
+
+        sb.append("}");
+        return sb.toString();
+    }
+
+    private static String escapeJson(String s)
+    {
+        if (s == null)
+        {
+            return "";
+        }
+        return s.replace("\\", "\\\\")
+                .replace("\"", "\\\"")
+                .replace("\n", "\\n")
+                .replace("\r", "\\r")
+                .replace("\t", "\\t");
+    }
+
+    /** Coverage data for a single physical operator node. Fields are mutable to support merging. */
+    public static class OperatorCoverage
+    {
+        public final int nodeId;
+        /** Node ID of the enclosing operator in the physical plan tree, or {@code -1} for top-level operators. Used to build a hierarchical test tree. */
+        public final int parentNodeId;
+        public final String name;
+        public int executionCount;
+        public long rowsOut;
+        public boolean covered;
+        public final Location location;
+
+        /** Creates an operator coverage entry. */
+        public OperatorCoverage(int nodeId, int parentNodeId, String name, int executionCount, long rowsOut, boolean covered, Location location)
+        {
+            this.nodeId = nodeId;
+            this.parentNodeId = parentNodeId;
+            this.name = name;
+            this.executionCount = executionCount;
+            this.rowsOut = rowsOut;
+            this.covered = covered;
+            this.location = location;
+        }
+    }
+
+    /** Coverage data for a single CASE/IF expression. Fields are mutable to support merging. */
+    public static class BranchCoverage
+    {
+        public final int nodeId;
+        public final String expressionText;
+        public final long[] whenHits;
+        public long elseHits;
+        public final Location location;
+
+        /** Creates a branch coverage entry. */
+        public BranchCoverage(int nodeId, String expressionText, long[] whenHits, long elseHits, Location location)
+        {
+            this.nodeId = nodeId;
+            this.expressionText = expressionText;
+            this.whenHits = whenHits;
+            this.elseHits = elseHits;
+            this.location = location;
+        }
+    }
+
+    /** Coverage data for a single AND/OR expression — tracks how many rows the condition evaluated to true vs. false. Fields are mutable to support merging. */
+    public static class ConditionCoverage
+    {
+        public final int nodeId;
+        public final String expressionText;
+        public long trueHits;
+        public long falseHits;
+        public final Location location;
+
+        /** Creates a condition coverage entry. */
+        public ConditionCoverage(int nodeId, String expressionText, long trueHits, long falseHits, Location location)
+        {
+            this.nodeId = nodeId;
+            this.expressionText = expressionText;
+            this.trueHits = trueHits;
+            this.falseHits = falseHits;
+            this.location = location;
+        }
+    }
+}
diff --git a/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/execution/QueryCoverageRegistry.java b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/execution/QueryCoverageRegistry.java
new file mode 100644
index 000000000..cc156dc5b
--- /dev/null
+++ b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/execution/QueryCoverageRegistry.java
@@ -0,0 +1,53 @@
+package se.kuseman.payloadbuilder.core.execution;
+
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * Thread-local registry that connects the coverage-aware query execution engine to external listeners (e.g. JUnit extensions). Listeners are registered per thread so parallel test execution works
+ * without interference.
+ */
+public class QueryCoverageRegistry
+{
+    private static final ThreadLocal<List<CoverageListener>> LISTENERS = ThreadLocal.withInitial(ArrayList::new);
+
+    private QueryCoverageRegistry()
+    {
+    }
+
+    /** Registers a listener that will receive coverage data after each query execution on this thread. */
+    public static void register(CoverageListener listener)
+    {
+        LISTENERS.get()
+                .add(listener);
+    }
+
+    /** Deregisters a previously registered listener. */
+    public static void deregister(CoverageListener listener)
+    {
+        LISTENERS.get()
+                .remove(listener);
+    }
+
+    /** Returns {@code true} if at least one listener is registered on the current thread. */
+    public static boolean isEnabled()
+    {
+        return !LISTENERS.get()
+                .isEmpty();
+    }
+
+    /** Notify all registered listeners on the current thread with the given coverage data. */
+    public static void notifyListeners(QueryCoverageData data)
+    {
+        for (CoverageListener listener : LISTENERS.get())
+        {
+            listener.onQueryCoverage(data);
+        }
+    }
+
+    /** Listener notified after each query completes with coverage data. */
+    public interface CoverageListener
+    {
+        void onQueryCoverage(QueryCoverageData data);
+    }
+}
diff --git a/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/expression/ARewriteExpressionVisitor.java b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/expression/ARewriteExpressionVisitor.java
index ccc472b26..89e72df54 100644
--- a/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/expression/ARewriteExpressionVisitor.java
+++ b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/expression/ARewriteExpressionVisitor.java
@@ -183,7 +183,8 @@ public IExpression visit(ILiteralObjectExpression expression, C context)
     @Override
     public IExpression visit(ILogicalBinaryExpression expression, C context)
     {
-        return new LogicalBinaryExpression(expression.getLogicalType(), visit(expression.getLeft(), context), visit(expression.getRight(), context));
+        return new LogicalBinaryExpression(expression.getLogicalType(), visit(expression.getLeft(), context), visit(expression.getRight(), context))
+                .withLocation(((LogicalBinaryExpression) expression).getLocation());
     }
 
     @Override
diff --git a/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/expression/CaseExpression.java b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/expression/CaseExpression.java
index f7845e803..8150252f6 100644
--- a/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/expression/CaseExpression.java
+++ b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/expression/CaseExpression.java
@@ -16,6 +16,7 @@
 import se.kuseman.payloadbuilder.api.expression.ICaseExpression;
 import se.kuseman.payloadbuilder.api.expression.IExpression;
 import se.kuseman.payloadbuilder.core.execution.VectorUtils;
+import se.kuseman.payloadbuilder.core.parser.Location;
 
 import it.unimi.dsi.fastutil.ints.IntArrayList;
 import it.unimi.dsi.fastutil.ints.IntList;
@@ -25,11 +26,24 @@ public class CaseExpression implements ICaseExpression
 {
     private final List<WhenClause> whenClauses;
     private final IExpression elseExpression;
+    private final Location location;
 
     public CaseExpression(List<WhenClause> whenClauses, IExpression elseExpression)
+    {
+        this(whenClauses, elseExpression, Location.EMPTY);
+    }
+
+    public CaseExpression(List<WhenClause> whenClauses, IExpression elseExpression, Location location)
     {
         this.whenClauses = requireNonNull(whenClauses, "whenClauses");
         this.elseExpression = elseExpression;
+        this.location = location != null ? location
+                : Location.EMPTY;
+    }
+
+    public Location getLocation()
+    {
+        return location;
     }
 
     @Override
diff --git a/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/expression/InstrumentedCaseExpression.java b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/expression/InstrumentedCaseExpression.java
new file mode 100644
index 000000000..4bb6704b0
--- /dev/null
+++ b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/expression/InstrumentedCaseExpression.java
@@ -0,0 +1,129 @@
+package se.kuseman.payloadbuilder.core.expression;
+
+import static java.util.Objects.requireNonNull;
+
+import java.util.List;
+
+import se.kuseman.payloadbuilder.api.catalog.ResolvedType;
+import se.kuseman.payloadbuilder.api.execution.IExecutionContext;
+import se.kuseman.payloadbuilder.api.execution.TupleVector;
+import se.kuseman.payloadbuilder.api.execution.ValueVector;
+import se.kuseman.payloadbuilder.api.expression.ICaseExpression;
+import se.kuseman.payloadbuilder.api.expression.IExpression;
+import se.kuseman.payloadbuilder.api.expression.IExpressionVisitor;
+import se.kuseman.payloadbuilder.core.execution.CaseCoverageData;
+import se.kuseman.payloadbuilder.core.execution.VectorUtils;
+import se.kuseman.payloadbuilder.core.parser.Location;
+
+import it.unimi.dsi.fastutil.ints.IntArrayList;
+import it.unimi.dsi.fastutil.ints.IntList;
+
+/** Wraps a {@link CaseExpression} to track which WHEN branches are hit during test execution. A secondary pass evaluates WHEN conditions before the main call to count per-branch hits. */
+public class InstrumentedCaseExpression implements IExpression
+{
+    private final int nodeId;
+    private final CaseExpression wrapped;
+    private final Location location;
+
+    public InstrumentedCaseExpression(int nodeId, CaseExpression wrapped)
+    {
+        this.nodeId = nodeId;
+        this.wrapped = requireNonNull(wrapped, "wrapped");
+        this.location = wrapped.getLocation();
+    }
+
+    public int getNodeId()
+    {
+        return nodeId;
+    }
+
+    public CaseExpression getWrapped()
+    {
+        return wrapped;
+    }
+
+    public Location getLocation()
+    {
+        return location;
+    }
+
+    @Override
+    public ResolvedType getType()
+    {
+        return wrapped.getType();
+    }
+
+    @Override
+    public List<IExpression> getChildren()
+    {
+        return wrapped.getChildren();
+    }
+
+    @Override
+    public <T, C> T accept(IExpressionVisitor<T, C> visitor, C context)
+    {
+        return wrapped.accept(visitor, context);
+    }
+
+    @Override
+    public ValueVector eval(TupleVector input, IExecutionContext context)
+    {
+        return eval(input, ValueVector.range(0, input.getRowCount()), context);
+    }
+
+    @Override
+    public ValueVector eval(TupleVector input, ValueVector selection, IExecutionContext context)
+    {
+        // Track which branches were hit using the sequential-matching algorithm
+        List<ICaseExpression.WhenClause> whenClauses = wrapped.getWhenClauses();
+        int size = whenClauses.size();
+
+        CaseCoverageData data = context.getStatementContext()
+                .getOrCreateNodeData(nodeId, () -> new CaseCoverageData(size, wrapped.toString(), location));
+
+        int rowCount = selection.size();
+        IntList nonMatchedRows = new IntArrayList(rowCount);
+        for (int i = 0; i < rowCount; i++)
+        {
+            nonMatchedRows.add(selection.getInt(i));
+        }
+
+        for (int j = 0; j < size; j++)
+        {
+            ValueVector nonMatchedSelection = VectorUtils.convertToSelectionVector(nonMatchedRows);
+            ValueVector condition = whenClauses.get(j)
+                    .getCondition()
+                    .eval(input, nonMatchedSelection, context);
+
+            int currentSize = nonMatchedRows.size();
+            IntList matchedRows = new IntArrayList();
+            for (int i = 0; i < currentSize; i++)
+            {
+                if (condition.getPredicateBoolean(i))
+                {
+                    matchedRows.add(nonMatchedRows.getInt(i));
+                }
+            }
+
+            if (!matchedRows.isEmpty())
+            {
+                data.recordWhenHit(j, matchedRows.size());
+                nonMatchedRows.removeAll(matchedRows);
+            }
+        }
+
+        if (!nonMatchedRows.isEmpty())
+        {
+            data.recordElseHit(nonMatchedRows.size());
+        }
+
+        // Delegate to wrapped for the real result
+        return wrapped.eval(input, selection, context);
+    }
+
+    @Override
+    public String toString()
+    {
+        return wrapped.toString();
+    }
+}
diff --git a/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/expression/InstrumentedLogicalBinaryExpression.java b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/expression/InstrumentedLogicalBinaryExpression.java
new file mode 100644
index 000000000..13658973a
--- /dev/null
+++ b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/expression/InstrumentedLogicalBinaryExpression.java
@@ -0,0 +1,107 @@
+package se.kuseman.payloadbuilder.core.expression;
+
+import static java.util.Objects.requireNonNull;
+
+import java.util.List;
+
+import se.kuseman.payloadbuilder.api.catalog.ResolvedType;
+import se.kuseman.payloadbuilder.api.execution.IExecutionContext;
+import se.kuseman.payloadbuilder.api.execution.TupleVector;
+import se.kuseman.payloadbuilder.api.execution.ValueVector;
+import se.kuseman.payloadbuilder.api.expression.IExpression;
+import se.kuseman.payloadbuilder.api.expression.IExpressionVisitor;
+import se.kuseman.payloadbuilder.core.execution.LogicalBinaryCoverageData;
+import se.kuseman.payloadbuilder.core.parser.Location;
+
+/**
+ * Wraps a {@link LogicalBinaryExpression} to track how many rows the condition evaluates to {@code true} vs. {@code false} during test execution. Delegates all evaluation to the wrapped expression;
+ * the instrumentation is a counting pass over the result vector.
+ */
+public class InstrumentedLogicalBinaryExpression implements IExpression
+{
+    private final int nodeId;
+    private final LogicalBinaryExpression wrapped;
+    private final Location location;
+
+    public InstrumentedLogicalBinaryExpression(int nodeId, LogicalBinaryExpression wrapped)
+    {
+        this.nodeId = nodeId;
+        this.wrapped = requireNonNull(wrapped, "wrapped");
+        this.location = wrapped.getLocation();
+    }
+
+    public int getNodeId()
+    {
+        return nodeId;
+    }
+
+    public LogicalBinaryExpression getWrapped()
+    {
+        return wrapped;
+    }
+
+    public Location getLocation()
+    {
+        return location;
+    }
+
+    @Override
+    public ResolvedType getType()
+    {
+        return wrapped.getType();
+    }
+
+    @Override
+    public List<IExpression> getChildren()
+    {
+        return wrapped.getChildren();
+    }
+
+    @Override
+    public <T, C> T accept(IExpressionVisitor<T, C> visitor, C context)
+    {
+        return wrapped.accept(visitor, context);
+    }
+
+    @Override
+    public ValueVector eval(TupleVector input, IExecutionContext context)
+    {
+        return eval(input, ValueVector.range(0, input.getRowCount()), context);
+    }
+
+    @Override
+    public ValueVector eval(TupleVector input, ValueVector selection, IExecutionContext context)
+    {
+        ValueVector result = wrapped.eval(input, selection, context);
+
+        LogicalBinaryCoverageData data = context.getStatementContext()
+                .getOrCreateNodeData(nodeId, () -> new LogicalBinaryCoverageData(wrapped.getLogicalType() + " " + wrapped.getRight(), location));
+
+        int size = result.size();
+        long trueCount = 0;
+        long falseCount = 0;
+        for (int i = 0; i < size; i++)
+        {
+            if (!result.isNull(i))
+            {
+                if (result.getBoolean(i))
+                {
+                    trueCount++;
+                }
+                else
+                {
+                    falseCount++;
+                }
+            }
+        }
+        data.recordHits(trueCount, falseCount);
+
+        return result;
+    }
+
+    @Override
+    public String toString()
+    {
+        return wrapped.toString();
+    }
+}
diff --git a/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/expression/LogicalBinaryExpression.java b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/expression/LogicalBinaryExpression.java
index 1c7f7136b..5bcd1e2a6 100644
--- a/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/expression/LogicalBinaryExpression.java
+++ b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/expression/LogicalBinaryExpression.java
@@ -13,11 +13,13 @@
 import se.kuseman.payloadbuilder.api.expression.IExpression;
 import se.kuseman.payloadbuilder.api.expression.ILogicalBinaryExpression;
 import se.kuseman.payloadbuilder.core.execution.VectorUtils;
+import se.kuseman.payloadbuilder.core.parser.Location;
 
 /** AND/OR expression */
 public class LogicalBinaryExpression extends ABinaryExpression implements ILogicalBinaryExpression
 {
     private final Type type;
+    private Location location = Location.EMPTY;
 
     public LogicalBinaryExpression(Type type, IExpression left, IExpression right)
     {
@@ -25,6 +27,17 @@ public LogicalBinaryExpression(Type type, IExpression left, IExpression right)
         this.type = requireNonNull(type, "type");
     }
 
+    public Location getLocation()
+    {
+        return location;
+    }
+
+    public LogicalBinaryExpression withLocation(Location location)
+    {
+        this.location = requireNonNull(location, "location");
+        return this;
+    }
+
     @Override
     public Type getLogicalType()
     {
diff --git a/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/expression/PredicateAnalyzer.java b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/expression/PredicateAnalyzer.java
index 4fefd3bdb..cfa02c9a1 100644
--- a/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/expression/PredicateAnalyzer.java
+++ b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/expression/PredicateAnalyzer.java
@@ -8,7 +8,9 @@
 
 import java.util.ArrayList;
 import java.util.HashSet;
+import java.util.IdentityHashMap;
 import java.util.List;
+import java.util.Map;
 import java.util.Objects;
 import java.util.Set;
 
@@ -25,6 +27,7 @@
 import se.kuseman.payloadbuilder.core.catalog.ColumnReference;
 import se.kuseman.payloadbuilder.core.catalog.TableSourceReference;
 import se.kuseman.payloadbuilder.core.common.SchemaUtils;
+import se.kuseman.payloadbuilder.core.parser.Location;
 
 /**
  * Analyzes a join predicate
@@ -74,6 +77,9 @@ public static AnalyzeResult analyze(IExpression predicate)
         }
 
         List<IExpression> queue = new ArrayList<>();
+        // Maps each right-side child of an AND node to the AND token's source location,
+        // so getPredicate() can reconstruct AND nodes with their original source positions.
+        Map<IExpression, Location> andLocations = new IdentityHashMap<>();
         queue.add(predicate);
         List<AnalyzePair> resultItems = new ArrayList<>();
 
@@ -85,6 +91,12 @@ public static AnalyzeResult analyze(IExpression predicate)
                 LogicalBinaryExpression lbe = (LogicalBinaryExpression) e;
                 if (lbe.getLogicalType() == ILogicalBinaryExpression.Type.AND)
                 {
+                    // The right-side child "belongs to" this AND token in source text.
+                    if (lbe.getLocation()
+                            .line() > 0)
+                    {
+                        andLocations.put(lbe.getRight(), lbe.getLocation());
+                    }
                     queue.add(0, lbe.getLeft());
                     queue.add(0, lbe.getRight());
                     continue;
@@ -92,11 +104,19 @@ public static AnalyzeResult analyze(IExpression predicate)
             }
             else if (e instanceof NestedExpression)
             {
-                queue.add(0, ((NestedExpression) e).getExpression());
+                IExpression inner = ((NestedExpression) e).getExpression();
+                Location loc = andLocations.get(e);
+                if (loc != null)
+                {
+                    andLocations.put(inner, loc);
+                }
+                queue.add(0, inner);
                 continue;
             }
 
-            resultItems.add(AnalyzePair.of(e));
+            Location andLoc = andLocations.getOrDefault(e, Location.EMPTY);
+            resultItems.add(AnalyzePair.of(e)
+                    .withAndLocation(andLoc));
         }
 
         return new AnalyzeResult(resultItems);
@@ -180,7 +200,7 @@ public static IExpression getPredicate(List<AnalyzePair> pairs)
                 }
                 else
                 {
-                    result = new LogicalBinaryExpression(ILogicalBinaryExpression.Type.AND, result, pair.getPredicate());
+                    result = new LogicalBinaryExpression(ILogicalBinaryExpression.Type.AND, result, pair.getPredicate()).withLocation(pair.getAndLocation());
                 }
             }
             return result;
@@ -245,6 +265,19 @@ public static class AnalyzePair
         private final IComparisonExpression.Type comparisonType;
         private final AnalyzeItem left;
         private final AnalyzeItem right;
+        private Location andLocation = Location.EMPTY;
+
+        Location getAndLocation()
+        {
+            return andLocation;
+        }
+
+        AnalyzePair withAndLocation(Location loc)
+        {
+            this.andLocation = loc != null ? loc
+                    : Location.EMPTY;
+            return this;
+        }
 
         AnalyzePair(IPredicate.Type type, AnalyzeItem left, AnalyzeItem right)
         {
diff --git a/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/logicalplan/Filter.java b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/logicalplan/Filter.java
index 5a4fe8861..00b5dbfcd 100644
--- a/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/logicalplan/Filter.java
+++ b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/logicalplan/Filter.java
@@ -9,6 +9,7 @@
 import se.kuseman.payloadbuilder.api.catalog.Schema;
 import se.kuseman.payloadbuilder.api.expression.IExpression;
 import se.kuseman.payloadbuilder.core.catalog.TableSourceReference;
+import se.kuseman.payloadbuilder.core.parser.Location;
 
 /** A filter that filters input according to a predicate */
 public class Filter implements ILogicalPlan
@@ -17,6 +18,7 @@ public class Filter implements ILogicalPlan
     private final IExpression predicate;
     /** Table source that is set if this filter is a pushdown filter for a specific table source */
     private final TableSourceReference tableSource;
+    private Location location = Location.EMPTY;
 
     public Filter(ILogicalPlan input, TableSourceReference tableSource, IExpression predicate)
     {
@@ -41,6 +43,17 @@ public TableSourceReference getTableSource()
         return tableSource;
     }
 
+    public Location getLocation()
+    {
+        return location;
+    }
+
+    public Filter withLocation(Location location)
+    {
+        this.location = location;
+        return this;
+    }
+
     @Override
     public Schema getSchema()
     {
diff --git a/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/logicalplan/Join.java b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/logicalplan/Join.java
index 97767a5fa..973ca279a 100644
--- a/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/logicalplan/Join.java
+++ b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/logicalplan/Join.java
@@ -15,6 +15,7 @@
 import se.kuseman.payloadbuilder.api.expression.IExpression;
 import se.kuseman.payloadbuilder.core.catalog.TableSourceReference;
 import se.kuseman.payloadbuilder.core.common.SchemaUtils;
+import se.kuseman.payloadbuilder.core.parser.Location;
 
 /** Logical definition of a join */
 public class Join implements ILogicalPlan
@@ -32,6 +33,7 @@ public class Join implements ILogicalPlan
 
     /** The outer schema if this join is a correlated type */
     private final Schema outerSchema;
+    private Location location = Location.EMPTY;
 
     /** Constructor used during column resolving */
     public Join(ILogicalPlan outer, ILogicalPlan inner, Type type, String populateAlias, IExpression condition, Set<Column> outerReferences, boolean switchedInputs, Schema outerSchema)
@@ -86,6 +88,17 @@ public Schema getOuterSchema()
         return outerSchema;
     }
 
+    public Location getLocation()
+    {
+        return location;
+    }
+
+    public Join withLocation(Location location)
+    {
+        this.location = location;
+        return this;
+    }
+
     /** Returns true of this join can have outer references otherwise false */
     public boolean canHaveOuterReferences()
     {
diff --git a/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/logicalplan/Projection.java b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/logicalplan/Projection.java
index 2261e2faa..8678bf4fb 100644
--- a/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/logicalplan/Projection.java
+++ b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/logicalplan/Projection.java
@@ -12,6 +12,7 @@
 import se.kuseman.payloadbuilder.core.catalog.TableSourceReference;
 import se.kuseman.payloadbuilder.core.common.SchemaUtils;
 import se.kuseman.payloadbuilder.core.expression.AsteriskExpression;
+import se.kuseman.payloadbuilder.core.parser.Location;
 
 /** Projects input with a list of expressions */
 public class Projection implements ILogicalPlan
@@ -21,6 +22,7 @@ public class Projection implements ILogicalPlan
     /** Projection expressions */
     private final List<IExpression> expressions;
     private final TableSourceReference parentTableSource;
+    private Location location = Location.EMPTY;
 
     public Projection(ILogicalPlan input, List<IExpression> expressions, TableSourceReference parentTableSource)
     {
@@ -48,6 +50,17 @@ public TableSourceReference getParentTableSource()
         return parentTableSource;
     }
 
+    public Location getLocation()
+    {
+        return location;
+    }
+
+    public Projection withLocation(Location location)
+    {
+        this.location = requireNonNull(location, "location");
+        return this;
+    }
+
     /** Returns true if this projection is a single non qualified asterisk projection. */
     public boolean isAsteriskProjection()
     {
diff --git a/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/logicalplan/Sort.java b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/logicalplan/Sort.java
index c4784524e..49fcf030d 100644
--- a/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/logicalplan/Sort.java
+++ b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/logicalplan/Sort.java
@@ -8,12 +8,14 @@
 
 import se.kuseman.payloadbuilder.api.catalog.Schema;
 import se.kuseman.payloadbuilder.core.common.SortItem;
+import se.kuseman.payloadbuilder.core.parser.Location;
 
 /** Logical sort. Sorts input by sort items */
 public class Sort implements ILogicalPlan
 {
     private final ILogicalPlan input;
     private final List<SortItem> sortItems;
+    private Location location = Location.EMPTY;
 
     public Sort(ILogicalPlan input, List<SortItem> sortItems)
     {
@@ -21,6 +23,17 @@ public Sort(ILogicalPlan input, List<SortItem> sortItems)
         this.sortItems = requireNonNull(sortItems, "sortItems");
     }
 
+    public Location getLocation()
+    {
+        return location;
+    }
+
+    public Sort withLocation(Location location)
+    {
+        this.location = requireNonNull(location, "location");
+        return this;
+    }
+
     public ILogicalPlan getInput()
     {
         return input;
diff --git a/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/logicalplan/optimization/ALogicalPlanOptimizer.java b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/logicalplan/optimization/ALogicalPlanOptimizer.java
index 2809476c0..b3c223101 100644
--- a/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/logicalplan/optimization/ALogicalPlanOptimizer.java
+++ b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/logicalplan/optimization/ALogicalPlanOptimizer.java
@@ -379,7 +379,7 @@ protected ILogicalPlan create(Projection plan, C context)
             expressions = visit(plan, plan.getExpressions(), context);
         }
         return new Projection(plan.getInput()
-                .accept(this, context), expressions, plan.getParentTableSource());
+                .accept(this, context), expressions, plan.getParentTableSource()).withLocation(plan.getLocation());
     }
 
     protected ILogicalPlan create(Aggregate plan, C context)
@@ -427,7 +427,7 @@ protected ILogicalPlan create(Join plan, C context)
                 .accept(this, context),
                 plan.getInner()
                         .accept(this, context),
-                plan.getType(), plan.getPopulateAlias(), condition, plan.getOuterReferences(), plan.isSwitchedInputs(), plan.getOuterSchema());
+                plan.getType(), plan.getPopulateAlias(), condition, plan.getOuterReferences(), plan.isSwitchedInputs(), plan.getOuterSchema()).withLocation(plan.getLocation());
     }
 
     protected ILogicalPlan create(Sort plan, C context)
@@ -450,7 +450,7 @@ protected ILogicalPlan create(Sort plan, C context)
                 .collect(toList());
 
         return new Sort(plan.getInput()
-                .accept(this, context), sortItems);
+                .accept(this, context), sortItems).withLocation(plan.getLocation());
     }
 
     protected ILogicalPlan create(Filter plan, C context)
@@ -465,7 +465,7 @@ protected ILogicalPlan create(Filter plan, C context)
             predicate = visit(plan, predicate, context);
         }
         return new Filter(plan.getInput()
-                .accept(this, context), plan.getTableSource(), predicate);
+                .accept(this, context), plan.getTableSource(), predicate).withLocation(plan.getLocation());
     }
 
     protected ILogicalPlan create(SubQuery plan, C context)
diff --git a/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/logicalplan/optimization/ColumnOrdinalResolver.java b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/logicalplan/optimization/ColumnOrdinalResolver.java
index 59af891df..c0163397e 100644
--- a/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/logicalplan/optimization/ColumnOrdinalResolver.java
+++ b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/logicalplan/optimization/ColumnOrdinalResolver.java
@@ -79,7 +79,7 @@ public ILogicalPlan visit(Projection plan, Ctx context)
         context.schema = prevSchema;
         context.outerSchema = prevOuterSchema;
 
-        return new Projection(input, expressions, plan.getParentTableSource());
+        return new Projection(input, expressions, plan.getParentTableSource()).withLocation(plan.getLocation());
     }
 
     @Override
@@ -91,7 +91,7 @@ public ILogicalPlan visit(Filter plan, Ctx context)
         context.schema = input.getSchema();
 
         IExpression e = ColumnOrdinalRewriter.INSTANCE.visit(plan.getPredicate(), context);
-        return new Filter(input, plan.getTableSource(), e);
+        return new Filter(input, plan.getTableSource(), e).withLocation(plan.getLocation());
     }
 
     @Override
@@ -111,7 +111,7 @@ public ILogicalPlan visit(Sort plan, Ctx context)
                 })
                 .collect(toList());
 
-        return new Sort(input, sortItems);
+        return new Sort(input, sortItems).withLocation(plan.getLocation());
     }
 
     @Override
@@ -143,7 +143,7 @@ public ILogicalPlan visit(Join plan, Ctx context)
 
         context.outerSchema = prevOuterSchema;
 
-        return new Join(outer, inner, plan.getType(), plan.getPopulateAlias(), condition, plan.getOuterReferences(), plan.isSwitchedInputs(), plan.getOuterSchema());
+        return new Join(outer, inner, plan.getType(), plan.getPopulateAlias(), condition, plan.getOuterReferences(), plan.isSwitchedInputs(), plan.getOuterSchema()).withLocation(plan.getLocation());
     }
 
     @Override
diff --git a/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/logicalplan/optimization/ColumnResolver.java b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/logicalplan/optimization/ColumnResolver.java
index 6e080b341..1009223fb 100644
--- a/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/logicalplan/optimization/ColumnResolver.java
+++ b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/logicalplan/optimization/ColumnResolver.java
@@ -206,7 +206,7 @@ public ILogicalPlan visit(Projection plan, Ctx context)
         // the sub query table source since that is what resolving has resolved against but at runtime
         // the subquey operator is removed and hence we need to retain it's table source when expanding asteriskts etc.
         TableSourceReference parentTableSourceReference = context.subQueryTableSource.peek();
-        ILogicalPlan result = new Projection(input, expressions, parentTableSourceReference);
+        ILogicalPlan result = new Projection(input, expressions, parentTableSourceReference).withLocation(plan.getLocation());
         context.planSchema.push(new ResolveSchema(result.getSchema()));
         return result;
     }
@@ -223,7 +223,7 @@ public ILogicalPlan visit(Filter plan, Ctx context)
         context.schema = schema;
         IExpression predicate = ColumnResolverVisitor.rewrite(context, plan.getPredicate());
 
-        ILogicalPlan result = new Filter(input, plan.getTableSource(), predicate);
+        ILogicalPlan result = new Filter(input, plan.getTableSource(), predicate).withLocation(plan.getLocation());
 
         context.planSchema.push(schema);
         return result;
@@ -250,7 +250,7 @@ public ILogicalPlan visit(Sort plan, Ctx context)
                 .map(si -> new SortItem(ColumnResolverVisitor.rewrite(context, si.getExpression()), si.getOrder(), si.getNullOrder(), si.getLocation()))
                 .collect(toList());
 
-        ILogicalPlan result = new Sort(input, sortItems);
+        ILogicalPlan result = new Sort(input, sortItems).withLocation(plan.getLocation());
         context.planSchema.push(schema);
         return result;
     }
@@ -391,7 +391,7 @@ else if (prevOuterReferences != null)
         }
 
         // CSOFF
-        Join result = new Join(outer, inner, plan.getType(), plan.getPopulateAlias(), condition, context.outerReferences, plan.isSwitchedInputs(), outerSchema);
+        Join result = new Join(outer, inner, plan.getType(), plan.getPopulateAlias(), condition, context.outerReferences, plan.isSwitchedInputs(), outerSchema).withLocation(plan.getLocation());
         // CSON
 
         // Restore context values
diff --git a/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/logicalplan/optimization/ComputedExpressionPushDown.java b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/logicalplan/optimization/ComputedExpressionPushDown.java
index 24e590b48..545913fb0 100644
--- a/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/logicalplan/optimization/ComputedExpressionPushDown.java
+++ b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/logicalplan/optimization/ComputedExpressionPushDown.java
@@ -114,7 +114,7 @@ public ILogicalPlan visit(Sort plan, Ctx context)
                 .accept(this, context);
         List<SortItem> result = planData.sortItems;
         planData.sortItems = emptyList();
-        return new Sort(sortInput, result);
+        return new Sort(sortInput, result).withLocation(plan.getLocation());
     }
 
     @Override
@@ -187,7 +187,7 @@ else if (e instanceof HasAlias alias)
         if (planData.sortItems.isEmpty())
         {
             return new Projection(plan.getInput()
-                    .accept(this, context), projectionExpressions, plan.getParentTableSource());
+                    .accept(this, context), projectionExpressions, plan.getParentTableSource()).withLocation(plan.getLocation());
         }
 
         List<IExpression> newProjectionExpressions = new ArrayList<>(projectionExpressions);
@@ -342,7 +342,7 @@ else if (isComputed(projectionExpression))
         ILogicalPlan input = plan.getInput()
                 .accept(this, context);
 
-        return new Projection(input, newProjectionExpressions, plan.getParentTableSource());
+        return new Projection(input, newProjectionExpressions, plan.getParentTableSource()).withLocation(plan.getLocation());
     }
 
     @Override
@@ -367,7 +367,7 @@ public ILogicalPlan visit(Filter plan, Ctx context)
                 return input;
             }
 
-            return new Filter(input, plan.getTableSource(), filterPredicate);
+            return new Filter(input, plan.getTableSource(), filterPredicate).withLocation(plan.getLocation());
         }
 
         return super.create(plan, context);
diff --git a/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/logicalplan/optimization/PredicatePushDown.java b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/logicalplan/optimization/PredicatePushDown.java
index 014946b61..927d62e3f 100644
--- a/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/logicalplan/optimization/PredicatePushDown.java
+++ b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/logicalplan/optimization/PredicatePushDown.java
@@ -211,10 +211,20 @@ public ILogicalPlan visit(Filter plan, Ctx context)
         // If all predicate pairs was used then no filter should be used here, return input
         if (predicate == null)
         {
+            // Propagate the WHERE clause location to the push-down filter so the annotated
+            // SQL gutter can mark the WHERE line when all predicates are fully index-seeked.
+            if (plan.getLocation()
+                    .line() > 0
+                    && input instanceof Filter pushed
+                    && pushed.getLocation()
+                            .line() == 0)
+            {
+                pushed.withLocation(plan.getLocation());
+            }
             return input;
         }
 
-        return new Filter(input, plan.getTableSource(), predicate);
+        return new Filter(input, plan.getTableSource(), predicate).withLocation(plan.getLocation());
     }
 
     @Override
@@ -295,6 +305,7 @@ public ILogicalPlan visit(Join plan, Ctx context)
         AnalyzeResult analyzeResult = context.analyzeResults.remove(resultIndex)
                 .getValue();
 
-        return new Join(outer, inner, plan.getType(), plan.getPopulateAlias(), analyzeResult.getPredicate(), plan.getOuterReferences(), plan.isSwitchedInputs(), plan.getOuterSchema());
+        return new Join(outer, inner, plan.getType(), plan.getPopulateAlias(), analyzeResult.getPredicate(), plan.getOuterReferences(), plan.isSwitchedInputs(), plan.getOuterSchema())
+                .withLocation(plan.getLocation());
     }
 }
diff --git a/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/logicalplan/optimization/SubQueryExpressionPushDown.java b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/logicalplan/optimization/SubQueryExpressionPushDown.java
index bec3c9c4c..77e40daf1 100644
--- a/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/logicalplan/optimization/SubQueryExpressionPushDown.java
+++ b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/logicalplan/optimization/SubQueryExpressionPushDown.java
@@ -363,7 +363,7 @@ && returnsAtLeastOneRow(plan))
                 ILogicalPlan left = ctx.current;
                 ILogicalPlan right = plan;
 
-                ctx.current = new Join(left, right, Join.Type.LEFT, null, (IExpression) null, emptySet(), false, Schema.EMPTY);
+                ctx.current = new Join(left, right, Join.Type.LEFT, null, (IExpression) null, emptySet(), false, Schema.EMPTY).withLocation(expression.getLocation());
             }
             // Return an unresolved column that will be resolved as an ordinary column at next stage (ColumnResolver)
             return new UnresolvedColumnExpression(QualifiedName.of(alias), -1, expression.getLocation());
diff --git a/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/parser/QueryParser.java b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/parser/QueryParser.java
index e5bb06776..6ac74372e 100644
--- a/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/parser/QueryParser.java
+++ b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/parser/QueryParser.java
@@ -27,6 +27,7 @@
 import org.antlr.v4.runtime.TokenStream;
 import org.antlr.v4.runtime.atn.PredictionMode;
 import org.antlr.v4.runtime.misc.ParseCancellationException;
+import org.antlr.v4.runtime.tree.TerminalNode;
 import org.apache.commons.lang3.EnumUtils;
 import org.apache.commons.lang3.StringUtils;
 
@@ -672,7 +673,7 @@ else if (joinCtx.RIGHT() != null)
                 String joinAlias = getIdentifier(joinCtx.tableSource()
                         .identifier());
                 current = new Join(current, joinTableSource, type, populate ? joinAlias
-                        : null, condition, emptySet(), false, Schema.EMPTY);
+                        : null, condition, emptySet(), false, Schema.EMPTY).withLocation(Location.from(joinCtx));
             }
 
             return current;
@@ -832,7 +833,7 @@ public Object visitCaseExpression(CaseExpressionContext ctx)
 
             IExpression elseExpression = getExpression(ctx.elseExpr);
 
-            return new CaseExpression(whenClauses, elseExpression);
+            return new CaseExpression(whenClauses, elseExpression, Location.from(ctx));
         }
 
         @Override
@@ -1108,13 +1109,13 @@ public Object visitExpr_compare(Expr_compareContext ctx)
         @Override
         public Object visitExpr_and(Expr_andContext ctx)
         {
-            return buildLogicalTree(ILogicalBinaryExpression.Type.AND, ctx.left, ctx.right);
+            return buildLogicalTree(ILogicalBinaryExpression.Type.AND, ctx.left, ctx.right, ctx.AND());
         }
 
         @Override
         public Object visitExpr_or(Expr_orContext ctx)
         {
-            return buildLogicalTree(ILogicalBinaryExpression.Type.OR, ctx.left, ctx.right);
+            return buildLogicalTree(ILogicalBinaryExpression.Type.OR, ctx.left, ctx.right, ctx.OR());
         }
 
         @Override
@@ -1401,7 +1402,7 @@ private IExpression wrapIndirection(IExpression target, List<IndirectionContext>
             return result;
         }
 
-        private IExpression buildLogicalTree(ILogicalBinaryExpression.Type type, ParserRuleContext left, List<? extends ParserRuleContext> right)
+        private IExpression buildLogicalTree(ILogicalBinaryExpression.Type type, ParserRuleContext left, List<? extends ParserRuleContext> right, List<TerminalNode> operators)
         {
             IExpression le = getExpression(left);
 
@@ -1411,23 +1412,19 @@ private IExpression buildLogicalTree(ILogicalBinaryExpression.Type type, ParserR
                 return le;
             }
 
-            IExpression result = null;
-
             List<IExpression> rightList = right.stream()
                     .map(e -> (IExpression) visit(e))
                     .collect(toList());
 
+            IExpression result = le;
+
             // TODO: This could be kept as a list to avoid building a tree
-            for (IExpression r : rightList)
+            // Each binary node uses its own operator token location so multi-line AND/OR chains
+            // produce per-line condition coverage entries in the annotated SQL report.
+            for (int i = 0; i < rightList.size(); i++)
             {
-                if (result == null)
-                {
-                    result = new LogicalBinaryExpression(type, le, r).fold();
-                }
-                else
-                {
-                    result = new LogicalBinaryExpression(type, result, r).fold();
-                }
+                result = new LogicalBinaryExpression(type, result, rightList.get(i)).withLocation(Location.from(operators.get(i)))
+                        .fold();
             }
 
             return result;
@@ -1573,7 +1570,7 @@ else if (containsAsterisks
                 return ConstantScan.create(expressions, Location.from(ctx.SELECT()));
             }
 
-            return new Projection(plan, expressions, null);
+            return new Projection(plan, expressions, null).withLocation(Location.from(ctx.SELECT()));
         }
 
         private ILogicalPlan wrapSort(ILogicalPlan plan, SelectStatementContext ctx)
@@ -1585,7 +1582,7 @@ private ILogicalPlan wrapSort(ILogicalPlan plan, SelectStatementContext ctx)
                         .stream()
                         .map(this::getSortItem)
                         .collect(toList());
-                plan = new Sort(plan, orderBy);
+                plan = new Sort(plan, orderBy).withLocation(Location.from(ctx.sortItem(0)));
             }
             return plan;
         }
@@ -1671,7 +1668,7 @@ private ILogicalPlan wrapFilter(ILogicalPlan plan, SelectStatementContext ctx)
         {
             if (ctx.where != null)
             {
-                plan = new Filter(plan, null, getExpression(ctx.where));
+                plan = new Filter(plan, null, getExpression(ctx.where)).withLocation(Location.from(ctx.where));
             }
             return plan;
         }
@@ -1680,7 +1677,7 @@ private ILogicalPlan wrapHaving(ILogicalPlan plan, SelectStatementContext ctx)
         {
             if (ctx.having != null)
             {
-                plan = new Filter(plan, null, getExpression(ctx.having));
+                plan = new Filter(plan, null, getExpression(ctx.having)).withLocation(Location.from(ctx.having));
             }
             return plan;
         }
diff --git a/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/physicalplan/AnalyzeInterceptor.java b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/physicalplan/AnalyzeInterceptor.java
index 8c9efe1e7..c8856f34b 100644
--- a/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/physicalplan/AnalyzeInterceptor.java
+++ b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/physicalplan/AnalyzeInterceptor.java
@@ -114,6 +114,12 @@ public int hashCode()
         return nodeId;
     }
 
+    @Override
+    public boolean hasWritableOutput()
+    {
+        return input.hasWritableOutput();
+    }
+
     @Override
     public boolean equals(Object obj)
     {
diff --git a/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/physicalplan/CoveragePlan.java b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/physicalplan/CoveragePlan.java
new file mode 100644
index 000000000..661cd66da
--- /dev/null
+++ b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/physicalplan/CoveragePlan.java
@@ -0,0 +1,243 @@
+package se.kuseman.payloadbuilder.core.physicalplan;
+
+import static java.util.Collections.singletonList;
+import static java.util.Objects.requireNonNull;
+
+import java.util.ArrayList;
+import java.util.Comparator;
+import java.util.List;
+import java.util.Map;
+
+import se.kuseman.payloadbuilder.api.catalog.Schema;
+import se.kuseman.payloadbuilder.api.execution.IExecutionContext;
+import se.kuseman.payloadbuilder.api.execution.NodeData;
+import se.kuseman.payloadbuilder.api.execution.TupleIterator;
+import se.kuseman.payloadbuilder.api.execution.TupleVector;
+import se.kuseman.payloadbuilder.core.common.DescribableNode;
+import se.kuseman.payloadbuilder.core.execution.CaseCoverageData;
+import se.kuseman.payloadbuilder.core.execution.LogicalBinaryCoverageData;
+import se.kuseman.payloadbuilder.core.execution.QueryCoverageData;
+import se.kuseman.payloadbuilder.core.execution.QueryCoverageData.BranchCoverage;
+import se.kuseman.payloadbuilder.core.execution.QueryCoverageData.ConditionCoverage;
+import se.kuseman.payloadbuilder.core.execution.QueryCoverageData.OperatorCoverage;
+import se.kuseman.payloadbuilder.core.execution.QueryCoverageRegistry;
+import se.kuseman.payloadbuilder.core.execution.StatementContext;
+import se.kuseman.payloadbuilder.core.parser.Location;
+
+/**
+ * Physical plan that executes a query with full ANALYZE instrumentation, buffers result rows, appends a {@code __coverage__} column with coverage JSON and notifies {@link QueryCoverageRegistry}
+ * listeners. Injected by {@link se.kuseman.payloadbuilder.core.planning.StatementRewriter} when coverage is enabled.
+ */
+public class CoveragePlan implements IPhysicalPlan
+{
+    /** Name of the coverage metadata column appended to every result set when coverage is active. */
+    public static final String COVERAGE_COLUMN = CoverageTupleVector.COVERAGE_COLUMN;
+
+    private final int nodeId;
+    private final IPhysicalPlan input;
+    private final Map<Integer, Location> nodeLocations;
+    private final String queryName;
+
+    public CoveragePlan(int nodeId, IPhysicalPlan input, Map<Integer, Location> nodeLocations)
+    {
+        this(nodeId, input, nodeLocations, null);
+    }
+
+    public CoveragePlan(int nodeId, IPhysicalPlan input, Map<Integer, Location> nodeLocations, String queryName)
+    {
+        this.nodeId = nodeId;
+        this.input = requireNonNull(input, "input");
+        this.nodeLocations = requireNonNull(nodeLocations, "nodeLocations");
+        this.queryName = queryName;
+    }
+
+    @Override
+    public int getNodeId()
+    {
+        return nodeId;
+    }
+
+    @Override
+    public Schema getSchema()
+    {
+        return Schema.EMPTY;
+    }
+
+    @Override
+    public String getName()
+    {
+        return "Coverage";
+    }
+
+    @Override
+    public TupleIterator execute(IExecutionContext context)
+    {
+        // 1. Execute inner plan (ANALYZE interceptors are active), buffer all rows
+        List<TupleVector> buffer = new ArrayList<>();
+        TupleIterator it = input.execute(context);
+        try
+        {
+            while (it.hasNext())
+            {
+                buffer.add(it.next());
+            }
+        }
+        finally
+        {
+            it.close();
+        }
+
+        // 2. Collect coverage data from StatementContext
+        StatementContext stmtContext = (StatementContext) context.getStatementContext();
+        List<OperatorCoverage> operators = collectOperatorCoverage(input, stmtContext, nodeLocations);
+        List<BranchCoverage> branches = collectBranchCoverage(stmtContext);
+        List<ConditionCoverage> conditions = collectConditionCoverage(stmtContext);
+
+        String queryKey = queryName != null ? queryName
+                : String.format("%08x", Math.abs(input.print(0)
+                        .hashCode()));
+        QueryCoverageData coverageData = new QueryCoverageData(queryKey, operators, branches, conditions);
+        String coverageJson = coverageData.toJson();
+
+        // 3. Notify listeners (JUnit extension etc.)
+        QueryCoverageRegistry.notifyListeners(coverageData);
+
+        // 4. Wrap buffered rows with coverage column and return
+        if (buffer.isEmpty())
+        {
+            return TupleIterator.EMPTY;
+        }
+
+        List<TupleVector> covered = new ArrayList<>(buffer.size());
+        for (TupleVector tv : buffer)
+        {
+            covered.add(new CoverageTupleVector(tv, coverageJson));
+        }
+
+        return new TupleIterator()
+        {
+            private int index = 0;
+
+            @Override
+            public TupleVector next()
+            {
+                return covered.get(index++);
+            }
+
+            @Override
+            public boolean hasNext()
+            {
+                return index < covered.size();
+            }
+        };
+    }
+
+    @Override
+    public boolean hasWritableOutput()
+    {
+        // Delegate so CoveragePlan(InsertInto) is treated as non-writable and auto-executed
+        // by the query runner without requiring an explicit consumeResult() call from tests.
+        return input.hasWritableOutput();
+    }
+
+    @Override
+    public List<IPhysicalPlan> getChildren()
+    {
+        return singletonList(input);
+    }
+
+    @Override
+    public List<DescribableNode> getChildNodes()
+    {
+        return singletonList(input);
+    }
+
+    @Override
+    public int hashCode()
+    {
+        return nodeId;
+    }
+
+    @Override
+    public boolean equals(Object obj)
+    {
+        if (obj instanceof CoveragePlan that)
+        {
+            return nodeId == that.nodeId
+                    && input.equals(that.input);
+        }
+        return false;
+    }
+
+    @Override
+    public String toString()
+    {
+        return "Coverage Plan (" + nodeId + ")";
+    }
+
+    private static List<OperatorCoverage> collectOperatorCoverage(IPhysicalPlan plan, StatementContext stmtContext, Map<Integer, Location> nodeLocations)
+    {
+        List<OperatorCoverage> result = new ArrayList<>();
+        collectOperators(plan, stmtContext, nodeLocations, result, -1);
+        // Sort ascending by source line so the report mirrors SQL top-to-bottom order.
+        // Operators without location info (line <= 0) sort to the end.
+        result.sort(Comparator.comparingInt(op -> op.location != null
+                && op.location.line() > 0 ? op.location.line()
+                        : Integer.MAX_VALUE));
+        return result;
+    }
+
+    private static void collectOperators(IPhysicalPlan plan, StatementContext stmtContext, Map<Integer, Location> nodeLocations, List<OperatorCoverage> result, int parentNodeId)
+    {
+        if (plan instanceof AnalyzeInterceptor ai)
+        {
+            int aiNodeId = ai.getActualNodeId();
+            NodeData data = stmtContext.getNodeData(aiNodeId);
+            Location loc = nodeLocations.getOrDefault(aiNodeId, Location.EMPTY);
+            int execCount = data != null ? data.getExecutionCount()
+                    : 0;
+            long rowsOut = data != null ? data.getRowCount()
+                    : 0;
+            boolean covered = execCount > 0;
+            result.add(new OperatorCoverage(aiNodeId, parentNodeId, ai.getName(), execCount, rowsOut, covered, loc));
+            // Children use this node's ID as their parent — transparent non-AI wrappers pass the ID through
+            collectOperators(ai.getInput(), stmtContext, nodeLocations, result, aiNodeId);
+        }
+        else
+        {
+            for (IPhysicalPlan child : plan.getChildren())
+            {
+                // Non-AI nodes are transparent: children stay under the same parent
+                collectOperators(child, stmtContext, nodeLocations, result, parentNodeId);
+            }
+        }
+    }
+
+    private static List<BranchCoverage> collectBranchCoverage(StatementContext stmtContext)
+    {
+        List<BranchCoverage> result = new ArrayList<>();
+        for (Map.Entry<Integer, ? extends NodeData> entry : stmtContext.getNodeData()
+                .entrySet())
+        {
+            if (entry.getValue() instanceof CaseCoverageData cd)
+            {
+                result.add(new BranchCoverage(entry.getKey(), cd.getExpressionText(), cd.getWhenHits(), cd.getElseHits(), cd.getLocation()));
+            }
+        }
+        return result;
+    }
+
+    private static List<ConditionCoverage> collectConditionCoverage(StatementContext stmtContext)
+    {
+        List<ConditionCoverage> result = new ArrayList<>();
+        for (Map.Entry<Integer, ? extends NodeData> entry : stmtContext.getNodeData()
+                .entrySet())
+        {
+            if (entry.getValue() instanceof LogicalBinaryCoverageData ld)
+            {
+                result.add(new ConditionCoverage(entry.getKey(), ld.getExpressionText(), ld.getTrueHits(), ld.getFalseHits(), ld.getLocation()));
+            }
+        }
+        return result;
+    }
+}
diff --git a/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/physicalplan/CoverageTupleVector.java b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/physicalplan/CoverageTupleVector.java
new file mode 100644
index 000000000..29f776338
--- /dev/null
+++ b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/physicalplan/CoverageTupleVector.java
@@ -0,0 +1,64 @@
+package se.kuseman.payloadbuilder.core.physicalplan;
+
+import static java.util.Objects.requireNonNull;
+
+import java.util.ArrayList;
+import java.util.List;
+
+import se.kuseman.payloadbuilder.api.catalog.Column;
+import se.kuseman.payloadbuilder.api.catalog.Column.Type;
+import se.kuseman.payloadbuilder.api.catalog.Schema;
+import se.kuseman.payloadbuilder.api.execution.TupleVector;
+import se.kuseman.payloadbuilder.api.execution.ValueVector;
+
+/** Wraps a {@link TupleVector} adding a {@code __coverage__} string column containing coverage JSON. */
+class CoverageTupleVector implements TupleVector
+{
+    static final String COVERAGE_COLUMN = "__coverage__";
+
+    private final TupleVector delegate;
+    private final ValueVector coverageColumn;
+    private Schema schema;
+
+    CoverageTupleVector(TupleVector delegate, String coverageJson)
+    {
+        this.delegate = requireNonNull(delegate, "delegate");
+        this.coverageColumn = ValueVector.literalString(coverageJson, delegate.getRowCount());
+    }
+
+    @Override
+    public int getRowCount()
+    {
+        return delegate.getRowCount();
+    }
+
+    @Override
+    public ValueVector getColumn(int column)
+    {
+        int delegateSize = delegate.getSchema()
+                .getSize();
+        if (column < delegateSize)
+        {
+            return delegate.getColumn(column);
+        }
+        return coverageColumn;
+    }
+
+    @Override
+    public Schema getSchema()
+    {
+        if (schema == null)
+        {
+            schema = buildSchema();
+        }
+        return schema;
+    }
+
+    private Schema buildSchema()
+    {
+        List<Column> columns = new ArrayList<>(delegate.getSchema()
+                .getColumns());
+        columns.add(Column.of(COVERAGE_COLUMN, Type.String));
+        return Schema.of(columns.toArray(new Column[0]));
+    }
+}
diff --git a/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/physicalplan/TableScan.java b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/physicalplan/TableScan.java
index a64c82766..2db1ac8c2 100644
--- a/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/physicalplan/TableScan.java
+++ b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/physicalplan/TableScan.java
@@ -47,6 +47,11 @@ public TableScan(int nodeId, Schema schema, TableSourceReference tableSource, St
         this.asteriskSchema = SchemaUtils.isAsterisk(schema);
     }
 
+    public TableSourceReference getTableSource()
+    {
+        return tableSource;
+    }
+
     @Override
     public int getNodeId()
     {
diff --git a/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/planning/CoverageExpressionRewriter.java b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/planning/CoverageExpressionRewriter.java
new file mode 100644
index 000000000..0144956fc
--- /dev/null
+++ b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/planning/CoverageExpressionRewriter.java
@@ -0,0 +1,66 @@
+package se.kuseman.payloadbuilder.core.planning;
+
+import static java.util.stream.Collectors.toList;
+
+import java.util.List;
+
+import se.kuseman.payloadbuilder.api.expression.ICaseExpression;
+import se.kuseman.payloadbuilder.api.expression.IExpression;
+import se.kuseman.payloadbuilder.api.expression.ILogicalBinaryExpression;
+import se.kuseman.payloadbuilder.core.expression.ARewriteExpressionVisitor;
+import se.kuseman.payloadbuilder.core.expression.CaseExpression;
+import se.kuseman.payloadbuilder.core.expression.InstrumentedCaseExpression;
+import se.kuseman.payloadbuilder.core.expression.InstrumentedLogicalBinaryExpression;
+import se.kuseman.payloadbuilder.core.expression.LogicalBinaryExpression;
+
+/**
+ * Expression visitor that replaces {@link CaseExpression} nodes with {@link InstrumentedCaseExpression} and {@link LogicalBinaryExpression} nodes with {@link InstrumentedLogicalBinaryExpression} for
+ * branch/condition coverage tracking. Children are visited first so nested expressions are also instrumented.
+ */
+class CoverageExpressionRewriter extends ARewriteExpressionVisitor<StatementPlanner.Context>
+{
+    static final CoverageExpressionRewriter INSTANCE = new CoverageExpressionRewriter();
+
+    static IExpression rewrite(StatementPlanner.Context context, IExpression expression)
+    {
+        if (expression == null)
+        {
+            return null;
+        }
+        return expression.accept(INSTANCE, context);
+    }
+
+    @Override
+    public IExpression visit(ICaseExpression expression, StatementPlanner.Context context)
+    {
+        // Visit children first to instrument nested CASE expressions
+        List<ICaseExpression.WhenClause> whenClauses = expression.getWhenClauses()
+                .stream()
+                .map(w -> new ICaseExpression.WhenClause(visit(w.getCondition(), context), visit(w.getResult(), context)))
+                .collect(toList());
+        IExpression elseExpr = expression.getElseExpression() != null ? visit(expression.getElseExpression(), context)
+                : null;
+
+        // Preserve location from the original CaseExpression
+        CaseExpression rewritten = expression instanceof CaseExpression ce ? new CaseExpression(whenClauses, elseExpr, ce.getLocation())
+                : new CaseExpression(whenClauses, elseExpr);
+
+        return new InstrumentedCaseExpression(context.getNextNodeId(), rewritten);
+    }
+
+    @Override
+    public IExpression visit(ILogicalBinaryExpression expression, StatementPlanner.Context context)
+    {
+        // Visit children first so nested AND/OR are also instrumented
+        IExpression left = visit(expression.getLeft(), context);
+        IExpression right = visit(expression.getRight(), context);
+
+        LogicalBinaryExpression rebuilt = new LogicalBinaryExpression(expression.getLogicalType(), left, right);
+        if (expression instanceof LogicalBinaryExpression lbe)
+        {
+            rebuilt.withLocation(lbe.getLocation());
+        }
+
+        return new InstrumentedLogicalBinaryExpression(context.getNextNodeId(), rebuilt);
+    }
+}
diff --git a/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/planning/QueryPlanner.java b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/planning/QueryPlanner.java
index 0b951a2ce..37038fec1 100644
--- a/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/planning/QueryPlanner.java
+++ b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/planning/QueryPlanner.java
@@ -9,6 +9,7 @@
 import java.util.List;
 import java.util.Set;
 import java.util.function.BiFunction;
+import java.util.stream.Collectors;
 
 import org.apache.commons.lang3.tuple.Pair;
 
@@ -31,11 +32,13 @@
 import se.kuseman.payloadbuilder.api.expression.IFunctionCallExpression;
 import se.kuseman.payloadbuilder.api.expression.IInExpression;
 import se.kuseman.payloadbuilder.api.expression.ILikeExpression;
+import se.kuseman.payloadbuilder.api.expression.ILiteralIntegerExpression;
 import se.kuseman.payloadbuilder.api.expression.ILogicalBinaryExpression;
 import se.kuseman.payloadbuilder.api.expression.INullPredicateExpression;
 import se.kuseman.payloadbuilder.core.catalog.ColumnReference;
 import se.kuseman.payloadbuilder.core.catalog.TableSourceReference;
 import se.kuseman.payloadbuilder.core.common.SchemaUtils;
+import se.kuseman.payloadbuilder.core.common.SortItem;
 import se.kuseman.payloadbuilder.core.execution.QuerySession;
 import se.kuseman.payloadbuilder.core.expression.AExpressionVisitor;
 import se.kuseman.payloadbuilder.core.expression.AliasExpression;
@@ -109,7 +112,14 @@ else if (input instanceof AnalyzeInterceptor ai
             parentTableSource = p.getParentTableSource();
         }
 
-        return wrapWithAnalyze(context, new se.kuseman.payloadbuilder.core.physicalplan.Projection(context.getNextNodeId(), input, schema, expressions, parentTableSource));
+        if (context.coverageMode)
+        {
+            expressions = expressions.stream()
+                    .map(e -> CoverageExpressionRewriter.rewrite(context, e))
+                    .collect(Collectors.toList());
+        }
+
+        return wrapWithAnalyze(context, new se.kuseman.payloadbuilder.core.physicalplan.Projection(context.getNextNodeId(), input, schema, expressions, parentTableSource), plan.getLocation());
     }
 
     @Override
@@ -157,7 +167,14 @@ public IPhysicalPlan visit(Sort plan, Context context)
             return input;
         }
 
-        return wrapWithAnalyze(context, new se.kuseman.payloadbuilder.core.physicalplan.Sort(context.getNextNodeId(), input, plan.getSortItems()));
+        List<SortItem> sortItems = plan.getSortItems();
+        if (context.coverageMode)
+        {
+            sortItems = sortItems.stream()
+                    .map(si -> new SortItem(CoverageExpressionRewriter.rewrite(context, si.getExpression()), si.getOrder(), si.getNullOrder(), si.getLocation()))
+                    .collect(toList());
+        }
+        return wrapWithAnalyze(context, new se.kuseman.payloadbuilder.core.physicalplan.Sort(context.getNextNodeId(), input, sortItems), plan.getLocation());
     }
 
     @Override
@@ -177,14 +194,22 @@ public IPhysicalPlan visit(Filter plan, Context context)
         IExpression predicate = plan.getPredicate();
         if (tableSourcePushDown != null)
         {
-            // All predicate pairs was consumed skip filter and return input
+            // All predicate pairs was consumed — normally skip filter, but in coverage mode keep
+            // the full original predicate so AND/OR branches in ON/WHERE clauses can be tracked.
             if (tableSourcePushDown.predicatePairs.isEmpty())
             {
-                return input;
+                if (!context.coverageMode)
+                {
+                    return wrapWithAnalyze(context, input, plan.getLocation());
+                }
+                // Coverage mode: fall through with the full original predicate so that
+                // AND/OR branches in pushed-down ON/WHERE conditions can be instrumented.
+            }
+            else
+            {
+                // Construct a new predicate from the pairs that was not consumed
+                predicate = AnalyzeResult.getPredicate(tableSourcePushDown.predicatePairs);
             }
-
-            // Construct a new predicate from the pairs that was not consumed
-            predicate = AnalyzeResult.getPredicate(tableSourcePushDown.predicatePairs);
         }
 
         // If the catalog did not consume all predicates we will have the non pushable predicates
@@ -196,7 +221,12 @@ public IPhysicalPlan visit(Filter plan, Context context)
             input = filter.getInput();
         }
 
-        return wrapWithAnalyze(context, new se.kuseman.payloadbuilder.core.physicalplan.Filter(context.getNextNodeId(), input, new ExpressionPredicate(predicate)));
+        if (context.coverageMode)
+        {
+            predicate = CoverageExpressionRewriter.rewrite(context, predicate);
+        }
+
+        return wrapWithAnalyze(context, new se.kuseman.payloadbuilder.core.physicalplan.Filter(context.getNextNodeId(), input, new ExpressionPredicate(predicate)), plan.getLocation());
     }
 
     @Override
@@ -264,6 +294,11 @@ public IPhysicalPlan visit(TableScan plan, Context context)
                         .getDefaultCatalogAlias());
 
         DatasourceData data = new DatasourceData(nodeId, predicatePairs, sortItems, plan.getProjection(), plan.getOptions());
+        if (tableSourcePushDown != null
+                && tableSourcePushDown.topCount >= 0)
+        {
+            data.withTopCount(tableSourcePushDown.topCount);
+        }
 
         if (context.seekPredicate != null)
         {
@@ -305,7 +340,8 @@ public IPhysicalPlan visit(TableScan plan, Context context)
         return wrapWithAnalyze(context,
                 seekPredicate != null
                         ? new se.kuseman.payloadbuilder.core.physicalplan.IndexSeek(nodeId, plan.getSchema(), plan.getTableSource(), catalog.getName(), seekPredicate, dataSource, plan.getOptions())
-                        : new se.kuseman.payloadbuilder.core.physicalplan.TableScan(nodeId, plan.getSchema(), plan.getTableSource(), catalog.getName(), dataSource, plan.getOptions()));
+                        : new se.kuseman.payloadbuilder.core.physicalplan.TableScan(nodeId, plan.getSchema(), plan.getTableSource(), catalog.getName(), dataSource, plan.getOptions()),
+                plan.getLocation());
     }
 
     @Override
@@ -325,13 +361,14 @@ public IPhysicalPlan visit(TableFunctionScan plan, Context context)
 
         TableFunctionInfo functionInfo = pair.getValue();
         return wrapWithAnalyze(context, new se.kuseman.payloadbuilder.core.physicalplan.TableFunctionScan(context.getNextNodeId(), plan.getSchema(), plan.getTableSource(), catalogAlias,
-                catalog.getName(), functionInfo, plan.getArguments(), plan.getOptions()));
+                catalog.getName(), functionInfo, plan.getArguments(), plan.getOptions()), plan.getLocation());
     }
 
     @Override
     public IPhysicalPlan visit(ExpressionScan plan, Context context)
     {
-        return wrapWithAnalyze(context, new se.kuseman.payloadbuilder.core.physicalplan.ExpressionScan(context.getNextNodeId(), plan.getTableSource(), plan.getSchema(), plan.getExpression()));
+        return wrapWithAnalyze(context, new se.kuseman.payloadbuilder.core.physicalplan.ExpressionScan(context.getNextNodeId(), plan.getTableSource(), plan.getSchema(), plan.getExpression()),
+                plan.getLocation());
     }
 
     @Override
@@ -482,6 +519,11 @@ public IPhysicalPlan visit(Join plan, Context context)
         IPhysicalPlan inner = plan.getInner()
                 .accept(this, context);
 
+        if (context.coverageMode
+                && condition != null)
+        {
+            condition = CoverageExpressionRewriter.rewrite(context, condition);
+        }
         ExpressionPredicate predicate = plan.getCondition() != null ? new ExpressionPredicate(condition)
                 : null;
 
@@ -523,7 +565,7 @@ public IPhysicalPlan visit(Join plan, Context context)
             join = createNestedLoop(plan, context.getNextNodeId(), outer, inner, predicate, pushOuterReference);
         }
 
-        return wrapWithAnalyze(context, join);
+        return wrapWithAnalyze(context, join, plan.getLocation());
     }
 
     @Override
@@ -545,18 +587,18 @@ public IPhysicalPlan visit(ConstantScan plan, Context context)
     {
         if (ConstantScan.ONE_ROW_EMPTY_SCHEMA.equals(plan))
         {
-            return wrapWithAnalyze(context, new se.kuseman.payloadbuilder.core.physicalplan.ConstantScan(context.getNextNodeId(), TupleVector.CONSTANT));
+            return wrapWithAnalyze(context, new se.kuseman.payloadbuilder.core.physicalplan.ConstantScan(context.getNextNodeId(), TupleVector.CONSTANT), plan.getLocation());
         }
         else if (ConstantScan.ZERO_ROWS_EMPTY_SCHEMA.equals(plan))
         {
-            return wrapWithAnalyze(context, new se.kuseman.payloadbuilder.core.physicalplan.ConstantScan(context.getNextNodeId(), TupleVector.EMPTY));
+            return wrapWithAnalyze(context, new se.kuseman.payloadbuilder.core.physicalplan.ConstantScan(context.getNextNodeId(), TupleVector.EMPTY), plan.getLocation());
         }
 
         // Zero row scan with a schema
         if (plan.getRowsExpressions()
                 .isEmpty())
         {
-            return wrapWithAnalyze(context, new se.kuseman.payloadbuilder.core.physicalplan.ConstantScan(context.getNextNodeId(), TupleVector.of(plan.getSchema())));
+            return wrapWithAnalyze(context, new se.kuseman.payloadbuilder.core.physicalplan.ConstantScan(context.getNextNodeId(), TupleVector.of(plan.getSchema())), plan.getLocation());
         }
 
         // Strip all alias expression here since they are not needed anymore
@@ -575,15 +617,26 @@ else if (ConstantScan.ZERO_ROWS_EMPTY_SCHEMA.equals(plan))
                         .allMatch(IExpression::isConstant)))
         {
             TupleVector vector = se.kuseman.payloadbuilder.core.physicalplan.ConstantScan.vectorize(plan.getSchema(), rowsExpressions, context.context, false);
-            return wrapWithAnalyze(context, new se.kuseman.payloadbuilder.core.physicalplan.ConstantScan(context.getNextNodeId(), vector));
+            return wrapWithAnalyze(context, new se.kuseman.payloadbuilder.core.physicalplan.ConstantScan(context.getNextNodeId(), vector), plan.getLocation());
         }
 
-        return wrapWithAnalyze(context, new se.kuseman.payloadbuilder.core.physicalplan.ConstantScan(context.getNextNodeId(), plan.getSchema(), rowsExpressions));
+        return wrapWithAnalyze(context, new se.kuseman.payloadbuilder.core.physicalplan.ConstantScan(context.getNextNodeId(), plan.getSchema(), rowsExpressions), plan.getLocation());
     }
 
     @Override
     public IPhysicalPlan visit(Limit plan, Context context)
     {
+        // Push a constant TOP count down to a single-table datasource (no joins = safe to add SQL-level limiting)
+        if (!hasJoin(plan.getInput())
+                && plan.getLimitExpression() instanceof ILiteralIntegerExpression litInt)
+        {
+            TableSourceReference singleSource = collectSingleTableSource(plan.getInput());
+            if (singleSource != null)
+            {
+                context.tableSourcePushDown.computeIfAbsent(singleSource, k -> new StatementPlanner.TableSourcePushDown()).topCount = litInt.getValue();
+            }
+        }
+
         IPhysicalPlan input = plan.getInput()
                 .accept(this, context);
         return wrapWithAnalyze(context, new se.kuseman.payloadbuilder.core.physicalplan.Limit(context.getNextNodeId(), input, plan.getLimitExpression()));
@@ -684,14 +737,60 @@ private TableSource getTopTableSource(ILogicalPlan plan, boolean skipSubQuery)
     }
 
     static IPhysicalPlan wrapWithAnalyze(Context context, IPhysicalPlan plan)
+    {
+        return wrapWithAnalyze(context, plan, null);
+    }
+
+    static IPhysicalPlan wrapWithAnalyze(Context context, IPhysicalPlan plan, se.kuseman.payloadbuilder.core.parser.Location location)
     {
         if (context.analyze)
         {
-            return new AnalyzeInterceptor(context.getNextNodeId(), plan);
+            int nodeId = context.getNextNodeId();
+            if (location != null)
+            {
+                context.nodeLocations.put(nodeId, location);
+            }
+            return new AnalyzeInterceptor(nodeId, plan);
         }
         return plan;
     }
 
+    /** Returns true if the logical plan contains any Join node at any depth. */
+    private boolean hasJoin(ILogicalPlan plan)
+    {
+        if (plan instanceof Join)
+        {
+            return true;
+        }
+        return plan.getChildren()
+                .stream()
+                .anyMatch(this::hasJoin);
+    }
+
+    /** Returns the single TableSourceReference in the logical plan, or null if zero or more than one. */
+    private TableSourceReference collectSingleTableSource(ILogicalPlan plan)
+    {
+        Set<TableSourceReference> found = new HashSet<>();
+        collectTableSources(plan, found);
+        return found.size() == 1 ? found.iterator()
+                .next()
+                : null;
+    }
+
+    private void collectTableSources(ILogicalPlan plan, Set<TableSourceReference> result)
+    {
+        if (plan instanceof TableScan scan)
+        {
+            result.add(scan.getTableSource());
+        }
+        else if (plan instanceof TableFunctionScan scan)
+        {
+            result.add(scan.getTableSource());
+        }
+        plan.getChildren()
+                .forEach(child -> collectTableSources(child, result));
+    }
+
     /** Visitor that collects table source references */
     static class TableSourceReferenceCollector extends AExpressionVisitor<Void, Set<TableSourceReference>>
     {
diff --git a/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/planning/StatementPlanner.java b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/planning/StatementPlanner.java
index afef4216d..b28c65527 100644
--- a/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/planning/StatementPlanner.java
+++ b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/planning/StatementPlanner.java
@@ -17,6 +17,7 @@
 import se.kuseman.payloadbuilder.core.execution.QuerySession;
 import se.kuseman.payloadbuilder.core.expression.PredicateAnalyzer.AnalyzePair;
 import se.kuseman.payloadbuilder.core.logicalplan.ILogicalPlan;
+import se.kuseman.payloadbuilder.core.parser.Location;
 import se.kuseman.payloadbuilder.core.statement.QueryStatement;
 
 /** Statement planner that transforms a {@link QueryStatement} to an executable form */
@@ -41,6 +42,18 @@ static class Context
         /** Flag indicating that next plan to be generated is an analzye */
         boolean analyze;
 
+        /** Maps each AnalyzeInterceptor nodeId to the source Location of the wrapped operator. Populated when coverage mode is active. */
+        Map<Integer, Location> nodeLocations = new HashMap<>();
+
+        /** True when this plan is being compiled in query coverage mode (generates InstrumentedCaseExpression wrappers). */
+        boolean coverageMode;
+
+        /** Optional name assigned at compile time via {@link Payloadbuilder#compile(QuerySession, String, String)}. Used as the stable key in coverage reports. */
+        String queryName;
+
+        /** Counts SELECT/SELECT-INTO statements instrumented for coverage in this compile. Used to generate unique keys for multi-statement files. */
+        int statementCoverageIndex;
+
         /** Field with the last created logical plan. Used when holding schema information for temp tables etc. */
         ILogicalPlan currentLogicalPlan;
 
@@ -72,13 +85,23 @@ static class TableSourcePushDown
 
         /** Push down predicates that can be consumed by catalog */
         List<AnalyzePair> predicatePairs = emptyList();
+
+        /** TOP/LIMIT count pushed down from an enclosing Limit operator. -1 = no limit */
+        int topCount = -1;
     }
 
     /** Plans provided query. Produces a runnable query that can be cached */
     public static QueryStatement plan(QuerySession session, QueryStatement query)
+    {
+        return plan(session, query, null);
+    }
+
+    /** Plans provided query with an optional name used in coverage reports. */
+    public static QueryStatement plan(QuerySession session, QueryStatement query, String queryName)
     {
         ExecutionContext context = new ExecutionContext(session);
         Context ctx = new Context(context);
+        ctx.queryName = queryName;
 
         // Add existing session tables into context
         // This is used when working in a statefull session system like Queryeer
diff --git a/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/planning/StatementRewriter.java b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/planning/StatementRewriter.java
index d26df1289..5d29b7353 100644
--- a/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/planning/StatementRewriter.java
+++ b/payloadbuilder-core/src/main/java/se/kuseman/payloadbuilder/core/planning/StatementRewriter.java
@@ -8,6 +8,7 @@
 import static se.kuseman.payloadbuilder.core.logicalplan.optimization.LogicalPlanOptimizer.resolveExpression;
 
 import java.util.List;
+import java.util.Map;
 
 import se.kuseman.payloadbuilder.api.QualifiedName;
 import se.kuseman.payloadbuilder.api.catalog.Catalog;
@@ -26,6 +27,9 @@
 import se.kuseman.payloadbuilder.core.catalog.TableSourceReference;
 import se.kuseman.payloadbuilder.core.common.SchemaUtils;
 import se.kuseman.payloadbuilder.core.common.SortItem;
+import se.kuseman.payloadbuilder.core.execution.PlanOperatorInfo;
+import se.kuseman.payloadbuilder.core.execution.PlanRuleRegistry;
+import se.kuseman.payloadbuilder.core.execution.QueryCoverageRegistry;
 import se.kuseman.payloadbuilder.core.execution.QuerySession;
 import se.kuseman.payloadbuilder.core.expression.LiteralIntegerExpression;
 import se.kuseman.payloadbuilder.core.expression.LiteralStringExpression;
@@ -36,8 +40,11 @@
 import se.kuseman.payloadbuilder.core.logicalplan.Sort;
 import se.kuseman.payloadbuilder.core.logicalplan.TableScan;
 import se.kuseman.payloadbuilder.core.logicalplan.optimization.LogicalPlanOptimizer;
+import se.kuseman.payloadbuilder.core.parser.Location;
 import se.kuseman.payloadbuilder.core.parser.ParseException;
+import se.kuseman.payloadbuilder.core.physicalplan.AnalyzeInterceptor;
 import se.kuseman.payloadbuilder.core.physicalplan.AssignmentPlan;
+import se.kuseman.payloadbuilder.core.physicalplan.CoveragePlan;
 import se.kuseman.payloadbuilder.core.physicalplan.DescribePlan;
 import se.kuseman.payloadbuilder.core.physicalplan.IPhysicalPlan;
 import se.kuseman.payloadbuilder.core.physicalplan.InsertInto;
@@ -205,6 +212,30 @@ public Statement visit(StatementList statement, Context context)
     @Override
     public Statement visit(LogicalSelectStatement statement, Context context)
     {
+        final boolean coverageEnabled = QueryCoverageRegistry.isEnabled();
+        final boolean rulesActive = PlanRuleRegistry.isActive();
+        if ((coverageEnabled
+                || rulesActive)
+                && !context.analyze)
+        {
+            context.analyze = true;
+            context.coverageMode = coverageEnabled;
+            final PhysicalStatement physicalStatement = createPhysicalPlan(statement, context);
+            context.analyze = false;
+            context.coverageMode = false;
+            if (rulesActive)
+            {
+                checkPlanRules(physicalStatement.getPlan(), context.nodeLocations, coverageQueryKey(context));
+            }
+            if (coverageEnabled)
+            {
+                String key = coverageQueryKey(context);
+                context.statementCoverageIndex++;
+                return new PhysicalStatement(new CoveragePlan(context.getNextNodeId(), physicalStatement.getPlan(), Map.copyOf(context.nodeLocations), key));
+            }
+            context.statementCoverageIndex++;
+            return physicalStatement;
+        }
         return createPhysicalPlan(statement, context);
     }
 
@@ -229,6 +260,17 @@ public Statement visit(DropTableStatement statement, Context context)
 
     private Statement createInsertStatement(LogicalSelectIntoStatement statement, Context context, List<String> insertColumns)
     {
+        final boolean coverageActive = QueryCoverageRegistry.isEnabled()
+                && !context.analyze;
+        final boolean rulesActiveForInsert = PlanRuleRegistry.isActive()
+                && !context.analyze;
+        if (coverageActive
+                || rulesActiveForInsert)
+        {
+            context.analyze = true;
+            context.coverageMode = coverageActive;
+        }
+
         PhysicalStatement input = createPhysicalPlan(statement.getInput(), context);
 
         List<Option> options = statement.getOptions()
@@ -264,7 +306,72 @@ private Statement createInsertStatement(LogicalSelectIntoStatement statement, Co
                 : catalog.getInsertIntoSink(context.getSession(), catalogAlias, statement.getTable(), new InsertIntoData(nodeId, schema, options, insertColumns));
         //@formatter:on
 
-        return new PhysicalStatement(QueryPlanner.wrapWithAnalyze(context, new InsertInto(nodeId, input.getPlan(), insertColumns, sink)));
+        IPhysicalPlan insertPlan = QueryPlanner.wrapWithAnalyze(context, new InsertInto(nodeId, input.getPlan(), insertColumns, sink), statement.getLocation());
+
+        if (coverageActive
+                || rulesActiveForInsert)
+        {
+            context.analyze = false;
+            context.coverageMode = false;
+            if (rulesActiveForInsert)
+            {
+                checkPlanRules(insertPlan, context.nodeLocations, coverageQueryKey(context));
+            }
+            if (coverageActive)
+            {
+                String key = coverageQueryKey(context);
+                context.statementCoverageIndex++;
+                return new PhysicalStatement(new CoveragePlan(context.getNextNodeId(), insertPlan, Map.copyOf(context.nodeLocations), key));
+            }
+            context.statementCoverageIndex++;
+        }
+
+        return new PhysicalStatement(insertPlan);
+    }
+
+    /**
+     * Walks the physical plan tree and invokes all registered {@link se.kuseman.payloadbuilder.core.execution.PlanRuleRegistry} rules. Uses the same traversal as
+     * {@link se.kuseman.payloadbuilder.core.physicalplan.CoveragePlan}: {@link se.kuseman.payloadbuilder.core.physicalplan.AnalyzeInterceptor} nodes expose the operator name and location;
+     * non-interceptor nodes are transparent pass-throughs. The parent chain on each {@link se.kuseman.payloadbuilder.core.execution.PlanOperatorInfo} is built incrementally so rules can inspect
+     * ancestor operators via {@link se.kuseman.payloadbuilder.core.execution.PlanOperatorInfo#hasAncestor} and {@link se.kuseman.payloadbuilder.core.execution.PlanOperatorInfo#firstAncestor}.
+     */
+    private static void checkPlanRules(IPhysicalPlan plan, Map<Integer, Location> nodeLocations, String queryName)
+    {
+        checkPlanRules(plan, nodeLocations, queryName, null);
+    }
+
+    private static void checkPlanRules(IPhysicalPlan plan, Map<Integer, Location> nodeLocations, String queryName, PlanOperatorInfo parent)
+    {
+        if (plan instanceof AnalyzeInterceptor ai)
+        {
+            int aiNodeId = ai.getActualNodeId();
+            Location loc = nodeLocations.getOrDefault(aiNodeId, Location.EMPTY);
+            int line = loc.line() > 0 ? loc.line()
+                    : 0;
+            PlanOperatorInfo info = new PlanOperatorInfo(ai.getInput(), line, queryName, parent);
+            PlanRuleRegistry.check(info);
+            // info becomes the parent for this operator's children
+            checkPlanRules(ai.getInput(), nodeLocations, queryName, info);
+        }
+        else
+        {
+            // Non-interceptor nodes are transparent — pass the same parent through
+            for (IPhysicalPlan child : plan.getChildren())
+            {
+                checkPlanRules(child, nodeLocations, queryName, parent);
+            }
+        }
+    }
+
+    /** Returns the coverage query key for the current statement, appending {@code #N} for the second and subsequent statements in the same compile. */
+    private static String coverageQueryKey(Context context)
+    {
+        if (context.queryName == null)
+        {
+            return null;
+        }
+        return context.statementCoverageIndex == 0 ? context.queryName
+                : context.queryName + "#" + context.statementCoverageIndex;
     }
 
     private PhysicalStatement createPhysicalPlan(LogicalSelectStatement statement, Context context)
diff --git a/payloadbuilder-core/src/test/java/se/kuseman/payloadbuilder/core/physicalplan/CoveragePlanTest.java b/payloadbuilder-core/src/test/java/se/kuseman/payloadbuilder/core/physicalplan/CoveragePlanTest.java
new file mode 100644
index 000000000..b35d934f5
--- /dev/null
+++ b/payloadbuilder-core/src/test/java/se/kuseman/payloadbuilder/core/physicalplan/CoveragePlanTest.java
@@ -0,0 +1,278 @@
+package se.kuseman.payloadbuilder.core.physicalplan;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.util.ArrayList;
+import java.util.List;
+
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+import se.kuseman.payloadbuilder.api.catalog.Schema;
+import se.kuseman.payloadbuilder.api.execution.TupleVector;
+import se.kuseman.payloadbuilder.core.Payloadbuilder;
+import se.kuseman.payloadbuilder.core.RawQueryResult;
+import se.kuseman.payloadbuilder.core.catalog.CatalogRegistry;
+import se.kuseman.payloadbuilder.core.execution.QueryCoverageData;
+import se.kuseman.payloadbuilder.core.execution.QueryCoverageRegistry;
+import se.kuseman.payloadbuilder.core.execution.QuerySession;
+import se.kuseman.payloadbuilder.core.execution.vector.BufferAllocator;
+import se.kuseman.payloadbuilder.core.execution.vector.VectorFactory;
+
+/** Tests for {@link CoveragePlan}. */
+public class CoveragePlanTest
+{
+    private QuerySession session;
+    private final List<QueryCoverageData> coverageResults = new ArrayList<>();
+    private final QueryCoverageRegistry.CoverageListener listener = coverageResults::add;
+
+    @BeforeEach
+    void setUp()
+    {
+        session = new QuerySession(new CatalogRegistry());
+        session.setVectorFactory(new VectorFactory(new BufferAllocator()));
+        QueryCoverageRegistry.register(listener);
+    }
+
+    @AfterEach
+    void tearDown()
+    {
+        QueryCoverageRegistry.deregister(listener);
+        coverageResults.clear();
+    }
+
+    @Test
+    public void testCoveragePlanAddsColumn()
+    {
+        List<TupleVector> vectors = executeRaw("select 1 + 1 as result");
+        assertFalse(vectors.isEmpty());
+
+        TupleVector tv = vectors.get(0);
+        Schema schema = tv.getSchema();
+        int schemaSize = schema.getSize();
+
+        assertTrue(schemaSize >= 2, "Expected at least 2 columns (result + __coverage__)");
+        assertEquals(CoverageTupleVector.COVERAGE_COLUMN, schema.getColumns()
+                .get(schemaSize - 1)
+                .getName());
+
+        String coverageJson = tv.getColumn(schemaSize - 1)
+                .getString(0)
+                .toString();
+        assertNotNull(coverageJson);
+        assertTrue(coverageJson.startsWith("{"), "Coverage JSON should be a JSON object");
+        assertTrue(coverageJson.contains("\"operators\""), "Coverage JSON should contain operators");
+    }
+
+    @Test
+    public void testCoverageListenerNotified()
+    {
+        assertTrue(coverageResults.isEmpty());
+        executeRaw("select 1");
+        assertEquals(1, coverageResults.size());
+    }
+
+    @Test
+    public void testNoCoverageWithoutRegistry()
+    {
+        QueryCoverageRegistry.deregister(listener);
+
+        List<TupleVector> vectors = executeRaw("select 1 + 1 as result");
+        assertFalse(vectors.isEmpty());
+
+        TupleVector tv = vectors.get(0);
+        int schemaSize = tv.getSchema()
+                .getSize();
+
+        assertEquals(1, schemaSize, "Without coverage mode, should have exactly 1 column");
+        assertFalse(CoverageTupleVector.COVERAGE_COLUMN.equals(tv.getSchema()
+                .getColumns()
+                .get(0)
+                .getName()));
+
+        QueryCoverageRegistry.register(listener);
+    }
+
+    @Test
+    public void testCaseExpressionBranchTracking()
+    {
+        // Use a data-dependent CASE so it cannot be constant-folded at compile time
+        executeRaw("select case when x > 0 then 'positive' else 'negative' end as sign from (values (1), (-1)) t(x)");
+
+        assertFalse(coverageResults.isEmpty());
+        String json = coverageResults.get(0)
+                .toJson();
+
+        assertTrue(json.contains("\"branches\""), "Coverage JSON should contain branch data for CASE expressions");
+        assertTrue(json.contains("\"when_hits\""), "Coverage JSON should track WHEN clause hits");
+    }
+
+    @Test
+    public void testFilterOperatorCovered()
+    {
+        executeRaw("select * from (values (1), (2), (3)) t(x) where x > 1");
+
+        assertFalse(coverageResults.isEmpty());
+        String json = coverageResults.get(0)
+                .toJson();
+        assertTrue(json.contains("\"Filter\""), "Coverage JSON should show Filter operator");
+        assertTrue(json.contains("\"covered\":true"), "Filter operator should be covered");
+    }
+
+    @Test
+    public void testAndConditionTracking()
+    {
+        // x=1: false AND short-circuits → false (1 row)
+        // x=2: true AND true → true (1 row)
+        // x=3: true AND false → false (1 row)
+        executeRaw("select * from (values (1), (2), (3)) t(x) where x > 1 AND x < 3");
+
+        assertFalse(coverageResults.isEmpty());
+        QueryCoverageData data = coverageResults.get(0);
+
+        assertFalse(data.getConditions()
+                .isEmpty(), "Coverage should include AND/OR condition entries");
+
+        String json = data.toJson();
+        assertTrue(json.contains("\"conditions\""), "Coverage JSON should contain condition data for AND/OR");
+        assertTrue(json.contains("\"true_hits\""), "Coverage JSON should track true hits");
+        assertTrue(json.contains("\"false_hits\""), "Coverage JSON should track false hits");
+
+        // Exactly one row matched (x=2), two rows did not
+        QueryCoverageData.ConditionCoverage cond = data.getConditions()
+                .get(0);
+        assertEquals(1, cond.trueHits, "One row should satisfy the AND condition");
+        assertEquals(2, cond.falseHits, "Two rows should fail the AND condition");
+    }
+
+    @Test
+    public void testOrConditionTracking()
+    {
+        // x=1: true OR (short-circuits) → true (1 row)
+        // x=2: false OR false → false (1 row)
+        // x=3: false OR true → true (1 row)
+        executeRaw("select * from (values (1), (2), (3)) t(x) where x = 1 OR x = 3");
+
+        assertFalse(coverageResults.isEmpty());
+        QueryCoverageData.ConditionCoverage cond = coverageResults.get(0)
+                .getConditions()
+                .get(0);
+        assertEquals(2, cond.trueHits);
+        assertEquals(1, cond.falseHits);
+    }
+
+    /**
+     * Mirrors a controller that calls hasMoreResults() once and processes only the first writable result set. INSERT INTO statements must be auto-executed so their coverage fires even though the
+     * controller never calls consumeResult() for them.
+     */
+    @Test
+    public void testInsertIntoAutoExecutedAndCovered()
+    {
+        // Two-statement query: INSERT INTO #temp, then SELECT from it
+        // Controller pattern: only processes the first writable (SELECT) result
+        String sql = "select * into #temp from (values (1), (2), (3)) t(x);\n" + "select * from #temp where x > 1;";
+
+        List<TupleVector> result = new ArrayList<>();
+        RawQueryResult raw = Payloadbuilder.compile(session, sql, "svc-query")
+                .executeRaw(session);
+
+        // Simulates: if (!rs.hasMoreResults()) return; — only one call, no loop
+        if (raw.hasMoreResults())
+        {
+            raw.consumeResult(new RawQueryResult.ResultConsumer()
+            {
+                @Override
+                public void schema(Schema schema)
+                {
+                }
+
+                @Override
+                public boolean consume(TupleVector vector)
+                {
+                    result.add(vector);
+                    return true;
+                }
+            });
+        }
+
+        // INSERT INTO auto-executed during hasMoreResults() → coverage fires for both statements
+        assertEquals(2, coverageResults.size(), "INSERT INTO must fire coverage even though caller only processes one result set");
+        assertEquals("svc-query", coverageResults.get(0)
+                .getQueryKey(), "INSERT INTO statement should be keyed as the base name");
+        assertEquals("svc-query#1", coverageResults.get(1)
+                .getQueryKey(), "SELECT statement should be keyed with #1 suffix");
+
+        // The caller saw exactly one result set (the SELECT)
+        assertEquals(1, result.size(), "Caller should receive exactly one result set (the SELECT)");
+
+        // INSERT INTO coverage should have operators
+        assertFalse(coverageResults.get(0)
+                .getOperators()
+                .isEmpty(), "INSERT INTO coverage entry must contain operators");
+        // SELECT coverage should have operators
+        assertFalse(coverageResults.get(1)
+                .getOperators()
+                .isEmpty(), "SELECT coverage entry must contain operators");
+    }
+
+    @Test
+    public void testMultiStatementEachStatementGetsSeparateCoverageEntry()
+    {
+        // Three-statement named query — each should produce its own accumulator entry
+        List<TupleVector> vectors = executeRaw("select * from (values (1), (2)) t(x);\n" + "select * from (values (3)) t(y) where y > 0;\n" + "select * from (values (10), (20), (30)) t(z);",
+                "multi-stmt");
+
+        // Three result-sets returned
+        assertEquals(3, vectors.size(), "Expected 3 result sets from 3 statements");
+
+        // Three separate coverage entries — one per statement key
+        assertEquals(3, coverageResults.size(), "Expected one coverage entry per statement");
+        assertEquals("multi-stmt", coverageResults.get(0)
+                .getQueryKey());
+        assertEquals("multi-stmt#1", coverageResults.get(1)
+                .getQueryKey());
+        assertEquals("multi-stmt#2", coverageResults.get(2)
+                .getQueryKey());
+
+        // Each entry must have at least one operator
+        for (QueryCoverageData data : coverageResults)
+        {
+            assertFalse(data.getOperators()
+                    .isEmpty(), "Expected operators in coverage entry for " + data.getQueryKey());
+        }
+    }
+
+    private List<TupleVector> executeRaw(String query)
+    {
+        return executeRaw(query, null);
+    }
+
+    private List<TupleVector> executeRaw(String query, String queryName)
+    {
+        List<TupleVector> result = new ArrayList<>();
+        RawQueryResult raw = Payloadbuilder.compile(session, query, queryName)
+                .executeRaw(session);
+        while (raw.hasMoreResults())
+        {
+            raw.consumeResult(new RawQueryResult.ResultConsumer()
+            {
+                @Override
+                public void schema(Schema schema)
+                {
+                }
+
+                @Override
+                public boolean consume(TupleVector vector)
+                {
+                    result.add(vector);
+                    return true;
+                }
+            });
+        }
+        return result;
+    }
+}
diff --git a/payloadbuilder-core/src/test/java/se/kuseman/payloadbuilder/core/planning/QueryPlannerTest.java b/payloadbuilder-core/src/test/java/se/kuseman/payloadbuilder/core/planning/QueryPlannerTest.java
index 0b3608162..de76ff6a7 100644
--- a/payloadbuilder-core/src/test/java/se/kuseman/payloadbuilder/core/planning/QueryPlannerTest.java
+++ b/payloadbuilder-core/src/test/java/se/kuseman/payloadbuilder/core/planning/QueryPlannerTest.java
@@ -194,6 +194,7 @@ void test_cache_inner_plan_regression()
 
         Assertions.assertThat(actual)
                 .usingRecursiveComparison()
+                .ignoringFieldsOfTypes(Location.class)
                 .isEqualTo(expected);
 
         assertEquals(expected, actual);
@@ -283,6 +284,7 @@ void test_cache_inner_plan_with_nested_complex_structure()
 
         Assertions.assertThat(actual)
                 .usingRecursiveComparison()
+                .ignoringFieldsOfTypes(Location.class)
                 .isEqualTo(expected);
 
         assertEquals(expected, actual);
@@ -331,6 +333,7 @@ void test_sub_query_filter_elimination()
 
         Assertions.assertThat(actual)
                 .usingRecursiveComparison()
+                .ignoringFieldsOfTypes(Location.class)
                 .isEqualTo(expected);
 
         assertEquals(expected, actual);
@@ -388,6 +391,7 @@ void test_sub_query_filter_elimination_analyze()
 
         Assertions.assertThat(actual)
                 .usingRecursiveComparison()
+                .ignoringFieldsOfTypes(Location.class)
                 .isEqualTo(expected);
 
         assertEquals(expected, actual);
@@ -447,6 +451,7 @@ void test_nested_sub_query_projection_elimination()
 
         Assertions.assertThat(actual)
                 .usingRecursiveComparison()
+                .ignoringFieldsOfTypes(Location.class)
                 .isEqualTo(expected);
 
         assertEquals(expected, actual);
@@ -501,6 +506,7 @@ void test_sub_query_projection_elimination()
 
         Assertions.assertThat(actual)
                 .usingRecursiveComparison()
+                .ignoringFieldsOfTypes(Location.class)
                 .isEqualTo(expected);
 
         assertEquals(expected, actual);
@@ -565,6 +571,7 @@ void test_sub_query_projection_elimination_analyze()
 
         Assertions.assertThat(actual)
                 .usingRecursiveComparison()
+                .ignoringFieldsOfTypes(Location.class)
                 .isEqualTo(expected);
 
         assertEquals(expected, actual);
@@ -617,6 +624,7 @@ void test_sub_query_projection_elimination_2()
 
         Assertions.assertThat(actual)
                 .usingRecursiveComparison()
+                .ignoringFieldsOfTypes(Location.class)
                 .isEqualTo(expected);
 
         assertEquals(expected, actual);
@@ -677,6 +685,7 @@ void test_using_same_table_ref_different_places()
 
         Assertions.assertThat(actual)
                 .usingRecursiveComparison()
+                .ignoringFieldsOfTypes(Location.class)
                 .isEqualTo(expected);
 
         assertEquals(expected, actual);
@@ -744,6 +753,7 @@ void test_using_same_table_ref_different_places_2()
 
         Assertions.assertThat(actual)
                 .usingRecursiveComparison()
+                .ignoringFieldsOfTypes(Location.class)
                 .isEqualTo(expected);
 
         assertEquals(expected, actual);
@@ -819,6 +829,7 @@ void test_using_same_table_ref_different_places_3()
 
         Assertions.assertThat(actual)
                 .usingRecursiveComparison()
+                .ignoringFieldsOfTypes(Location.class)
                 .isEqualTo(expected);
 
         assertEquals(expected, actual);
@@ -874,6 +885,7 @@ void test_using_same_table_ref_different_places_non_equi()
 
         Assertions.assertThat(actual)
                 .usingRecursiveComparison()
+                .ignoringFieldsOfTypes(Location.class)
                 .isEqualTo(expected);
 
         assertEquals(expected, actual);
@@ -920,6 +932,7 @@ void test_outer_apply_non_correlated()
 
         Assertions.assertThat(actual)
                 .usingRecursiveComparison()
+                .ignoringFieldsOfTypes(Location.class)
                 .isEqualTo(expected);
 
         assertEquals(expected, actual);
@@ -971,6 +984,7 @@ void test_outer_apply_correlated()
 
         Assertions.assertThat(actual)
                 .usingRecursiveComparison()
+                .ignoringFieldsOfTypes(Location.class)
                 .isEqualTo(expected);
 
         assertEquals(expected, actual);
@@ -1022,6 +1036,7 @@ void test_cross_apply_correlated()
 
         Assertions.assertThat(actual)
                 .usingRecursiveComparison()
+                .ignoringFieldsOfTypes(Location.class)
                 .isEqualTo(expected);
 
         assertEquals(expected, actual);
@@ -1082,6 +1097,7 @@ public TableSchema getTableSchema(IExecutionContext context, String catalogAlias
 
         Assertions.assertThat(actual)
                 .usingRecursiveComparison()
+                .ignoringFieldsOfTypes(Location.class)
                 .isEqualTo(expected);
 
         assertEquals(expected, actual);
@@ -1144,6 +1160,7 @@ public TableSchema getTableSchema(IExecutionContext context, String catalogAlias
 
         Assertions.assertThat(actual)
                 .usingRecursiveComparison()
+                .ignoringFieldsOfTypes(Location.class)
                 .isEqualTo(expected);
 
         assertEquals(expected, actual);
@@ -1182,6 +1199,7 @@ void test_top()
 
         Assertions.assertThat(actual)
                 .usingRecursiveComparison()
+                .ignoringFieldsOfTypes(Location.class)
                 .isEqualTo(expected);
 
         assertEquals(expected, actual);
@@ -1278,7 +1296,7 @@ void test_table_function()
 
         Assertions.assertThat(actual)
                 .usingRecursiveComparison()
-                .ignoringFieldsOfTypes(Random.class)
+                .ignoringFieldsOfTypes(Random.class, Location.class)
                 .isEqualTo(expected);
 
         assertEquals(expected, actual);
@@ -1771,6 +1789,7 @@ public TableSchema getTableSchema(IExecutionContext context, String catalogAlias
 
         Assertions.assertThat(actual)
                 .usingRecursiveComparison()
+                .ignoringFieldsOfTypes(Location.class)
                 .isEqualTo(expected);
 
         assertEquals(expected, actual);
@@ -1841,6 +1860,7 @@ public TableSchema getTableSchema(IExecutionContext context, String catalogAlias
 
         Assertions.assertThat(actual)
                 .usingRecursiveComparison()
+                .ignoringFieldsOfTypes(Location.class)
                 .isEqualTo(expected);
 
         assertEquals(expected, actual);
@@ -1894,6 +1914,7 @@ public TableSchema getTableSchema(IExecutionContext context, String catalogAlias
 
         Assertions.assertThat(actual)
                 .usingRecursiveComparison()
+                .ignoringFieldsOfTypes(Location.class)
                 .isEqualTo(expected);
 
         assertEquals(expected, actual);
@@ -1947,6 +1968,7 @@ public TableSchema getTableSchema(IExecutionContext context, String catalogAlias
 
         Assertions.assertThat(actual)
                 .usingRecursiveComparison()
+                .ignoringFieldsOfTypes(Location.class)
                 .isEqualTo(expected);
 
         assertEquals(expected, actual);
@@ -2004,6 +2026,7 @@ public TableSchema getTableSchema(IExecutionContext context, String catalogAlias
 
         Assertions.assertThat(actual)
                 .usingRecursiveComparison()
+                .ignoringFieldsOfTypes(Location.class)
                 .isEqualTo(expected);
 
         assertEquals(expected, actual);
@@ -2061,6 +2084,7 @@ public TableSchema getTableSchema(IExecutionContext context, String catalogAlias
 
         Assertions.assertThat(actual)
                 .usingRecursiveComparison()
+                .ignoringFieldsOfTypes(Location.class)
                 .isEqualTo(expected);
 
         assertEquals(expected, actual);
@@ -2118,6 +2142,7 @@ public TableSchema getTableSchema(IExecutionContext context, String catalogAlias
 
         Assertions.assertThat(actual)
                 .usingRecursiveComparison()
+                .ignoringFieldsOfTypes(Location.class)
                 .isEqualTo(expected);
 
         assertEquals(expected, actual);
@@ -2181,6 +2206,7 @@ public TableSchema getTableSchema(IExecutionContext context, String catalogAlias
 
         Assertions.assertThat(actual)
                 .usingRecursiveComparison()
+                .ignoringFieldsOfTypes(Location.class)
                 .isEqualTo(expected);
 
         assertEquals(expected, actual);
@@ -2243,6 +2269,7 @@ public TableSchema getTableSchema(IExecutionContext context, String catalogAlias
 
         Assertions.assertThat(actual)
                 .usingRecursiveComparison()
+                .ignoringFieldsOfTypes(Location.class)
                 .isEqualTo(expected);
 
         assertEquals(expected, actual);
@@ -2315,6 +2342,7 @@ public TableSchema getTableSchema(IExecutionContext context, String catalogAlias
 
         Assertions.assertThat(actual)
                 .usingRecursiveComparison()
+                .ignoringFieldsOfTypes(Location.class)
                 .isEqualTo(expected);
 
         assertEquals(expected, actual);
@@ -2391,6 +2419,7 @@ public TableSchema getTableSchema(IExecutionContext context, String catalogAlias
 
         Assertions.assertThat(actual)
                 .usingRecursiveComparison()
+                .ignoringFieldsOfTypes(Location.class)
                 .isEqualTo(expected);
 
         assertEquals(expected, actual);
@@ -2469,6 +2498,7 @@ public TableSchema getTableSchema(IExecutionContext context, String catalogAlias
 
         Assertions.assertThat(actual)
                 .usingRecursiveComparison()
+                .ignoringFieldsOfTypes(Location.class)
                 .isEqualTo(expected);
 
         assertEquals(expected, actual);
@@ -2538,6 +2568,7 @@ public TableSchema getTableSchema(IExecutionContext context, String catalogAlias
 
         Assertions.assertThat(actual)
                 .usingRecursiveComparison()
+                .ignoringFieldsOfTypes(Location.class)
                 .isEqualTo(expected);
 
         assertEquals(expected, actual);
@@ -2669,7 +2700,7 @@ else if (tbl.equalsIgnoreCase("tableC"))
 
         Assertions.assertThat(actual)
                 .usingRecursiveComparison()
-                .ignoringFieldsOfTypes(Random.class)
+                .ignoringFieldsOfTypes(Random.class, Location.class)
                 .isEqualTo(expected);
 
         assertEquals(expected, actual);
@@ -2745,6 +2776,7 @@ public TableSchema getTableSchema(IExecutionContext context, String catalogAlias
 
         Assertions.assertThat(actual)
                 .usingRecursiveComparison()
+                .ignoringFieldsOfTypes(Location.class)
                 .isEqualTo(expected);
 
         assertEquals(expected, actual);
@@ -2854,6 +2886,7 @@ void test_predicate_pushdown_inverted_in_expression()
 
         Assertions.assertThat(actual)
                 .usingRecursiveComparison()
+                .ignoringFieldsOfTypes(Location.class)
                 .isEqualTo(expected);
 
         assertEquals(expected, actual);
@@ -2895,6 +2928,7 @@ void test_predicate_pushdown_inverted_in_expression_multiple_args()
 
         Assertions.assertThat(actual)
                 .usingRecursiveComparison()
+                .ignoringFieldsOfTypes(Location.class)
                 .isEqualTo(expected);
 
         assertEquals(expected, actual);
@@ -2936,6 +2970,7 @@ void test_predicate_pushdown_inverted_in_expression_with_not()
 
         Assertions.assertThat(actual)
                 .usingRecursiveComparison()
+                .ignoringFieldsOfTypes(Location.class)
                 .isEqualTo(expected);
 
         assertEquals(expected, actual);
@@ -3003,6 +3038,7 @@ void test_predicate_pushdown_2()
 
         Assertions.assertThat(actual)
                 .usingRecursiveComparison()
+                .ignoringFieldsOfTypes(Location.class)
                 .isEqualTo(expected);
 
         assertEquals(expected, actual);
@@ -3081,6 +3117,7 @@ void test_predicate_pushdown_with_analyze()
 
         Assertions.assertThat(actual)
                 .usingRecursiveComparison()
+                .ignoringFieldsOfTypes(Location.class)
                 .isEqualTo(expected);
 
         assertEquals(expected, actual);
diff --git a/payloadbuilder-test/.gitignore b/payloadbuilder-test/.gitignore
new file mode 100644
index 000000000..b83d22266
--- /dev/null
+++ b/payloadbuilder-test/.gitignore
@@ -0,0 +1 @@
+/target/
diff --git a/payloadbuilder-test/README.md b/payloadbuilder-test/README.md
new file mode 100644
index 000000000..9f54604db
--- /dev/null
+++ b/payloadbuilder-test/README.md
@@ -0,0 +1,263 @@
+# payloadbuilder-test
+
+JUnit 5 utilities for testing PayloadBuilder SQL queries, including a **query coverage extension** that shows which operators, filters, joins and CASE/IF branches were exercised by your tests.
+
+---
+
+## Dependency
+
+```xml
+<dependency>
+    <groupId>se.kuseman.payloadbuilder</groupId>
+    <artifactId>payloadbuilder-test</artifactId>
+    <version>${payloadbuilder.version}</version>
+    <scope>test</scope>
+</dependency>
+```
+
+---
+
+## Query Coverage
+
+### What it tracks
+
+| Item | What "covered" means |
+|------|----------------------|
+| **Filter** (WHERE / HAVING) | Executed at least once with at least one matching row |
+| **Join** (INNER / LEFT / CROSS APPLY etc.) | Executed at least once |
+| **Projection** | Executed at least once |
+| **TableScan / TableFunctionScan** | Executed at least once |
+| **CASE WHEN branch** | That specific WHEN clause matched at least one row |
+| **ELSE branch** | At least one row fell through to ELSE |
+| **AND / OR condition** | Both the `true` and `false` outcomes were observed at least once |
+
+Source locations (line numbers) are attached to operators and expressions when available, so you can pinpoint exactly which WHERE clause, JOIN, or AND branch was missed.
+
+### The `__coverage__` column
+
+Every result set produced while coverage is active gets an extra `__coverage__` column appended as the last column. The value is identical on every row — it is a JSON snapshot of the plan coverage for that query:
+
+```json
+{
+  "operators": {
+    "3": { "name": "Filter", "execution_count": 1, "rows_out": 3, "covered": true,  "location": { "line": 2, "start": 42, "end": 57 } },
+    "5": { "name": "HashMatch", "execution_count": 0, "rows_out": 0, "covered": false }
+  },
+  "branches": {
+    "7": { "expression": "CASE WHEN x > 0 ...", "when_hits": [4, 0], "else_hits": 2, "location": { "line": 3, "start": 10, "end": 60 } }
+  },
+  "conditions": {
+    "9": { "expression": "x > 1 AND x < 10", "true_hits": 3, "false_hits": 1, "location": { "line": 2, "start": 62, "end": 78 } }
+  }
+}
+```
+
+> **Note** — if your existing tests assert on exact column count or schema, they will need updating to account for the extra column.
+
+---
+
+## Usage
+
+### Option A — `@ExtendWith` (console summary only)
+
+Simplest form. Gives a summary in the JUnit console output and writes a JSON report to `target/coverage/`.
+
+```java
+@ExtendWith(QueryCoverageExtension.class)
+class MyQueryTest {
+
+    @Test
+    void myTest() {
+        // run queries, make normal assertions
+    }
+}
+```
+
+Console output after all tests:
+
+```
+TestIdentifier [MyQueryTest]
+ReportEntry [query-coverage = 'operators: 18/24 covered, branches: 3/4 covered']
+```
+
+---
+
+### Option B — `@RegisterExtension` + `@TestFactory` (per-operator JUnit entries)
+
+Gives individual pass/fail entries in the JUnit view — one per operator and one per CASE/IF branch. Uncovered items show as red failures, covered items as green passes.
+
+`QueryCoverageExtension` has no JUnit `DynamicTest` dependency itself — the dynamic test generation lives in `CoverageTestFactory` so the extension loads cleanly as a `@RegisterExtension` field.
+
+```java
+@TestMethodOrder(MethodOrderer.OrderAnnotation.class)  // required — factory must run last
+class MyQueryTest {
+
+    @RegisterExtension
+    static final QueryCoverageExtension coverage = new QueryCoverageExtension();
+
+    @Test
+    @Order(1)
+    void someQuery() {
+        // ...
+    }
+
+    @ParameterizedTest
+    @Order(2)
+    @CsvSource({ "..." })
+    void parameterisedQuery(String arg) {
+        // ...
+    }
+
+    // Must be last so the accumulator is fully populated
+    @TestFactory
+    @Order(Integer.MAX_VALUE)
+    Stream<DynamicNode> queryCoverageResults() {
+        return CoverageTestFactory.from(coverage.getAccumulator());
+    }
+}
+```
+
+JUnit view result:
+
+```
+▼ queryCoverageResults()
+  ▼ query #1
+    ✓ Projection [id:0]
+    ✗ Filter [line 5]          ← red: "not covered — 0 executions"
+    ✓ HashMatch [line 3]
+  ▼ query #2
+    ✓ CASE [line 8] → WHEN 0 (4 hits)
+    ✗ CASE [line 8] → WHEN 1 (0 hits)   ← red: "WHEN 1 never matched — 0 hits"
+    ✓ CASE [line 8] → ELSE (2 hits)
+```
+
+---
+
+## Sharing test cases with a Spring Boot integration test
+
+If you already have a `@SpringBootTest` class testing the same queries via HTTP, extract the shared test cases into an abstract base class and have both test classes extend it:
+
+```java
+// Base — no framework annotations, just the test data
+abstract class AbstractProductQueryTest {
+
+    @ParameterizedTest
+    @CsvSource(textBlock = """
+        /v1/products/123; 200; /expected/product_123.json
+        /v1/products/999; 404; <null>
+    """, nullValues = "<null>", delimiter = ';')
+    void testProductEndpoint(String path, int expectedStatus, String expectedJson) throws IOException {
+        assertResponse(path, expectedStatus, expectedJson);
+    }
+
+    protected abstract void assertResponse(String path, int expectedStatus, String expectedJson) throws IOException;
+}
+```
+
+```java
+// Spring Boot integration test (HTTP)
+@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)
+class ProductControllerIT extends AbstractProductQueryTest {
+
+    @Autowired TestRestTemplate restTemplate;
+
+    @Override
+    protected void assertResponse(String path, int expectedStatus, String expectedJson) {
+        // assert via HTTP
+    }
+}
+```
+
+```java
+// Coverage test (direct service call, no Spring context)
+@TestMethodOrder(MethodOrderer.OrderAnnotation.class)
+class ProductQueryCoverageTest extends AbstractProductQueryTest {
+
+    @RegisterExtension
+    static QueryCoverageExtension coverage = new QueryCoverageExtension();
+
+    @Override
+    protected void assertResponse(String path, int expectedStatus, String expectedJson) {
+        // call service directly — same assertions, but queries run on the test thread
+        // so the thread-local coverage registry picks them up
+    }
+
+    @TestFactory
+    @Order(Integer.MAX_VALUE)
+    Stream<DynamicNode> queryCoverageResults() {
+        return coverage.buildCoverageTests();
+    }
+}
+```
+
+> **Why not use `@SpringBootTest` for coverage?**
+> `@SpringBootTest` with `WebEnvironment.RANDOM_PORT` handles requests on Tomcat threads, not the test thread.
+> `QueryCoverageExtension` uses a `ThreadLocal`, so it only sees queries executed on the thread that registered the listener.
+> Direct service calls stay on the test thread and work correctly.
+
+---
+
+## JSON report
+
+After each test class run a file is written to:
+
+```
+target/coverage/<TestClassName>-coverage.json
+```
+
+Format:
+
+```json
+{
+  "test_class": "ProductQueryCoverageTest",
+  "queries": [
+    {
+      "operators": { ... },
+      "branches":  { ... }
+    }
+  ]
+}
+```
+
+---
+
+## Annotated SQL files (gutter markers)
+
+When a named query is compiled with `Payloadbuilder.compile(session, sql, "queryName")` and you register the corresponding source file, the coverage report generates an annotated `.annotated.sql` file alongside the JSON report. Each SQL line is prefixed with a gutter character:
+
+| Marker | Meaning |
+|--------|---------|
+| `✓` | Fully covered — every operator on this line executed and every CASE/IF branch and AND/OR outcome was seen |
+| `~` | Partially covered — the line was reached but at least one branch or outcome was never hit |
+| `✗` | Present in the plan but never executed |
+| ` ` | No coverage data for this line (comments, blank lines, DDL) |
+
+Register the source file on the extension:
+
+```java
+@RegisterExtension
+static final QueryCoverageExtension coverage = new QueryCoverageExtension()
+        .registerSource("my-query", "src/test/resources/queries/my-query.sql");
+```
+
+The name must match the third argument to `Payloadbuilder.compile(session, sql, "my-query")`. Multi-statement files compiled as `my-query`, `my-query#1`, … are automatically merged into one annotated file.
+
+Example annotated output written to `target/coverage/MyTest-my-query.annotated.sql`:
+
+```
+✓  1 | select *
+✓  2 | from orders o
+✓  3 | inner join customers c on c.id = o.customerId
+~  4 | where o.status = 'open'
+✗  5 |   and o.amount > 1000
+   6 | order by o.createdAt desc
+```
+
+> **Tip** — wire this up in CI by archiving `target/coverage/` as a build artefact. Developers can open the `.annotated.sql` files directly in their IDE to see which lines their test suite never reached.
+
+---
+
+## See also
+
+- `QueryCoverageExtensionExampleTest` in `src/test/java` — runnable end-to-end example including `registerSource` usage
+- `CoveragePlan`, `InstrumentedCaseExpression`, `InstrumentedLogicalBinaryExpression` in `payloadbuilder-core` — engine-side implementation
diff --git a/payloadbuilder-test/pom.xml b/payloadbuilder-test/pom.xml
new file mode 100644
index 000000000..8d3c85de2
--- /dev/null
+++ b/payloadbuilder-test/pom.xml
@@ -0,0 +1,38 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+    <parent>
+        <groupId>se.kuseman</groupId>
+        <artifactId>payloadbuilder</artifactId>
+        <version>1.13.0-SNAPSHOT</version>
+    </parent>
+    <groupId>se.kuseman.payloadbuilder</groupId>
+    <artifactId>payloadbuilder-test</artifactId>
+    <name>Payloadbuilder :: Test</name>
+    <url>https://github.com/kuseman/payloadbuilder</url>
+
+    <properties>
+        <main.basedir>${project.parent.basedir}</main.basedir>
+    </properties>
+
+    <dependencies>
+        <dependency>
+            <groupId>se.kuseman.payloadbuilder</groupId>
+            <artifactId>payloadbuilder-core</artifactId>
+            <version>${project.version}</version>
+        </dependency>
+        <!-- JUnit API as compile dependency since this module IS a test utility library -->
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter-api</artifactId>
+            <scope>compile</scope>
+        </dependency>
+        <!-- TEST -->
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter</artifactId>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+</project>
diff --git a/payloadbuilder-test/src/main/java/se/kuseman/payloadbuilder/test/CoverageAccumulator.java b/payloadbuilder-test/src/main/java/se/kuseman/payloadbuilder/test/CoverageAccumulator.java
new file mode 100644
index 000000000..3b1f9bdb2
--- /dev/null
+++ b/payloadbuilder-test/src/main/java/se/kuseman/payloadbuilder/test/CoverageAccumulator.java
@@ -0,0 +1,52 @@
+package se.kuseman.payloadbuilder.test;
+
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+
+import se.kuseman.payloadbuilder.core.execution.QueryCoverageData;
+import se.kuseman.payloadbuilder.core.execution.QueryCoverageRegistry;
+
+/**
+ * Accumulates {@link QueryCoverageData} from all queries executed during a test class run. Multiple executions of the same query (same plan structure or query name) are merged into a single entry
+ * rather than recorded separately. Thread-safe: the listener may be called from multiple test threads when JUnit parallel execution is enabled.
+ */
+public class CoverageAccumulator implements QueryCoverageRegistry.CoverageListener
+{
+    private final String testClassName;
+    /** Insertion-ordered map keyed by query key (compile-time name or plan-structure hash). */
+    private final Map<String, QueryCoverageData> byKey = new LinkedHashMap<>();
+
+    /** Creates an accumulator for the given test class display name. */
+    public CoverageAccumulator(String testClassName)
+    {
+        this.testClassName = testClassName;
+    }
+
+    @Override
+    public synchronized void onQueryCoverage(QueryCoverageData data)
+    {
+        QueryCoverageData existing = byKey.get(data.getQueryKey());
+        if (existing == null)
+        {
+            byKey.put(data.getQueryKey(), data);
+        }
+        else
+        {
+            existing.merge(data);
+        }
+    }
+
+    /** Returns the test class name this accumulator belongs to. */
+    public String getTestClassName()
+    {
+        return testClassName;
+    }
+
+    /** Returns all aggregated coverage entries — one per unique query. */
+    public synchronized List<QueryCoverageData> getCollected()
+    {
+        return new ArrayList<>(byKey.values());
+    }
+}
diff --git a/payloadbuilder-test/src/main/java/se/kuseman/payloadbuilder/test/CoverageReport.java b/payloadbuilder-test/src/main/java/se/kuseman/payloadbuilder/test/CoverageReport.java
new file mode 100644
index 000000000..d0022b28f
--- /dev/null
+++ b/payloadbuilder-test/src/main/java/se/kuseman/payloadbuilder/test/CoverageReport.java
@@ -0,0 +1,312 @@
+package se.kuseman.payloadbuilder.test;
+
+import java.io.IOException;
+import java.io.UncheckedIOException;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.nio.file.Paths;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+import se.kuseman.payloadbuilder.core.execution.QueryCoverageData;
+import se.kuseman.payloadbuilder.core.execution.QueryCoverageData.BranchCoverage;
+import se.kuseman.payloadbuilder.core.execution.QueryCoverageData.ConditionCoverage;
+import se.kuseman.payloadbuilder.core.execution.QueryCoverageData.OperatorCoverage;
+
+/** Writes aggregate JSON and annotated SQL coverage reports for a test class run. */
+public class CoverageReport
+{
+    private CoverageReport()
+    {
+    }
+
+    /**
+     * Write coverage reports to {@code outputDir}. Always produces a JSON file. For each query that has a matching entry in {@code querySources}, also produces a {@code .annotated.sql} file showing
+     * every SQL line prefixed with {@code ✓} (covered), {@code ✗} (never executed), {@code ~} (partially covered), or a blank when no coverage data exists for that line.
+     *
+     * @param accumulator the collected coverage data
+     * @param outputDir directory where report files are written
+     * @param querySources map from compile-time query name to source file path; multi-statement keys ({@code name#1}, …) match via prefix
+     */
+    public static void write(CoverageAccumulator accumulator, Path outputDir, Map<String, String> querySources)
+    {
+        List<QueryCoverageData> collected = accumulator.getCollected();
+        if (collected.isEmpty())
+        {
+            return;
+        }
+
+        try
+        {
+            Files.createDirectories(outputDir);
+            String safeName = accumulator.getTestClassName()
+                    .replace('.', '_');
+            Path reportFile = outputDir.resolve(safeName + "-coverage.json");
+            String json = buildJson(accumulator.getTestClassName(), collected);
+            Files.write(reportFile, json.getBytes(StandardCharsets.UTF_8));
+        }
+        catch (IOException ex)
+        {
+            throw new UncheckedIOException("Failed to write JSON coverage report", ex);
+        }
+
+        if (querySources.isEmpty())
+        {
+            return;
+        }
+
+        // Group collected data by base query name (strip the #N suffix used for multi-statement files)
+        Map<String, List<QueryCoverageData>> byBaseName = new HashMap<>();
+        for (QueryCoverageData data : collected)
+        {
+            String baseName = baseName(data.getQueryKey());
+            byBaseName.computeIfAbsent(baseName, k -> new ArrayList<>())
+                    .add(data);
+        }
+
+        for (Map.Entry<String, String> entry : querySources.entrySet())
+        {
+            List<QueryCoverageData> matching = byBaseName.get(entry.getKey());
+            if (matching == null
+                    || matching.isEmpty())
+            {
+                continue;
+            }
+            Path sourceFile = resolveSourcePath(entry.getValue());
+            if (!Files.exists(sourceFile))
+            {
+                continue;
+            }
+            try
+            {
+                String safeName = accumulator.getTestClassName()
+                        .replace('.', '_');
+                String safeKey = entry.getKey()
+                        .replace('#', '-')
+                        .replace(' ', '_');
+                writeAnnotated(sourceFile, matching, outputDir.resolve(safeName + "-" + safeKey + ".annotated.sql"));
+                Files.write(outputDir.resolve(safeName + "-" + safeKey + "-coverage.json"), buildJson(entry.getKey(), matching).getBytes(StandardCharsets.UTF_8));
+            }
+            catch (IOException ex)
+            {
+                throw new UncheckedIOException("Failed to write coverage report for " + entry.getKey(), ex);
+            }
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // Annotated SQL writer
+    // -------------------------------------------------------------------------
+
+    private static void writeAnnotated(Path sourceFile, List<QueryCoverageData> dataList, Path out) throws IOException
+    {
+        List<String> lines = Files.readAllLines(sourceFile, StandardCharsets.UTF_8);
+        int totalLines = lines.size();
+        int lineNumWidth = String.valueOf(totalLines)
+                .length();
+
+        // Build line → items maps by merging all statements for this source file
+        Map<Integer, List<OperatorCoverage>> opsByLine = new HashMap<>();
+        Map<Integer, List<BranchCoverage>> branchesByLine = new HashMap<>();
+        Map<Integer, List<ConditionCoverage>> condsByLine = new HashMap<>();
+
+        for (QueryCoverageData data : dataList)
+        {
+            for (OperatorCoverage op : data.getOperators())
+            {
+                if (op.location != null
+                        && op.location.line() > 0)
+                {
+                    opsByLine.computeIfAbsent(op.location.line(), k -> new ArrayList<>())
+                            .add(op);
+                }
+            }
+            for (BranchCoverage br : data.getBranches())
+            {
+                if (br.location != null
+                        && br.location.line() > 0)
+                {
+                    branchesByLine.computeIfAbsent(br.location.line(), k -> new ArrayList<>())
+                            .add(br);
+                }
+            }
+            for (ConditionCoverage cond : data.getConditions())
+            {
+                if (cond.location != null
+                        && cond.location.line() > 0)
+                {
+                    condsByLine.computeIfAbsent(cond.location.line(), k -> new ArrayList<>())
+                            .add(cond);
+                }
+            }
+        }
+
+        StringBuilder sb = new StringBuilder();
+        for (int i = 0; i < lines.size(); i++)
+        {
+            int lineNum = i + 1;
+            char status = gutterChar(lineNum, opsByLine, branchesByLine, condsByLine);
+            sb.append(status == ' ' ? "  "
+                    : status + " ");
+            sb.append(String.format("%" + lineNumWidth + "d", lineNum));
+            sb.append(" | ");
+            sb.append(lines.get(i));
+            sb.append(System.lineSeparator());
+        }
+
+        Files.write(out, sb.toString()
+                .getBytes(StandardCharsets.UTF_8));
+    }
+
+    /**
+     * Computes the gutter character for one SQL line.
+     *
+     * <ul>
+     * <li>{@code ✓} — all coverage items on this line are fully covered (operator executed, all CASE branches hit, both AND/OR outcomes seen)</li>
+     * <li>{@code ✗} — coverage items exist on this line but none had any execution at all</li>
+     * <li>{@code ~} — coverage items exist and some executed, but at least one is not fully covered</li>
+     * <li>{@code ' '} — no coverage data for this line (e.g. comments, blank lines, SELECT list)</li>
+     * </ul>
+     */
+    private static char gutterChar(int lineNum, Map<Integer, List<OperatorCoverage>> opsByLine, Map<Integer, List<BranchCoverage>> branchesByLine, Map<Integer, List<ConditionCoverage>> condsByLine)
+    {
+        List<OperatorCoverage> ops = opsByLine.getOrDefault(lineNum, List.of());
+        List<BranchCoverage> branches = branchesByLine.getOrDefault(lineNum, List.of());
+        List<ConditionCoverage> conds = condsByLine.getOrDefault(lineNum, List.of());
+
+        if (ops.isEmpty()
+                && branches.isEmpty()
+                && conds.isEmpty())
+        {
+            return ' ';
+        }
+
+        boolean anyExecution = false;
+        boolean allFullyCovered = true;
+
+        for (OperatorCoverage op : ops)
+        {
+            if (op.executionCount > 0)
+            {
+                anyExecution = true;
+            }
+            if (!op.covered)
+            {
+                allFullyCovered = false;
+            }
+        }
+        for (BranchCoverage br : branches)
+        {
+            long totalHits = br.elseHits;
+            for (long h : br.whenHits)
+            {
+                totalHits += h;
+            }
+            if (totalHits > 0)
+            {
+                anyExecution = true;
+            }
+            boolean fullyHit = br.elseHits > 0
+                    && Arrays.stream(br.whenHits)
+                            .allMatch(h -> h > 0);
+            if (!fullyHit)
+            {
+                allFullyCovered = false;
+            }
+        }
+        for (ConditionCoverage cond : conds)
+        {
+            if (cond.trueHits > 0
+                    || cond.falseHits > 0)
+            {
+                anyExecution = true;
+            }
+            if (cond.trueHits == 0
+                    || cond.falseHits == 0)
+            {
+                allFullyCovered = false;
+            }
+        }
+
+        if (allFullyCovered)
+        {
+            return '✓';
+        }
+        if (!anyExecution)
+        {
+            return '✗';
+        }
+        return '~';
+    }
+
+    // -------------------------------------------------------------------------
+    // Helpers
+    // -------------------------------------------------------------------------
+
+    /** Strips the {@code #N} statement-index suffix added for multi-statement compiles. */
+    private static String baseName(String queryKey)
+    {
+        int hash = queryKey.lastIndexOf('#');
+        if (hash > 0)
+        {
+            String suffix = queryKey.substring(hash + 1);
+            if (suffix.chars()
+                    .allMatch(Character::isDigit))
+            {
+                return queryKey.substring(0, hash);
+            }
+        }
+        return queryKey;
+    }
+
+    /** Resolves a source file path — absolute or relative to the project base directory. */
+    private static Path resolveSourcePath(String sourceFile)
+    {
+        Path path = Paths.get(sourceFile);
+        if (!path.isAbsolute())
+        {
+            String base = System.getProperty("maven.projectBasedir", System.getProperty("user.dir", "."));
+            path = Paths.get(base, sourceFile);
+        }
+        return path;
+    }
+
+    // -------------------------------------------------------------------------
+    // JSON report
+    // -------------------------------------------------------------------------
+
+    private static String buildJson(String testClassName, List<QueryCoverageData> queries)
+    {
+        StringBuilder sb = new StringBuilder();
+        sb.append("{\"test_class\":\"")
+                .append(escapeJson(testClassName))
+                .append("\"");
+        sb.append(",\"queries\":[");
+        boolean firstQuery = true;
+        for (QueryCoverageData data : queries)
+        {
+            if (!firstQuery)
+            {
+                sb.append(",");
+            }
+            firstQuery = false;
+            sb.append(data.toJson());
+        }
+        sb.append("]}");
+        return sb.toString();
+    }
+
+    private static String escapeJson(String s)
+    {
+        if (s == null)
+        {
+            return "";
+        }
+        return s.replace("\\", "\\\\")
+                .replace("\"", "\\\"");
+    }
+}
diff --git a/payloadbuilder-test/src/main/java/se/kuseman/payloadbuilder/test/CoverageTestFactory.java b/payloadbuilder-test/src/main/java/se/kuseman/payloadbuilder/test/CoverageTestFactory.java
new file mode 100644
index 000000000..adf63ca85
--- /dev/null
+++ b/payloadbuilder-test/src/main/java/se/kuseman/payloadbuilder/test/CoverageTestFactory.java
@@ -0,0 +1,288 @@
+package se.kuseman.payloadbuilder.test;
+
+import static org.junit.jupiter.api.Assertions.fail;
+import static org.junit.jupiter.api.DynamicContainer.dynamicContainer;
+import static org.junit.jupiter.api.DynamicTest.dynamicTest;
+
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.stream.Stream;
+
+import org.junit.jupiter.api.DynamicNode;
+
+import se.kuseman.payloadbuilder.core.execution.QueryCoverageData;
+import se.kuseman.payloadbuilder.core.execution.QueryCoverageData.BranchCoverage;
+import se.kuseman.payloadbuilder.core.execution.QueryCoverageData.ConditionCoverage;
+import se.kuseman.payloadbuilder.core.execution.QueryCoverageData.OperatorCoverage;
+import se.kuseman.payloadbuilder.core.parser.Location;
+
+/**
+ * Converts a {@link CoverageAccumulator} into a stream of JUnit 5 {@code DynamicNode}s — one container per unique query. Operators are displayed as a nested tree mirroring the physical plan
+ * hierarchy: operators that wrap inner plans become {@code DynamicContainer}s so a green outer operator containing a red inner operator is immediately visible. An outer operator that ran but has at
+ * least one uncovered descendant also fails its own {@code execution} test with an explicit message, combining option B (propagate failure) and option C (hierarchy). CASE/IF branches and AND/OR
+ * conditions remain flat beneath the operator tree. Call from a {@code @TestFactory @Order(Integer.MAX_VALUE)} method so all regular tests have run first:
+ *
+ * <pre>
+ * {@code @TestFactory}
+ * {@code @Order(Integer.MAX_VALUE)}
+ * Stream&lt;DynamicNode&gt; queryCoverageResults() {
+ *     return CoverageTestFactory.from(coverage.getAccumulator());
+ * }
+ * </pre>
+ */
+public class CoverageTestFactory
+{
+    private CoverageTestFactory()
+    {
+    }
+
+    /** Builds the dynamic test tree from the given accumulator. Returns an empty stream if no queries were collected. */
+    public static Stream<DynamicNode> from(CoverageAccumulator accumulator)
+    {
+        if (accumulator == null
+                || accumulator.getCollected()
+                        .isEmpty())
+        {
+            return Stream.empty();
+        }
+
+        List<DynamicNode> queryContainers = new ArrayList<>();
+        for (QueryCoverageData data : accumulator.getCollected())
+        {
+            List<DynamicNode> tests = new ArrayList<>();
+
+            // Build parent→children index from the flat operator list
+            Map<Integer, List<OperatorCoverage>> childrenByParent = new HashMap<>();
+            for (OperatorCoverage op : data.getOperators())
+            {
+                childrenByParent.computeIfAbsent(op.parentNodeId, k -> new ArrayList<>())
+                        .add(op);
+            }
+
+            // Root operators (parentNodeId == -1) seed the tree
+            for (OperatorCoverage root : childrenByParent.getOrDefault(-1, Collections.emptyList()))
+            {
+                tests.add(buildOperatorNode(root, childrenByParent));
+            }
+
+            for (BranchCoverage br : data.getBranches())
+            {
+                for (int i = 0; i < br.whenHits.length; i++)
+                {
+                    final int branchIndex = i;
+                    final long hits = br.whenHits[i];
+                    tests.add(dynamicTest(branchLabel(br, "WHEN " + i, hits), () ->
+                    {
+                        if (hits == 0)
+                        {
+                            fail("WHEN " + branchIndex + " never matched — 0 hits");
+                        }
+                    }));
+                }
+
+                final long elseHits = br.elseHits;
+                tests.add(dynamicTest(branchLabel(br, "ELSE", elseHits), () ->
+                {
+                    if (elseHits == 0)
+                    {
+                        fail("ELSE branch never taken — 0 hits");
+                    }
+                }));
+            }
+
+            for (ConditionCoverage cond : data.getConditions())
+            {
+                final long trueHits = cond.trueHits;
+                final long falseHits = cond.falseHits;
+                tests.add(dynamicTest(conditionLabel(cond, "true", trueHits), () ->
+                {
+                    if (trueHits == 0)
+                    {
+                        fail("condition never true — 0 hits");
+                    }
+                }));
+                tests.add(dynamicTest(conditionLabel(cond, "false", falseHits), () ->
+                {
+                    if (falseHits == 0)
+                    {
+                        fail("condition never false — 0 hits");
+                    }
+                }));
+            }
+
+            if (!tests.isEmpty())
+            {
+                queryContainers.add(dynamicContainer(containerLabel(data), tests.stream()));
+            }
+        }
+
+        return queryContainers.stream();
+    }
+
+    private static String containerLabel(QueryCoverageData data)
+    {
+        long totalOps = data.getOperators()
+                .size();
+        long coveredOps = data.getOperators()
+                .stream()
+                .filter(op -> op.covered)
+                .count();
+
+        long totalBranches = 0;
+        long coveredBranches = 0;
+        for (BranchCoverage br : data.getBranches())
+        {
+            for (long hits : br.whenHits)
+            {
+                totalBranches++;
+                if (hits > 0)
+                {
+                    coveredBranches++;
+                }
+            }
+            totalBranches++;
+            if (br.elseHits > 0)
+            {
+                coveredBranches++;
+            }
+        }
+
+        long totalConds = data.getConditions()
+                .size() * 2L;
+        long coveredConds = data.getConditions()
+                .stream()
+                .mapToLong(c -> (c.trueHits > 0 ? 1
+                        : 0)
+                        + (c.falseHits > 0 ? 1
+                                : 0))
+                .sum();
+
+        StringBuilder sb = new StringBuilder(data.getQueryKey());
+        sb.append(" — ")
+                .append(coveredOps)
+                .append("/")
+                .append(totalOps)
+                .append(" operators");
+        if (totalBranches > 0)
+        {
+            sb.append(", ")
+                    .append(coveredBranches)
+                    .append("/")
+                    .append(totalBranches)
+                    .append(" branches");
+        }
+        if (totalConds > 0)
+        {
+            sb.append(", ")
+                    .append(coveredConds)
+                    .append("/")
+                    .append(totalConds)
+                    .append(" conditions");
+        }
+        return sb.toString();
+    }
+
+    /**
+     * Builds a {@code DynamicNode} for one operator. Leaf operators become a {@code DynamicTest}. Operators with children become a {@code DynamicContainer} whose first child is an {@code execution}
+     * test (B-style: fails if the operator ran but left descendants uncovered) followed by the children's own nodes.
+     */
+    private static DynamicNode buildOperatorNode(OperatorCoverage op, Map<Integer, List<OperatorCoverage>> childrenByParent)
+    {
+        String label = operatorLabel(op);
+        List<OperatorCoverage> children = childrenByParent.getOrDefault(op.nodeId, Collections.emptyList());
+
+        if (children.isEmpty())
+        {
+            return dynamicTest(label, () ->
+            {
+                if (!op.covered)
+                {
+                    fail("not covered — 0 executions");
+                }
+            });
+        }
+
+        // Operator has inner operators — promote to a container
+        List<DynamicNode> childNodes = new ArrayList<>();
+
+        // B: the operator's own execution test also fails when descendants are uncovered
+        long uncovered = countUncoveredDescendants(op.nodeId, childrenByParent);
+        childNodes.add(dynamicTest("execution", () ->
+        {
+            if (!op.covered)
+            {
+                fail("not covered — 0 executions");
+            }
+            else if (uncovered > 0)
+            {
+                fail("covered (" + op.executionCount
+                     + " execution"
+                     + (op.executionCount != 1 ? "s"
+                             : "")
+                     + ") but "
+                     + uncovered
+                     + " inner operator"
+                     + (uncovered != 1 ? "s"
+                             : "")
+                     + " not covered — inner path not exercised in any test");
+            }
+        }));
+
+        for (OperatorCoverage child : children)
+        {
+            childNodes.add(buildOperatorNode(child, childrenByParent));
+        }
+
+        return dynamicContainer(label, childNodes.stream());
+    }
+
+    private static long countUncoveredDescendants(int nodeId, Map<Integer, List<OperatorCoverage>> childrenByParent)
+    {
+        long count = 0;
+        for (OperatorCoverage child : childrenByParent.getOrDefault(nodeId, Collections.emptyList()))
+        {
+            if (!child.covered)
+            {
+                count++;
+            }
+            count += countUncoveredDescendants(child.nodeId, childrenByParent);
+        }
+        return count;
+    }
+
+    private static String operatorLabel(OperatorCoverage op)
+    {
+        Location loc = op.location;
+        if (loc != null
+                && loc.line() > 0)
+        {
+            return op.name + " [line " + loc.line() + "]";
+        }
+        return op.name + " [id:" + op.nodeId + "]";
+    }
+
+    private static String branchLabel(BranchCoverage br, String branchName, long hits)
+    {
+        Location loc = br.location;
+        if (loc != null
+                && loc.line() > 0)
+        {
+            return "CASE [line " + loc.line() + "] → " + branchName + " (" + hits + " hits)";
+        }
+        return "CASE → " + branchName + " (" + hits + " hits)";
+    }
+
+    private static String conditionLabel(ConditionCoverage cond, String outcome, long hits)
+    {
+        Location loc = cond.location;
+        if (loc != null
+                && loc.line() > 0)
+        {
+            return cond.expressionText + " [line " + loc.line() + "] → " + outcome + " (" + hits + " hits)";
+        }
+        return cond.expressionText + " → " + outcome + " (" + hits + " hits)";
+    }
+}
diff --git a/payloadbuilder-test/src/main/java/se/kuseman/payloadbuilder/test/QueryCoverageExtension.java b/payloadbuilder-test/src/main/java/se/kuseman/payloadbuilder/test/QueryCoverageExtension.java
new file mode 100644
index 000000000..909ff6793
--- /dev/null
+++ b/payloadbuilder-test/src/main/java/se/kuseman/payloadbuilder/test/QueryCoverageExtension.java
@@ -0,0 +1,195 @@
+package se.kuseman.payloadbuilder.test;
+
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.nio.file.Paths;
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+
+import org.junit.jupiter.api.extension.AfterAllCallback;
+import org.junit.jupiter.api.extension.BeforeAllCallback;
+import org.junit.jupiter.api.extension.ExtensionContext;
+import org.junit.jupiter.api.extension.ExtensionContext.Namespace;
+import org.junit.jupiter.api.extension.ExtensionContext.Store;
+
+import se.kuseman.payloadbuilder.core.execution.PlanRule;
+import se.kuseman.payloadbuilder.core.execution.PlanRuleRegistry;
+import se.kuseman.payloadbuilder.core.execution.QueryCoverageData;
+import se.kuseman.payloadbuilder.core.execution.QueryCoverageData.BranchCoverage;
+import se.kuseman.payloadbuilder.core.execution.QueryCoverageData.ConditionCoverage;
+import se.kuseman.payloadbuilder.core.execution.QueryCoverageData.OperatorCoverage;
+import se.kuseman.payloadbuilder.core.execution.QueryCoverageRegistry;
+
+/**
+ * JUnit 5 extension for SQL query coverage tracking and compile-time plan rule enforcement. Use {@code @ExtendWith} for a console summary only, or {@code @RegisterExtension static} to get a reference
+ * needed for {@link CoverageTestFactory#from(CoverageAccumulator)} in a {@code @TestFactory @Order(Integer.MAX_VALUE)} method. A JSON report is written to the build output directory after all tests
+ * complete (see {@link #resolveOutputDir()} for the per-tool convention). Plan rules (e.g. no full table scans) are registered via {@link #addRule(PlanRule)} and are checked at compile time; a
+ * {@link se.kuseman.payloadbuilder.core.execution.PlanRuleViolationException} propagates as a normal test failure on the {@code @Test} method that triggered the compile.
+ */
+public class QueryCoverageExtension implements BeforeAllCallback, AfterAllCallback
+{
+    private static final Namespace NAMESPACE = Namespace.create(QueryCoverageExtension.class);
+    private static final String ACCUMULATOR_KEY = "accumulator";
+
+    private CoverageAccumulator accumulator;
+    private final List<PlanRule> planRules = new ArrayList<>();
+    private final Map<String, String> querySources = new LinkedHashMap<>();
+
+    /**
+     * Registers the source file path for a named query. When present, {@link CoverageReport} generates an annotated {@code .annotated.sql} file alongside the JSON report, showing each SQL line marked
+     * with {@code ✓} (covered), {@code ✗} (never executed), or {@code ~} (partially covered). The name must match the one passed to {@code Payloadbuilder.compile(session, sql, queryName)}.
+     * Multi-statement files compiled as {@code name}, {@code name#1}, … are automatically merged into one annotated file. Returns {@code this} for fluent chaining.
+     */
+    public QueryCoverageExtension registerSource(String queryName, String sourceFile)
+    {
+        querySources.put(queryName, sourceFile);
+        return this;
+    }
+
+    /**
+     * Registers a {@link PlanRule} that will be checked against every compiled physical plan on this thread while the extension is active. Call before tests run — typically in the field initialiser
+     * or in {@code @BeforeAll}. Returns {@code this} for fluent chaining.
+     *
+     * <pre>
+     * {@code @RegisterExtension}
+     * static final QueryCoverageExtension coverage = new QueryCoverageExtension()
+     *     .addRule(new NoFullTableScanRule());
+     * </pre>
+     */
+    public QueryCoverageExtension addRule(PlanRule rule)
+    {
+        planRules.add(rule);
+        return this;
+    }
+
+    @Override
+    public void beforeAll(ExtensionContext context)
+    {
+        accumulator = new CoverageAccumulator(context.getDisplayName());
+        getStore(context).put(ACCUMULATOR_KEY, accumulator);
+        QueryCoverageRegistry.register(accumulator);
+        planRules.forEach(PlanRuleRegistry::register);
+    }
+
+    @Override
+    public void afterAll(ExtensionContext context)
+    {
+        planRules.forEach(PlanRuleRegistry::deregister);
+        QueryCoverageRegistry.deregister(accumulator);
+        CoverageReport.write(accumulator, resolveOutputDir(), querySources);
+        publishCoverageSummary(context, accumulator);
+    }
+
+    /** Returns the accumulator holding all coverage data collected so far. Non-null after {@link #beforeAll} has run. */
+    public CoverageAccumulator getAccumulator()
+    {
+        return accumulator;
+    }
+
+    private static void publishCoverageSummary(ExtensionContext context, CoverageAccumulator acc)
+    {
+        long totalOperators = 0;
+        long uncoveredOperators = 0;
+        long totalBranches = 0;
+        long uncoveredBranches = 0;
+        long totalConditions = 0;
+        long uncoveredConditions = 0;
+
+        for (QueryCoverageData data : acc.getCollected())
+        {
+            for (OperatorCoverage op : data.getOperators())
+            {
+                totalOperators++;
+                if (!op.covered)
+                {
+                    uncoveredOperators++;
+                }
+            }
+            for (BranchCoverage br : data.getBranches())
+            {
+                for (long hits : br.whenHits)
+                {
+                    totalBranches++;
+                    if (hits == 0)
+                    {
+                        uncoveredBranches++;
+                    }
+                }
+                totalBranches++;
+                if (br.elseHits == 0)
+                {
+                    uncoveredBranches++;
+                }
+            }
+            for (ConditionCoverage cond : data.getConditions())
+            {
+                totalConditions += 2;
+                if (cond.trueHits == 0)
+                {
+                    uncoveredConditions++;
+                }
+                if (cond.falseHits == 0)
+                {
+                    uncoveredConditions++;
+                }
+            }
+        }
+
+        if (totalOperators == 0)
+        {
+            return;
+        }
+
+        String summary = String.format("operators: %d/%d covered, branches: %d/%d covered, conditions: %d/%d covered", totalOperators - uncoveredOperators, totalOperators,
+                totalBranches - uncoveredBranches, totalBranches, totalConditions - uncoveredConditions, totalConditions);
+        context.publishReportEntry(Map.of("query-coverage", summary));
+    }
+
+    private static Store getStore(ExtensionContext context)
+    {
+        return context.getStore(NAMESPACE);
+    }
+
+    /**
+     * Resolves the coverage output directory using build-tool conventions, checked in order:
+     * <ol>
+     * <li>System property {@code payloadbuilder.coverage.outputDir} — explicit override for any tool or CI environment.</li>
+     * <li>Maven via Surefire: {@code maven.projectBasedir} is set → {@code <basedir>/target/coverage}.</li>
+     * <li>Maven in Eclipse (no Surefire): {@code pom.xml} found in {@code user.dir} → {@code <user.dir>/target/coverage}.</li>
+     * <li>Gradle: {@code build.gradle} or {@code build.gradle.kts} found in {@code user.dir} → {@code <user.dir>/build/coverage}.</li>
+     * <li>Ant: {@code build.xml} found in {@code user.dir} → {@code <user.dir>/build/coverage}.</li>
+     * <li>Fallback: {@code <user.dir>/target/coverage}.</li>
+     * </ol>
+     */
+    static Path resolveOutputDir()
+    {
+        String explicit = System.getProperty("payloadbuilder.coverage.outputDir");
+        if (explicit != null
+                && !explicit.isEmpty())
+        {
+            return Paths.get(explicit);
+        }
+        String mavenBasedir = System.getProperty("maven.projectBasedir");
+        if (mavenBasedir != null)
+        {
+            return Paths.get(mavenBasedir, "target", "coverage");
+        }
+        Path userDir = Paths.get(System.getProperty("user.dir", "."));
+        if (Files.exists(userDir.resolve("pom.xml")))
+        {
+            return userDir.resolve(Paths.get("target", "coverage"));
+        }
+        if (Files.exists(userDir.resolve("build.gradle"))
+                || Files.exists(userDir.resolve("build.gradle.kts")))
+        {
+            return userDir.resolve(Paths.get("build", "coverage"));
+        }
+        if (Files.exists(userDir.resolve("build.xml")))
+        {
+            return userDir.resolve(Paths.get("build", "coverage"));
+        }
+        return userDir.resolve(Paths.get("target", "coverage"));
+    }
+}
diff --git a/payloadbuilder-test/src/test/java/se/kuseman/payloadbuilder/test/QueryCoverageExtensionExampleTest.java b/payloadbuilder-test/src/test/java/se/kuseman/payloadbuilder/test/QueryCoverageExtensionExampleTest.java
new file mode 100644
index 000000000..45920b7e5
--- /dev/null
+++ b/payloadbuilder-test/src/test/java/se/kuseman/payloadbuilder/test/QueryCoverageExtensionExampleTest.java
@@ -0,0 +1,152 @@
+package se.kuseman.payloadbuilder.test;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.io.InputStream;
+import java.nio.charset.StandardCharsets;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.stream.Stream;
+
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.DynamicNode;
+import org.junit.jupiter.api.MethodOrderer;
+import org.junit.jupiter.api.Order;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.TestFactory;
+import org.junit.jupiter.api.TestMethodOrder;
+import org.junit.jupiter.api.extension.RegisterExtension;
+
+import se.kuseman.payloadbuilder.api.catalog.Schema;
+import se.kuseman.payloadbuilder.api.execution.TupleVector;
+import se.kuseman.payloadbuilder.core.CompiledQuery;
+import se.kuseman.payloadbuilder.core.Payloadbuilder;
+import se.kuseman.payloadbuilder.core.RawQueryResult;
+import se.kuseman.payloadbuilder.core.catalog.CatalogRegistry;
+import se.kuseman.payloadbuilder.core.execution.QuerySession;
+import se.kuseman.payloadbuilder.core.execution.vector.BufferAllocator;
+import se.kuseman.payloadbuilder.core.execution.vector.VectorFactory;
+import se.kuseman.payloadbuilder.core.physicalplan.CoveragePlan;
+
+/**
+ * End-to-end example for {@link QueryCoverageExtension} and {@link CoverageTestFactory}. Shows named queries (compile-time name via {@code Payloadbuilder.compile(session, sql, queryName)}) and the
+ * {@code @TestFactory} at the bottom that produces one JUnit entry per operator and CASE branch once all regular tests have run.
+ */
+@TestMethodOrder(MethodOrderer.OrderAnnotation.class)
+class QueryCoverageExtensionExampleTest
+{
+    @RegisterExtension
+    static final QueryCoverageExtension coverage = new QueryCoverageExtension().registerSource("filter-example", "src/test/resources/queries/filter-example.sql");
+
+    private QuerySession session;
+
+    @BeforeEach
+    void setUp()
+    {
+        session = new QuerySession(new CatalogRegistry());
+        session.setVectorFactory(new VectorFactory(new BufferAllocator()));
+    }
+
+    @Test
+    @Order(1)
+    void filterQuery() throws Exception
+    {
+        // Named at compile time — aggregates across repeated executions and labels coverage nodes
+        // with the name "filter-example" instead of a plan hash.
+        String sql = readResource("/queries/filter-example.sql");
+        CompiledQuery query = Payloadbuilder.compile(session, sql, "filter-example");
+        List<TupleVector> rows = execute(query);
+
+        assertEquals(1, rows.size());
+        assertEquals(3, rows.get(0)
+                .getRowCount());
+    }
+
+    @Test
+    @Order(2)
+    void caseExpression()
+    {
+        // Unnamed query — falls back to plan-hash container label
+        List<TupleVector> rows = execute(
+                Payloadbuilder.compile(session, "select case when x > 0 then 'positive' when x < 0 then 'negative' else 'zero' end as sign" + " from (values (1), (-2), (0)) t(x)"));
+
+        assertEquals(1, rows.size());
+        int signCol = rows.get(0)
+                .getSchema()
+                .getSize() - 2;
+        assertEquals("positive", rows.get(0)
+                .getColumn(signCol)
+                .getString(0)
+                .toString());
+    }
+
+    @Test
+    @Order(3)
+    void coverageColumnPresent()
+    {
+        List<TupleVector> rows = execute(Payloadbuilder.compile(session, "select 1 + 1 as result"));
+
+        assertNotNull(rows);
+        TupleVector tv = rows.get(0);
+        String lastCol = tv.getSchema()
+                .getColumns()
+                .get(tv.getSchema()
+                        .getSize() - 1)
+                .getName();
+        assertEquals(CoveragePlan.COVERAGE_COLUMN, lastCol);
+        String json = tv.getColumn(tv.getSchema()
+                .getSize() - 1)
+                .getString(0)
+                .toString();
+        assertTrue(json.contains("\"operators\""));
+    }
+
+    // Must be last — accumulator is empty until @Test methods above have run
+    @TestFactory
+    @Order(Integer.MAX_VALUE)
+    Stream<DynamicNode> queryCoverageResults()
+    {
+        return CoverageTestFactory.from(coverage.getAccumulator());
+    }
+
+    // --- helpers ---
+
+    /** Reads a classpath resource (e.g. {@code "/queries/filter-example.sql"}) as a UTF-8 string. */
+    private static String readResource(String path) throws Exception
+    {
+        try (InputStream in = QueryCoverageExtensionExampleTest.class.getResourceAsStream(path))
+        {
+            if (in == null)
+            {
+                throw new IllegalArgumentException("Classpath resource not found: " + path);
+            }
+            return new String(in.readAllBytes(), StandardCharsets.UTF_8).trim();
+        }
+    }
+
+    private List<TupleVector> execute(CompiledQuery query)
+    {
+        List<TupleVector> result = new ArrayList<>();
+        RawQueryResult raw = query.executeRaw(session);
+        while (raw.hasMoreResults())
+        {
+            raw.consumeResult(new RawQueryResult.ResultConsumer()
+            {
+                @Override
+                public void schema(Schema schema)
+                {
+                }
+
+                @Override
+                public boolean consume(TupleVector vector)
+                {
+                    result.add(vector);
+                    return true;
+                }
+            });
+        }
+        return result;
+    }
+}
diff --git a/payloadbuilder-test/src/test/resources/queries/filter-example.sql b/payloadbuilder-test/src/test/resources/queries/filter-example.sql
new file mode 100644
index 000000000..2a5bb2739
--- /dev/null
+++ b/payloadbuilder-test/src/test/resources/queries/filter-example.sql
@@ -0,0 +1,3 @@
+select x
+from (values (1),(2),(3),(4),(5)) t(x)
+where x > 2
diff --git a/pom.xml b/pom.xml
index 2525f6c0f..4db5f4ba5 100644
--- a/pom.xml
+++ b/pom.xml
@@ -65,6 +65,7 @@
         <module>payloadbuilder-core</module>
         <module>payloadbuilder-catalog</module>
         <module>payloadbuilder-bytes</module>
+        <module>payloadbuilder-test</module>
     </modules>
 
     <dependencyManagement>