From 434028a816158af7a99c9098f501d7de76f620bf Mon Sep 17 00:00:00 2001
From: Andrei Lepikhov <lepihov@gmail.com>
Date: Thu, 24 Sep 2026 15:48:33 +0200
Subject: [PATCH 1/7] Make the key order of the HTML diff report total

comparePKComponent compared two numbers by value, but a number and a
string as strings. That order is not transitive: "1a" < "9" < "10", but
"10" < "1a". The keys come from map iteration, so sort.Slice put rows
with such keys in a different order on each run.

Numbers now come before all other strings. NaN and the infinities count
as text, because NaN is not equal even to itself.
---
 pkg/common/html_reporter.go      | 21 +++++++++++------
 pkg/common/html_reporter_test.go | 39 ++++++++++++++++++++++++++++++++
 2 files changed, 53 insertions(+), 7 deletions(-)
 create mode 100644 pkg/common/html_reporter_test.go

diff --git a/pkg/common/html_reporter.go b/pkg/common/html_reporter.go
index 131b280..e6e5fb6 100644
--- a/pkg/common/html_reporter.go
+++ b/pkg/common/html_reporter.go
@@ -17,6 +17,7 @@ import (
 	"encoding/json"
 	"fmt"
 	"html/template"
+	"math"
 	"path/filepath"
 	"sort"
 	"strconv"
@@ -726,10 +727,16 @@ func comparePKKey(a, b string) int {
 	}
 }
 
+// comparePKComponent orders numbers by value and before all other strings,
+// and other strings byte-wise. The order must be total. The keys come from
+// map iteration, and with an order that is not transitive (as when a number
+// and a string compared as strings, so that "1a" < "9" < "10" but
+// "10" < "1a") sort.Slice put the rows in a different order on each run.
 func comparePKComponent(a, b string) int {
 	numA, okA := parseNumeric(a)
 	numB, okB := parseNumeric(b)
-	if okA && okB {
+	switch {
+	case okA && okB:
 		switch {
 		case numA < numB:
 			return -1
@@ -738,14 +745,12 @@ func comparePKComponent(a, b string) int {
 		default:
 			return 0
 		}
-	}
-	if a < b {
+	case okA:
 		return -1
-	}
-	if a > b {
+	case okB:
 		return 1
 	}
-	return 0
+	return strings.Compare(a, b)
 }
 
 func parseNumeric(val string) (float64, bool) {
@@ -753,7 +758,9 @@ func parseNumeric(val string) (float64, bool) {
 		return 0, false
 	}
 	num, err := strconv.ParseFloat(val, 64)
-	if err != nil {
+	// NaN is not equal to anything, itself included, and would break the
+	// order; treat it and the infinities as text.
+	if err != nil || math.IsNaN(num) || math.IsInf(num, 0) {
 		return 0, false
 	}
 	return num, true
diff --git a/pkg/common/html_reporter_test.go b/pkg/common/html_reporter_test.go
new file mode 100644
index 0000000..a37db17
--- /dev/null
+++ b/pkg/common/html_reporter_test.go
@@ -0,0 +1,39 @@
+// ///////////////////////////////////////////////////////////////////////////
+//
+// # ACE - Active Consistency Engine
+//
+// Copyright (C) 2023 - 2026, pgEdge (https://www.pgedge.com/)
+//
+// This software is released under the PostgreSQL License:
+// https://opensource.org/license/postgresql
+//
+// ///////////////////////////////////////////////////////////////////////////
+
+package common
+
+import "testing"
+
+func TestComparePKComponentIsATotalOrder(t *testing.T) {
+	vals := []string{"1", "1.0", "2", "9", "10", "1a", "10a", "9a", "", "NaN", "Inf", "-1", "abc", "a"}
+	sign := func(x int) int {
+		switch {
+		case x < 0:
+			return -1
+		case x > 0:
+			return 1
+		}
+		return 0
+	}
+	for _, a := range vals {
+		for _, b := range vals {
+			if sign(comparePKComponent(a, b)) != -sign(comparePKComponent(b, a)) {
+				t.Errorf("not antisymmetric: %q, %q", a, b)
+			}
+			for _, c := range vals {
+				if comparePKComponent(a, b) < 0 && comparePKComponent(b, c) < 0 && comparePKComponent(a, c) >= 0 {
+					t.Errorf("not transitive: %q < %q < %q but not %q < %q", a, b, c, a, c)
+				}
+			}
+		}
+	}
+}

From 4106731ba6f89a17969139b42fc307b409d886fa Mon Sep 17 00:00:00 2001
From: Andrei Lepikhov <lepihov@gmail.com>
Date: Thu, 24 Sep 2026 15:51:03 +0200
Subject: [PATCH 2/7] Stream the HTML diff report to disk

table-diff --output html was killed by the OOM killer on a diff of
493,200 rows, while the JSON report for the same diff was written
without trouble. The HTML writer held the whole report in memory at
once: a json.Marshal copy of the full diff for the page script, a struct
with escaped cells for every row, and the rendered page in one
bytes.Buffer. Each row takes several kilobytes of markup, so the buffer
alone grew to gigabytes.

The template is now split into blocks: page head, pair head, one block
per row, pair tail and page tail. The writer runs them one by one into a
buffered writer on the report file, and builds the data of a row only
while that row is written. Only the row keys of the whole diff stay in
memory. If writing fails, the half-written file is removed, and the
error names the JSON report, which is complete.

The page script no longer gets a copy of the whole diff. It gets one
entry per row, with the pair, the kind of difference, and each primary
key value as the JSON text of the diff file, and it builds the repair
plan from that. The script copies the key text into the YAML as it is.
Before, it read keys as JavaScript numbers, so a bigint above 2^53 could
name the next row, and a text key such as "007" became 7 and matched no
row. Range rules are used only when every key of the diff is a whole
number.

On a synthetic diff of 493,200 rows, peak memory fell from 4.8 GB to
0.55 GB; the diff itself takes 0.2 GB. The markup of the page does not
change.

Tests: the rows on the page match the embedded rows for each pair; key
literals; the output is the same from run to run; a write error in each
part of the page is returned and leaves no file. Three tests run the
page script in Node.js (they skip without node) and resolve the plan
with the repair executor.
---
 .../consistency/repair/html_plan_e2e_test.go  | 201 +++++
 pkg/common/html_reporter.go                   | 730 ++++++++++++------
 pkg/common/html_reporter_test.go              | 382 ++++++++-
 pkg/common/templates/diff_report.html         | 121 +--
 pkg/common/templates/diff_report.js           | 202 ++---
 pkg/common/utils.go                           |   3 +-
 6 files changed, 1209 insertions(+), 430 deletions(-)
 create mode 100644 internal/consistency/repair/html_plan_e2e_test.go

diff --git a/internal/consistency/repair/html_plan_e2e_test.go b/internal/consistency/repair/html_plan_e2e_test.go
new file mode 100644
index 0000000..974776d
--- /dev/null
+++ b/internal/consistency/repair/html_plan_e2e_test.go
@@ -0,0 +1,201 @@
+// ///////////////////////////////////////////////////////////////////////////
+//
+// # ACE - Active Consistency Engine
+//
+// Copyright (C) 2023 - 2026, pgEdge (https://www.pgedge.com/)
+//
+// This software is released under the PostgreSQL License:
+// https://opensource.org/license/postgresql
+//
+// ///////////////////////////////////////////////////////////////////////////
+
+package repair
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"strings"
+	"testing"
+
+	planner "github.com/pgedge/ace/internal/consistency/repair/plan"
+	utils "github.com/pgedge/ace/pkg/common"
+	"github.com/pgedge/ace/pkg/types"
+)
+
+// These tests check the whole path of a repair plan built in the HTML
+// report: table-diff writes the JSON and HTML reports, the page script
+// (run in Node.js, with no user choices) builds the YAML plan, and the
+// repair executor resolves that plan against the full JSON diff. They skip
+// when node is not installed.
+
+// planScript runs buildPlanYaml from the page on the page's embedded data.
+// It takes the script and the data out of the page itself, so it tests what
+// a browser would run.
+const planScript = `
+const fs = require('fs');
+const [htmlPath, outPath] = process.argv.slice(2);
+const page = fs.readFileSync(htmlPath, 'utf8');
+const data = page.match(/<script id="diff-data" type="application\/json">([\s\S]*?)<\/script>/)[1];
+const scripts = [...page.matchAll(/<script>([\s\S]*?)<\/script>/g)];
+let src = scripts[scripts.length - 1][1].trim();
+src = src.replace(/^\(function \(\) \{/, '').replace(/\}\)\(\);?$/, '');
+const doc = {
+    getElementById: () => ({ textContent: data }),
+    querySelectorAll: () => [],
+    querySelector: () => null,
+};
+const build = new Function('document', src + '; return buildPlanYaml;')(doc);
+fs.writeFileSync(outPath, build(JSON.parse(data), { usingSelection: false }));
+`
+
+func e2eRow(id any, v string) types.OrderedMap {
+	return types.OrderedMap{{Key: "id", Value: id}, {Key: "v", Value: v}}
+}
+
+// runHTMLPlan writes the reports for diff, builds the plan on the page, and
+// resolves it. It returns the upserted primary keys per
+// node, the plan, and the resolver error.
+func runHTMLPlan(t *testing.T, diff types.DiffOutput) (map[string][]string, string, error) {
+	t.Helper()
+	node, err := exec.LookPath("node")
+	if err != nil {
+		t.Skip("node is not installed")
+	}
+	dir := t.TempDir()
+	t.Chdir(dir) // WriteDiffReport writes into the current directory
+
+	jsonPath, htmlPath, err := utils.WriteDiffReport(diff, "public", "t", "html")
+	if err != nil {
+		t.Fatalf("WriteDiffReport: %v", err)
+	}
+	scriptPath := filepath.Join(dir, "plan.js")
+	planPath := filepath.Join(dir, "plan.yaml")
+	if err := os.WriteFile(scriptPath, []byte(planScript), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if out, err := exec.Command(node, scriptPath, htmlPath, planPath).CombinedOutput(); err != nil {
+		t.Fatalf("page script failed: %v\n%s", err, out)
+	}
+	planText, err := os.ReadFile(planPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	plan, err := planner.LoadRepairPlanFile(planPath)
+	if err != nil {
+		t.Fatalf("plan does not load: %v\n%s", err, planText)
+	}
+	raw, err := os.ReadFile(jsonPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	task := &TableRepairTask{}
+	task.Schema, task.Table = "public", "t"
+	task.Key = []string{"id"}
+	task.SimplePrimaryKey = true
+	task.RepairPlan = plan
+	if err := json.Unmarshal(raw, &task.RawDiffs); err != nil {
+		t.Fatal(err)
+	}
+
+	upserts, _, err := CalculatePlanRepairSets(task)
+	got := map[string][]string{}
+	for nodeName, rows := range upserts {
+		for _, row := range rows {
+			got[nodeName] = append(got[nodeName], fmt.Sprint(row["id"]))
+		}
+		sort.Strings(got[nodeName])
+	}
+	return got, string(planText), err
+}
+
+// twoNodeDiff: 30 value differences (1..30), 15 rows missing on n2
+// (31..45), 8 rows missing on n1 (46..53).
+func twoNodeDiff() types.DiffOutput {
+	var a, b []types.OrderedMap
+	for id := 1; id <= 30; id++ {
+		a = append(a, e2eRow(id, "a"))
+		b = append(b, e2eRow(id, "b"))
+	}
+	for id := 31; id <= 45; id++ {
+		a = append(a, e2eRow(id, "a"))
+	}
+	for id := 46; id <= 53; id++ {
+		b = append(b, e2eRow(id, "b"))
+	}
+	return types.DiffOutput{
+		NodeDiffs: map[string]types.DiffByNodePair{"n1/n2": {Rows: map[string][]types.OrderedMap{"n1": a, "n2": b}}},
+		Summary: types.DiffSummary{Schema: "public", Table: "t", Nodes: []string{"n1", "n2"},
+			PrimaryKey: []string{"id"}, DiffRowsCount: map[string]int{"n1/n2": 53}},
+	}
+}
+
+// Every row is on the page, so the plan covers every row: the default
+// keep_n1 for value differences, and explicit inserts for missing rows.
+func TestHTMLPlanCompleteReport(t *testing.T) {
+	got, plan, err := runHTMLPlan(t, twoNodeDiff())
+	if err != nil {
+		t.Fatalf("plan does not resolve: %v\n%s", err, plan)
+	}
+	if len(got["n2"]) != 45 || len(got["n1"]) != 8 {
+		t.Errorf("upserts: got n1=%d n2=%d, want n1=8 n2=45", len(got["n1"]), len(got["n2"]))
+	}
+	if !strings.Contains(plan, "type: keep_n1") {
+		t.Errorf("plan has no keep_n1 default:\n%s", plan)
+	}
+}
+
+// JSON.parse would round these keys to the same float, so a plan built from
+// parsed numbers names the wrong rows. The keys exist on one node only, so
+// the plan must have explicit rules for them.
+func TestHTMLPlanBigintKeys(t *testing.T) {
+	a := []types.OrderedMap{e2eRow(int64(9007199254740995), "a"), e2eRow(int64(9007199254740996), "a")}
+	b := []types.OrderedMap{e2eRow(int64(9007199254740997), "b")}
+	diff := types.DiffOutput{
+		NodeDiffs: map[string]types.DiffByNodePair{"n1/n2": {Rows: map[string][]types.OrderedMap{"n1": a, "n2": b}}},
+		Summary: types.DiffSummary{Schema: "public", Table: "t", PrimaryKey: []string{"id"},
+			DiffRowsCount: map[string]int{"n1/n2": 3}},
+	}
+	got, plan, err := runHTMLPlan(t, diff)
+	if err != nil {
+		t.Fatalf("plan does not resolve: %v\n%s", err, plan)
+	}
+	want := map[string][]string{
+		"n2": {"9007199254740995", "9007199254740996"},
+		"n1": {"9007199254740997"},
+	}
+	if fmt.Sprint(got) != fmt.Sprint(want) {
+		t.Errorf("upserts: got %v, want %v\n%s", got, want, plan)
+	}
+}
+
+// Text keys that look like numbers must stay text in the plan. If they turn
+// into numbers, no rule matches these rows missing on n1, the plan default
+// keep_n1 applies to them, and table-repair rejects the plan.
+func TestHTMLPlanTextKeysThatLookNumeric(t *testing.T) {
+	var b []types.OrderedMap
+	for _, id := range []string{"001", "002", "003"} {
+		b = append(b, e2eRow(id, "b"))
+	}
+	diff := types.DiffOutput{
+		NodeDiffs: map[string]types.DiffByNodePair{"n1/n2": {Rows: map[string][]types.OrderedMap{"n1": nil, "n2": b}}},
+		Summary: types.DiffSummary{Schema: "public", Table: "t", PrimaryKey: []string{"id"},
+			DiffRowsCount: map[string]int{"n1/n2": 3}},
+	}
+	got, plan, err := runHTMLPlan(t, diff)
+	if err != nil {
+		t.Fatalf("plan does not resolve: %v\n%s", err, plan)
+	}
+	want := map[string][]string{"n1": {"001", "002", "003"}}
+	if fmt.Sprint(got) != fmt.Sprint(want) {
+		t.Errorf("upserts: got %v, want %v\n%s", got, want, plan)
+	}
+	if regexp.MustCompile(`range:`).MatchString(plan) {
+		t.Errorf("plan uses a range for text keys:\n%s", plan)
+	}
+}
diff --git a/pkg/common/html_reporter.go b/pkg/common/html_reporter.go
index e6e5fb6..6e515ac 100644
--- a/pkg/common/html_reporter.go
+++ b/pkg/common/html_reporter.go
@@ -12,13 +12,16 @@
 package common
 
 import (
-	"bytes"
+	"bufio"
 	_ "embed"
 	"encoding/json"
 	"fmt"
 	"html/template"
+	"io"
 	"math"
+	"os"
 	"path/filepath"
+	"regexp"
 	"sort"
 	"strconv"
 	"strings"
@@ -36,99 +39,331 @@ var htmlDiffCSS string
 //go:embed templates/diff_report.js
 var htmlDiffJS string
 
+// htmlWriteBufferSize is the size of the buffer in front of the report file.
+// It is a variable only so that tests can make every write reach the writer.
+var htmlWriteBufferSize = 256 * 1024
+
 // htmlPairCount captures the diff counts grouped by node pair for the report summary.
 type htmlPairCount struct {
 	Name  string
 	Count string
 }
 
-func writeHTMLDiffReport(diffResult types.DiffOutput, jsonFilePath string) (string, error) {
-	if jsonFilePath == "" {
-		return "", nil
-	}
+type htmlSummaryItem struct {
+	Label string
+	Value string
+}
 
-	rawJSON, err := json.Marshal(diffResult)
-	if err != nil {
-		return "", fmt.Errorf("failed to marshal diff result for HTML embedding: %w", err)
+type htmlSummaryData struct {
+	Items     []htmlSummaryItem
+	Breakdown []htmlPairCount
+}
+
+type htmlReportHead struct {
+	CSS     template.CSS
+	Summary htmlSummaryData
+}
+
+type htmlReportTail struct {
+	JS template.JS
+}
+
+// htmlPairHead is the data for the "pair_head" and "pair_tail" blocks.
+type htmlPairHead struct {
+	NodeA     string
+	NodeB     string
+	DiffCount string
+	HasDiffs  bool
+}
+
+type htmlGroupHead struct {
+	Title         string
+	DividerBefore bool
+}
+
+type htmlCell struct {
+	Column     string
+	IsKey      bool
+	NodeAHTML  template.HTML
+	NodeAClass string
+	NodeBHTML  template.HTML
+	NodeBClass string
+	HasDiff    bool
+}
+
+// htmlRow is the data for one "value_row" or "missing_row" block.
+type htmlRow struct {
+	NodeA     string
+	NodeB     string
+	First     bool
+	PKey      string
+	RowType   string // "value_diff", "missing_in_a", "missing_in_b"
+	Cells     []htmlCell
+	NodeAJSON string
+}
+
+// htmlReportInfo goes into the embedded diff data, next to the list of rows
+// (see writeHTMLDiffData).
+type htmlReportInfo struct {
+	IntegerPK bool `json:"integer_pk"`
+}
+
+// htmlPlanRow is what the page script needs to write a repair-plan rule for
+// one row of the report. Key is the display key, as in data-pk. Type uses the names
+// of the repair executor. PK holds each primary key value as the JSON text
+// that the diff file has for it. The script copies that text into the YAML
+// as it is and never turns it into a JavaScript number, so a bigint keeps
+// every digit and a text key such as "007" stays text.
+type htmlPlanRow struct {
+	Pair  string   `json:"pair"`
+	NodeA string   `json:"node_a"`
+	NodeB string   `json:"node_b"`
+	Key   string   `json:"key"`
+	Type  string   `json:"type"`
+	PK    []string `json:"pk"`
+}
+
+// htmlPairPlan lists the report rows of one node pair, in report order:
+// value differences, then rows missing on node B, then rows missing on node A.
+// It holds only row keys. The row data stays in the diff result, and the
+// markup for a row exists only while that row is written.
+type htmlPairPlan struct {
+	pairKey    string
+	nodeA      string
+	nodeB      string
+	columns    []string
+	rowMapA    map[string]types.OrderedMap
+	rowMapB    map[string]types.OrderedMap
+	display    map[string]string
+	valueKeys  []string
+	missingInB []string
+	missingInA []string
+}
+
+func (p *htmlPairPlan) total() int {
+	return len(p.valueKeys) + len(p.missingInB) + len(p.missingInA)
+}
+
+// planType is the repair executor's name for the kind of difference of a row
+// in this pair: row_mismatch, missing_on_n2 or missing_on_n1, where n1 and n2
+// are node A and node B of the pair.
+const (
+	planTypeMismatch  = "row_mismatch"
+	planTypeMissingN2 = "missing_on_n2"
+	planTypeMissingN1 = "missing_on_n1"
+)
+
+// pkLiterals returns each primary key value of the row as JSON text, the
+// same text the diff file has for it.
+func pkLiterals(row types.OrderedMap, primaryKey []string) []string {
+	m := OrderedMapToMap(row)
+	out := make([]string, len(primaryKey))
+	for i, col := range primaryKey {
+		b, err := json.Marshal(m[col])
+		if err != nil {
+			b = []byte("null")
+		}
+		out[i] = string(b)
 	}
+	return out
+}
 
-	htmlPath := strings.TrimSuffix(jsonFilePath, filepath.Ext(jsonFilePath)) + ".html"
-	summary := diffResult.Summary
+var integerLiteralRe = regexp.MustCompile(`^-?[0-9]+$`)
 
-	type summaryItem struct {
-		Label string
-		Value string
+// htmlIntegerPK tells whether the primary key is a single column and every
+// row of the diff, in every pair, has a whole number in it. Only then can the
+// page script write a range rule: a range over the keys 1 and 2 would also
+// match a key 1.5 that has a rule of its own.
+func htmlIntegerPK(plans []*htmlPairPlan, primaryKey []string) bool {
+	if len(primaryKey) != 1 {
+		return false
 	}
+	isInt := func(rows map[string]types.OrderedMap) bool {
+		for _, row := range rows {
+			if !integerLiteralRe.MatchString(pkLiterals(row, primaryKey)[0]) {
+				return false
+			}
+		}
+		return true
+	}
+	for _, p := range plans {
+		if !isInt(p.rowMapA) || !isInt(p.rowMapB) {
+			return false
+		}
+	}
+	return true
+}
 
-	type summaryData struct {
-		Items     []summaryItem
-		Breakdown []htmlPairCount
+// buildHTMLPairPlan pairs the rows of the two nodes and sorts them. A row
+// that exists on both nodes but shows no difference after stringifyCellValue
+// (for example 1 against "1", or a difference only in _spock_metadata_) is
+// left out, as before. It returns nil when the pair has no rows to show.
+func buildHTMLPairPlan(pairKey string, nodeDiff types.DiffByNodePair, primaryKey []string) *htmlPairPlan {
+	nodeNames := strings.Split(pairKey, "/")
+	if len(nodeNames) != 2 {
+		nodeNames = nodeNames[:0]
+		for name := range nodeDiff.Rows {
+			nodeNames = append(nodeNames, name)
+		}
+		sort.Strings(nodeNames)
+		if len(nodeNames) < 2 {
+			return nil
+		}
 	}
 
-	type cell struct {
-		Column     string
-		IsKey      bool
-		NodeAHTML  template.HTML
-		NodeAClass string
-		NodeBHTML  template.HTML
-		NodeBClass string
-		HasDiff    bool
+	p := &htmlPairPlan{
+		pairKey: pairKey,
+		nodeA:   nodeNames[0],
+		nodeB:   nodeNames[1],
 	}
+	rowsA := nodeDiff.Rows[p.nodeA]
+	rowsB := nodeDiff.Rows[p.nodeB]
+	if len(rowsA) == 0 && len(rowsB) == 0 {
+		return nil
+	}
+
+	p.columns = collectColumnsInOrder(primaryKey, rowsA, rowsB)
+
+	// Two keys per row, and they are not interchangeable. buildRowKey is
+	// the collision-proof identity used to pair a row on A with the same
+	// row on B; buildRowDisplayKey is the plain rendering shown in the
+	// report and embedded in data-pk, which the report's own JavaScript
+	// interpolates into a CSS attribute selector and so cannot carry the
+	// quotes the identity encoding adds.
+	p.display = make(map[string]string, len(rowsA)+len(rowsB))
 
-	type row struct {
-		PKey      string
-		Cells     []cell
-		RowType   string // "value_diff", "missing_in_a", "missing_in_b"
-		HasDiffs  bool
-		NodeAJSON string
+	p.rowMapA = make(map[string]types.OrderedMap, len(rowsA))
+	for idx, row := range rowsA {
+		key := buildRowKey(row, primaryKey, idx)
+		p.rowMapA[key] = row
+		p.display[key] = buildRowDisplayKey(row, primaryKey, idx)
 	}
 
-	type missingGroup struct {
-		Title         string
-		Rows          []row
-		DividerBefore bool
+	p.rowMapB = make(map[string]types.OrderedMap, len(rowsB))
+	for idx, row := range rowsB {
+		key := buildRowKey(row, primaryKey, idx)
+		p.rowMapB[key] = row
+		p.display[key] = buildRowDisplayKey(row, primaryKey, idx)
 	}
 
-	type pairSection struct {
-		NodeA      string
-		NodeB      string
-		DiffCount  string
-		ValueDiffs []row
-		Missing    []missingGroup
-		HasDiffs   bool
+	for key, rowA := range p.rowMapA {
+		if rowB, ok := p.rowMapB[key]; ok {
+			if rowsDiffer(rowA, rowB, p.columns) {
+				p.valueKeys = append(p.valueKeys, key)
+			}
+		} else {
+			p.missingInB = append(p.missingInB, key)
+		}
+	}
+	for key := range p.rowMapB {
+		if _, ok := p.rowMapA[key]; !ok {
+			p.missingInA = append(p.missingInA, key)
+		}
 	}
 
-	type reportData struct {
-		Summary     summaryData
-		Pairs       []pairSection
-		RawDiffJSON template.JS
-		CSS         template.CSS
-		JS          template.JS
+	sortPKKeys(p.valueKeys, p.display)
+	sortPKKeys(p.missingInA, p.display)
+	sortPKKeys(p.missingInB, p.display)
+	return p
+}
+
+func (p *htmlPairPlan) valueRow(key string, pkSet map[string]struct{}) htmlRow {
+	rowA := OrderedMapToMap(p.rowMapA[key])
+	rowB := OrderedMapToMap(p.rowMapB[key])
+
+	cells := make([]htmlCell, 0, len(p.columns))
+	for _, col := range p.columns {
+		valA := stringifyCellValue(rowA[col])
+		valB := stringifyCellValue(rowB[col])
+		_, isPK := pkSet[col]
+
+		htmlA, htmlB := highlightDifference(valA, valB)
+		c := htmlCell{
+			Column:    col,
+			IsKey:     isPK,
+			NodeAHTML: htmlA,
+			NodeBHTML: htmlB,
+			HasDiff:   valA != valB,
+		}
+		if c.HasDiff {
+			c.NodeAClass = "value-diff"
+			c.NodeBClass = "value-diff"
+		}
+		cells = append(cells, c)
+	}
+	return htmlRow{
+		NodeA:     p.nodeA,
+		NodeB:     p.nodeB,
+		PKey:      p.display[key],
+		RowType:   "value_diff",
+		Cells:     cells,
+		NodeAJSON: buildRowJSONPretty(p.rowMapA[key], p.columns),
+	}
+}
+
+// missingRow builds a row that exists on one node only. missingInB tells
+// which node lacks it.
+func (p *htmlPairPlan) missingRow(key string, missingInB bool, pkSet map[string]struct{}) htmlRow {
+	row := htmlRow{
+		NodeA: p.nodeA,
+		NodeB: p.nodeB,
+		PKey:  p.display[key],
+	}
+	var present map[string]any
+	if missingInB {
+		present = OrderedMapToMap(p.rowMapA[key])
+		row.RowType = "missing_in_b"
+		row.NodeAJSON = buildRowJSONPretty(p.rowMapA[key], p.columns)
+	} else {
+		present = OrderedMapToMap(p.rowMapB[key])
+		row.RowType = "missing_in_a"
+	}
+
+	row.Cells = make([]htmlCell, 0, len(p.columns))
+	for _, col := range p.columns {
+		val := plainHTML(stringifyCellValue(present[col]))
+		_, isPK := pkSet[col]
+		c := htmlCell{Column: col, IsKey: isPK}
+		if missingInB {
+			c.NodeAHTML = val
+			c.NodeBHTML = plainHTML("MISSING")
+			c.NodeBClass = "missing"
+		} else {
+			c.NodeAHTML = plainHTML("MISSING")
+			c.NodeAClass = "missing"
+			c.NodeBHTML = val
+		}
+		row.Cells = append(row.Cells, c)
 	}
+	return row
+}
 
-	summaryItems := []summaryItem{
+func buildHTMLSummaryItems(summary types.DiffSummary) []htmlSummaryItem {
+	items := []htmlSummaryItem{
 		{Label: "Table", Value: fmt.Sprintf("%s.%s", summary.Schema, summary.Table)},
 		{Label: "Nodes", Value: strings.Join(summary.Nodes, ", ")},
 		{Label: "Primary Key", Value: formatPrimaryKey(summary.PrimaryKey)},
 		{Label: "Total Differences", Value: formatInt64WithCommas(totalDiffs(summary.DiffRowsCount))},
-		{Label: "Total Rows Checked", Value: formatInt64WithCommas(summary.TotalRowsChecked)},
-		{Label: "Initial Ranges", Value: formatInt64WithCommas(int64(summary.InitialRangesCount))},
-		{Label: "Mismatched Ranges", Value: formatInt64WithCommas(int64(summary.MismatchedRangesCount))},
-		{Label: "Block Size", Value: formatInt64WithCommas(int64(summary.BlockSize))},
-		{Label: "Compare Unit Size", Value: formatInt64WithCommas(int64(summary.CompareUnitSize))},
-		{Label: "Concurrency Factor", Value: strconv.FormatFloat(summary.ConcurrencyFactor, 'f', -1, 64)},
-		{Label: "Time Taken", Value: formatDurationHuman(summary.TimeTaken)},
-		{Label: "Start Time", Value: formatTimestampHuman(summary.StartTime)},
-		{Label: "End Time", Value: formatTimestampHuman(summary.EndTime)},
 	}
+	items = append(items,
+		htmlSummaryItem{Label: "Total Rows Checked", Value: formatInt64WithCommas(summary.TotalRowsChecked)},
+		htmlSummaryItem{Label: "Initial Ranges", Value: formatInt64WithCommas(int64(summary.InitialRangesCount))},
+		htmlSummaryItem{Label: "Mismatched Ranges", Value: formatInt64WithCommas(int64(summary.MismatchedRangesCount))},
+		htmlSummaryItem{Label: "Block Size", Value: formatInt64WithCommas(int64(summary.BlockSize))},
+		htmlSummaryItem{Label: "Compare Unit Size", Value: formatInt64WithCommas(int64(summary.CompareUnitSize))},
+		htmlSummaryItem{Label: "Concurrency Factor", Value: strconv.FormatFloat(summary.ConcurrencyFactor, 'f', -1, 64)},
+		htmlSummaryItem{Label: "Time Taken", Value: formatDurationHuman(summary.TimeTaken)},
+		htmlSummaryItem{Label: "Start Time", Value: formatTimestampHuman(summary.StartTime)},
+		htmlSummaryItem{Label: "End Time", Value: formatTimestampHuman(summary.EndTime)},
+	)
 
 	if summary.MaxDiffRows > 0 {
-		summaryItems = append(summaryItems, summaryItem{
+		items = append(items, htmlSummaryItem{
 			Label: "Max Diff Rows",
 			Value: formatInt64WithCommas(summary.MaxDiffRows),
 		})
 		if summary.DiffRowLimitReached {
-			summaryItems = append(summaryItems, summaryItem{
+			items = append(items, htmlSummaryItem{
 				Label: "Stopped Early",
 				Value: "yes (max_diff_rows limit)",
 			})
@@ -139,19 +374,65 @@ func writeHTMLDiffReport(diffResult types.DiffOutput, jsonFilePath string) (stri
 	// like a clean one. People who read the report never see the worker
 	// errors, which only went to the log.
 	if len(summary.IncompletePairs) > 0 {
-		summaryItems = append(summaryItems, summaryItem{
+		items = append(items, htmlSummaryItem{
 			Label: "Comparison Incomplete",
 			Value: strings.Join(summary.IncompletePairs, ", ") + " (counts are lower bounds)",
 		})
 	}
 
-	var filteredItems []summaryItem
-	for _, item := range summaryItems {
+	var filtered []htmlSummaryItem
+	for _, item := range items {
 		if item.Value != "" && item.Value != "0" {
-			filteredItems = append(filteredItems, item)
+			filtered = append(filtered, item)
+		}
+	}
+	return filtered
+}
+
+// writeHTMLDiffReport writes the HTML report next to the JSON report.
+func writeHTMLDiffReport(diffResult types.DiffOutput, jsonFilePath string) (htmlPath string, err error) {
+	if jsonFilePath == "" {
+		return "", nil
+	}
+
+	path := strings.TrimSuffix(jsonFilePath, filepath.Ext(jsonFilePath)) + ".html"
+	f, err := CreateFileSecure(path)
+	if err != nil {
+		return "", fmt.Errorf("failed to create HTML diff report: %w", err)
+	}
+	// A report cut off in the middle looks complete in a browser up to the
+	// point where it stops, so do not leave one behind. The deferred call
+	// uses its own copy of the path: by the time it runs, "return "", err"
+	// has already cleared htmlPath.
+	defer func() {
+		if err != nil {
+			f.Close()
+			os.Remove(path)
 		}
+	}()
+
+	if err = renderHTMLDiffReport(f, diffResult); err != nil {
+		return "", err
+	}
+	if err = f.Close(); err != nil {
+		return "", fmt.Errorf("failed to close HTML diff report: %w", err)
 	}
+	return path, nil
+}
 
+// renderHTMLDiffReport writes the report to out.
+//
+// The report goes out block by block through a buffered writer. Only the row
+// keys of the whole diff are held in memory, never the markup: at several
+// kilobytes of markup per row, a document built in memory for a diff of half a
+// million rows needs gigabytes.
+func renderHTMLDiffReport(out io.Writer, diffResult types.DiffOutput) error {
+	tmpl, err := template.New("tableDiffReport").Parse(htmlDiffTemplate)
+	if err != nil {
+		return fmt.Errorf("failed to parse HTML template: %w", err)
+	}
+
+	summary := diffResult.Summary
 	pkSet := make(map[string]struct{}, len(summary.PrimaryKey))
 	for _, col := range summary.PrimaryKey {
 		pkSet[col] = struct{}{}
@@ -163,212 +444,170 @@ func writeHTMLDiffReport(diffResult types.DiffOutput, jsonFilePath string) (stri
 	}
 	sort.Strings(pairKeys)
 
-	pairs := make([]pairSection, 0, len(pairKeys))
-
+	var plans []*htmlPairPlan
 	for _, pairKey := range pairKeys {
-		nodeDiff := diffResult.NodeDiffs[pairKey]
-		nodeNames := strings.Split(pairKey, "/")
-		if len(nodeNames) != 2 {
-			nodeNames = nodeNames[:0]
-			for name := range nodeDiff.Rows {
-				nodeNames = append(nodeNames, name)
-			}
-			sort.Strings(nodeNames)
-			if len(nodeNames) < 2 {
-				continue
-			}
+		if p := buildHTMLPairPlan(pairKey, diffResult.NodeDiffs[pairKey], summary.PrimaryKey); p != nil {
+			plans = append(plans, p)
 		}
+	}
 
-		nodeA := nodeNames[0]
-		nodeB := nodeNames[1]
-		rowsA := nodeDiff.Rows[nodeA]
-		rowsB := nodeDiff.Rows[nodeB]
+	head := htmlReportHead{
+		CSS: template.CSS(htmlDiffCSS),
+		Summary: htmlSummaryData{
+			Items:     buildHTMLSummaryItems(summary),
+			Breakdown: buildDiffBreakdown(summary.DiffRowsCount),
+		},
+	}
 
-		if len(rowsA) == 0 && len(rowsB) == 0 {
-			continue
+	w := bufio.NewWriterSize(out, htmlWriteBufferSize)
+	if err := tmpl.ExecuteTemplate(w, "report_head", head); err != nil {
+		return fmt.Errorf("failed to render HTML diff report: %w", err)
+	}
+	if len(plans) == 0 {
+		if err := tmpl.ExecuteTemplate(w, "no_pairs", nil); err != nil {
+			return fmt.Errorf("failed to render HTML diff report: %w", err)
 		}
+	}
+	for _, p := range plans {
+		if err := writeHTMLPair(tmpl, w, p, summary, pkSet); err != nil {
+			return fmt.Errorf("failed to render HTML diff report: %w", err)
+		}
+	}
 
-		columns := collectColumnsInOrder(summary.PrimaryKey, rowsA, rowsB)
+	info := htmlReportInfo{IntegerPK: htmlIntegerPK(plans, summary.PrimaryKey)}
+	if err := writeHTMLDiffData(w, summary, plans, info, summary.PrimaryKey); err != nil {
+		return fmt.Errorf("failed to embed diff data in HTML report: %w", err)
+	}
 
-		// Two keys per row, and they are not interchangeable. buildRowKey is
-		// the collision-proof identity used to pair a row on A with the same
-		// row on B; buildRowDisplayKey is the plain rendering shown in the
-		// report and embedded in data-pk, which the report's own JavaScript
-		// interpolates into a CSS attribute selector and so cannot carry the
-		// quotes the identity encoding adds.
-		displayByKey := make(map[string]string, len(rowsA)+len(rowsB))
+	if err := tmpl.ExecuteTemplate(w, "report_tail", htmlReportTail{JS: template.JS(htmlDiffJS)}); err != nil {
+		return fmt.Errorf("failed to render HTML diff report: %w", err)
+	}
+	if err := w.Flush(); err != nil {
+		return fmt.Errorf("failed to write HTML diff report: %w", err)
+	}
+	return nil
+}
 
-		rowMapA := make(map[string]types.OrderedMap, len(rowsA))
-		for idx, row := range rowsA {
-			key := buildRowKey(row, summary.PrimaryKey, idx)
-			rowMapA[key] = row
-			displayByKey[key] = buildRowDisplayKey(row, summary.PrimaryKey, idx)
-		}
+// writeHTMLPair writes the section of one node pair, one row at a time.
+func writeHTMLPair(tmpl *template.Template, w io.Writer, p *htmlPairPlan, summary types.DiffSummary, pkSet map[string]struct{}) error {
+	head := htmlPairHead{
+		NodeA:     p.nodeA,
+		NodeB:     p.nodeB,
+		DiffCount: formatInt64WithCommas(int64(summary.DiffRowsCount[p.pairKey])),
+		HasDiffs:  p.total() > 0,
+	}
 
-		rowMapB := make(map[string]types.OrderedMap, len(rowsB))
-		for idx, row := range rowsB {
-			key := buildRowKey(row, summary.PrimaryKey, idx)
-			rowMapB[key] = row
-			displayByKey[key] = buildRowDisplayKey(row, summary.PrimaryKey, idx)
-		}
+	if err := tmpl.ExecuteTemplate(w, "pair_head", head); err != nil {
+		return err
+	}
 
-		var commonKeys []string
-		var missingInB []string
-		for key := range rowMapA {
-			if _, ok := rowMapB[key]; ok {
-				commonKeys = append(commonKeys, key)
-			} else {
-				missingInB = append(missingInB, key)
-			}
+	if len(p.valueKeys) > 0 {
+		if err := tmpl.ExecuteTemplate(w, "separator", "Value Differences"); err != nil {
+			return err
 		}
-
-		var missingInA []string
-		for key := range rowMapB {
-			if _, ok := rowMapA[key]; !ok {
-				missingInA = append(missingInA, key)
+		for i, key := range p.valueKeys {
+			row := p.valueRow(key, pkSet)
+			row.First = i == 0
+			if err := tmpl.ExecuteTemplate(w, "value_row", row); err != nil {
+				return err
 			}
 		}
+	}
 
-		sortPKKeys(commonKeys, displayByKey)
-		sortPKKeys(missingInA, displayByKey)
-		sortPKKeys(missingInB, displayByKey)
-
-		valueDiffs := make([]row, 0, len(commonKeys))
-		for _, key := range commonKeys {
-			rowA := OrderedMapToMap(rowMapA[key])
-			rowB := OrderedMapToMap(rowMapB[key])
-			if !rowsDiffer(rowMapA[key], rowMapB[key], columns) {
+	if len(p.missingInB) > 0 || len(p.missingInA) > 0 {
+		if err := tmpl.ExecuteTemplate(w, "separator", "Missing Rows"); err != nil {
+			return err
+		}
+		groups := []struct {
+			keys       []string
+			missingInB bool
+			title      string
+		}{
+			{p.missingInB, true, "Missing in " + p.nodeB},
+			{p.missingInA, false, "Missing in " + p.nodeA},
+		}
+		groupWritten := false
+		for _, g := range groups {
+			if len(g.keys) == 0 {
 				continue
 			}
-
-			var cells []cell
-			hasDiffs := false
-			for _, col := range columns {
-				valA := stringifyCellValue(rowA[col])
-				valB := stringifyCellValue(rowB[col])
-				_, isPK := pkSet[col]
-
-				htmlA, htmlB := highlightDifference(valA, valB)
-				hasDiff := valA != valB
-				c := cell{
-					Column:    col,
-					IsKey:     isPK,
-					NodeAHTML: htmlA,
-					NodeBHTML: htmlB,
-					HasDiff:   hasDiff,
-				}
-				if hasDiff {
-					c.NodeAClass = "value-diff"
-					c.NodeBClass = "value-diff"
-					hasDiffs = true
-				}
-				cells = append(cells, c)
+			if err := tmpl.ExecuteTemplate(w, "group_head", htmlGroupHead{Title: g.title, DividerBefore: groupWritten}); err != nil {
+				return err
 			}
-			valueDiffs = append(valueDiffs, row{
-				PKey:      displayByKey[key],
-				Cells:     cells,
-				RowType:   "value_diff",
-				HasDiffs:  hasDiffs,
-				NodeAJSON: buildRowJSONPretty(rowMapA[key], columns),
-			})
-		}
-
-		missingGroups := make([]missingGroup, 0)
-		if len(missingInB) > 0 {
-			group := missingGroup{Title: fmt.Sprintf("Missing in %s", nodeB)}
-			for _, key := range missingInB {
-				rowA := OrderedMapToMap(rowMapA[key])
-				var cells []cell
-				for _, col := range columns {
-					valA := stringifyCellValue(rowA[col])
-					_, isPK := pkSet[col]
-					cells = append(cells, cell{
-						Column:     col,
-						IsKey:      isPK,
-						NodeAHTML:  plainHTML(valA),
-						NodeBHTML:  plainHTML("MISSING"),
-						NodeBClass: "missing",
-						HasDiff:    false,
-					})
-				}
-				group.Rows = append(group.Rows, row{
-					PKey:      displayByKey[key],
-					Cells:     cells,
-					RowType:   "missing_in_b",
-					HasDiffs:  true,
-					NodeAJSON: buildRowJSONPretty(rowMapA[key], columns),
-				})
-			}
-			missingGroups = append(missingGroups, group)
-		}
-
-		if len(missingInA) > 0 {
-			group := missingGroup{Title: fmt.Sprintf("Missing in %s", nodeA)}
-			for _, key := range missingInA {
-				rowB := OrderedMapToMap(rowMapB[key])
-				var cells []cell
-				for _, col := range columns {
-					valB := stringifyCellValue(rowB[col])
-					_, isPK := pkSet[col]
-					cells = append(cells, cell{
-						Column:     col,
-						IsKey:      isPK,
-						NodeAHTML:  plainHTML("MISSING"),
-						NodeAClass: "missing",
-						NodeBHTML:  plainHTML(valB),
-						HasDiff:    false,
-					})
+			groupWritten = true
+			for i, key := range g.keys {
+				row := p.missingRow(key, g.missingInB, pkSet)
+				row.First = i == 0
+				if err := tmpl.ExecuteTemplate(w, "missing_row", row); err != nil {
+					return err
 				}
-				group.Rows = append(group.Rows, row{
-					PKey:     displayByKey[key],
-					Cells:    cells,
-					RowType:  "missing_in_a",
-					HasDiffs: true,
-				})
 			}
-			if len(missingGroups) > 0 {
-				group.DividerBefore = true
-			}
-			missingGroups = append(missingGroups, group)
-		}
-
-		pair := pairSection{
-			NodeA:      nodeA,
-			NodeB:      nodeB,
-			DiffCount:  formatInt64WithCommas(int64(summary.DiffRowsCount[pairKey])),
-			ValueDiffs: valueDiffs,
-			Missing:    missingGroups,
-			HasDiffs:   len(valueDiffs) > 0 || len(missingGroups) > 0,
 		}
-		pairs = append(pairs, pair)
 	}
 
-	report := reportData{
-		Summary: summaryData{
-			Items:     filteredItems,
-			Breakdown: buildDiffBreakdown(summary.DiffRowsCount),
-		},
-		Pairs:       pairs,
-		RawDiffJSON: template.JS(rawJSON),
-		CSS:         template.CSS(htmlDiffCSS),
-		JS:          template.JS(htmlDiffJS),
-	}
-
-	tmpl, err := template.New("tableDiffReport").Parse(htmlDiffTemplate)
-	if err != nil {
-		return "", fmt.Errorf("failed to parse HTML template: %w", err)
-	}
+	return tmpl.ExecuteTemplate(w, "pair_tail", head)
+}
 
-	var buf bytes.Buffer
-	if err := tmpl.Execute(&buf, report); err != nil {
-		return "", fmt.Errorf("failed to render HTML diff report: %w", err)
+// writeHTMLDiffData embeds the data that the page script needs to build a
+// repair plan: the diff summary, htmlReportInfo, and one htmlPlanRow for each
+// row of the report, in report order. The rows are written one at a time, so the
+// list never exists in memory as a whole.
+//
+// json.Marshal escapes '<', '>' and '&', so no value can close the script
+// element early.
+func writeHTMLDiffData(w *bufio.Writer, summary types.DiffSummary, plans []*htmlPairPlan, info htmlReportInfo, primaryKey []string) error {
+	writeJSON := func(v any) error {
+		b, err := json.Marshal(v)
+		if err != nil {
+			return err
+		}
+		w.Write(b)
+		return nil
 	}
 
-	if err := WriteFileSecure(htmlPath, buf.Bytes()); err != nil {
-		return "", fmt.Errorf("failed to write HTML diff report: %w", err)
+	w.WriteString(`<script id="diff-data" type="application/json">{"summary":`)
+	if err := writeJSON(summary); err != nil {
+		return err
+	}
+	w.WriteString(`,"html_report":`)
+	if err := writeJSON(info); err != nil {
+		return err
+	}
+	w.WriteString(`,"rows":[`)
+	first := true
+	for _, p := range plans {
+		lists := []struct {
+			keys     []string
+			rows     map[string]types.OrderedMap
+			planType string
+		}{
+			{p.valueKeys, p.rowMapA, planTypeMismatch},
+			{p.missingInB, p.rowMapA, planTypeMissingN2},
+			{p.missingInA, p.rowMapB, planTypeMissingN1},
+		}
+		for _, l := range lists {
+			for _, key := range l.keys {
+				if !first {
+					w.WriteByte(',')
+				}
+				first = false
+				if err := writeJSON(htmlPlanRow{
+					Pair:  p.pairKey,
+					NodeA: p.nodeA,
+					NodeB: p.nodeB,
+					Key:   p.display[key],
+					Type:  l.planType,
+					PK:    pkLiterals(l.rows[key], primaryKey),
+				}); err != nil {
+					return err
+				}
+			}
+		}
 	}
-
-	return htmlPath, nil
+	// bufio.Writer keeps the first write error and returns it from every
+	// later call, so a single check at the end covers all the writes above.
+	_, err := w.WriteString("]}</script>\n")
+	return err
 }
 
 func highlightDifference(a, b string) (template.HTML, template.HTML) {
@@ -458,8 +697,9 @@ func buildDiffBreakdown(diffCounts map[string]int) []htmlPairCount {
 }
 
 // buildRowKey returns the identity a row is matched by across the two nodes.
-// It falls back to the row's position when there is no usable primary key,
-// which pairs nothing but at least keeps distinct rows distinct.
+// It falls back to the row's position when there is no usable primary key.
+// That keeps distinct rows of one node distinct, but it pairs rows of the two
+// nodes by position only: __row_0 on A meets __row_0 on B, whatever they hold.
 func buildRowKey(row types.OrderedMap, primaryKey []string, index int) string {
 	if len(primaryKey) == 0 {
 		return fmt.Sprintf("__row_%d", index)
diff --git a/pkg/common/html_reporter_test.go b/pkg/common/html_reporter_test.go
index a37db17..ea0d83c 100644
--- a/pkg/common/html_reporter_test.go
+++ b/pkg/common/html_reporter_test.go
@@ -11,7 +11,327 @@
 
 package common
 
-import "testing"
+import (
+	"bytes"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+	"testing"
+
+	"github.com/pgedge/ace/pkg/types"
+)
+
+// htmlTestDiff builds a two-node diff with the given number of value
+// differences, rows missing on n2 and rows missing on n1. Primary keys are
+// 1..N in that order, so the report order is easy to predict.
+func htmlTestDiff(valueDiffs, missingOnB, missingOnA int, note string) types.DiffOutput {
+	row := func(id int, val string) types.OrderedMap {
+		return types.OrderedMap{
+			{Key: "id", Value: id},
+			{Key: "val", Value: val},
+			{Key: "note", Value: note},
+		}
+	}
+	var a, b []types.OrderedMap
+	id := 0
+	for i := 0; i < valueDiffs; i++ {
+		id++
+		a = append(a, row(id, "on-n1"))
+		b = append(b, row(id, "on-n2"))
+	}
+	for i := 0; i < missingOnB; i++ {
+		id++
+		a = append(a, row(id, "only-n1"))
+	}
+	for i := 0; i < missingOnA; i++ {
+		id++
+		b = append(b, row(id, "only-n2"))
+	}
+	return types.DiffOutput{
+		NodeDiffs: map[string]types.DiffByNodePair{
+			"n1/n2": {Rows: map[string][]types.OrderedMap{"n1": a, "n2": b}},
+		},
+		Summary: types.DiffSummary{
+			Schema:        "public",
+			Table:         "t",
+			Nodes:         []string{"n1", "n2"},
+			PrimaryKey:    []string{"id"},
+			DiffRowsCount: map[string]int{"n1/n2": valueDiffs + missingOnB + missingOnA},
+		},
+	}
+}
+
+type htmlTestData struct {
+	Summary    types.DiffSummary `json:"summary"`
+	HTMLReport htmlReportInfo    `json:"html_report"`
+	Rows       []htmlPlanRow     `json:"rows"`
+}
+
+// typeCounts counts the embedded plan rows of each type for one pair.
+func (d htmlTestData) typeCounts(pair string) map[string]int {
+	c := map[string]int{}
+	for _, r := range d.Rows {
+		if r.Pair == pair {
+			c[r.Type]++
+		}
+	}
+	return c
+}
+
+var diffDataRe = regexp.MustCompile(`(?s)<script id="diff-data" type="application/json">(.*?)</script>`)
+
+// renderHTMLTestReport writes the report and returns the page and the parsed
+// embedded diff data.
+func renderHTMLTestReport(t *testing.T, diff types.DiffOutput) (string, htmlTestData) {
+	t.Helper()
+	jsonPath := filepath.Join(t.TempDir(), "public_t_diffs-20260101000000.json")
+	htmlPath, err := writeHTMLDiffReport(diff, jsonPath)
+	if err != nil {
+		t.Fatalf("writeHTMLDiffReport: %v", err)
+	}
+	raw, err := os.ReadFile(htmlPath)
+	if err != nil {
+		t.Fatalf("read report: %v", err)
+	}
+	page := string(raw)
+	if !strings.HasSuffix(strings.TrimSpace(page), "</html>") {
+		t.Fatal("report does not end with </html>")
+	}
+
+	m := diffDataRe.FindStringSubmatch(page)
+	if m == nil {
+		t.Fatal("report has no diff-data script")
+	}
+	var data htmlTestData
+	if err := json.Unmarshal([]byte(m[1]), &data); err != nil {
+		t.Fatalf("embedded diff data is not valid JSON: %v", err)
+	}
+	return page, data
+}
+
+// countRows counts rendered rows of one type ("value_diff", "missing_in_a",
+// "missing_in_b"). Every rendered row has exactly one select checkbox.
+func countRows(page, rowType string) int {
+	re := regexp.MustCompile(`class="row-select" data-pk="[^"]*" data-type="` + rowType + `"`)
+	return len(re.FindAllStringIndex(page, -1))
+}
+
+func TestHTMLReportRowsAndData(t *testing.T) {
+	page, data := renderHTMLTestReport(t, htmlTestDiff(4, 2, 1, "x"))
+
+	if !strings.Contains(page, ">7 entries<") {
+		t.Error("section pill does not show the entry count")
+	}
+	if got := countRows(page, "value_diff"); got != 4 {
+		t.Errorf("value rows: got %d, want 4", got)
+	}
+	if got := countRows(page, "missing_in_b"); got != 2 {
+		t.Errorf("missing_in_b rows: got %d, want 2", got)
+	}
+	if got := countRows(page, "missing_in_a"); got != 1 {
+		t.Errorf("missing_in_a rows: got %d, want 1", got)
+	}
+
+	want := map[string]int{"row_mismatch": 4, "missing_on_n2": 2, "missing_on_n1": 1}
+	if got := data.typeCounts("n1/n2"); fmt.Sprint(got) != fmt.Sprint(want) {
+		t.Errorf("embedded rows: got %v, want %v", got, want)
+	}
+	if data.Summary.Table != "t" || len(data.Summary.PrimaryKey) != 1 {
+		t.Errorf("embedded summary is wrong: %+v", data.Summary)
+	}
+}
+
+// Primary key values go into the embedded JSON inside a <script> element,
+// twice: as the display key and as a JSON literal. A value must not be able
+// to close that element.
+func TestHTMLReportEmbeddedDataCannotCloseScript(t *testing.T) {
+	evil := `</script><script>alert(1)</script><!--`
+	diff := types.DiffOutput{
+		NodeDiffs: map[string]types.DiffByNodePair{"n1/n2": {Rows: map[string][]types.OrderedMap{
+			"n1": {{{Key: "id", Value: evil}, {Key: "v", Value: "a"}}},
+			"n2": {{{Key: "id", Value: evil}, {Key: "v", Value: "b"}}},
+		}}},
+		Summary: types.DiffSummary{Schema: "public", Table: "t", PrimaryKey: []string{"id"}, DiffRowsCount: map[string]int{"n1/n2": 1}},
+	}
+	page, data := renderHTMLTestReport(t, diff)
+
+	if strings.Contains(page, evil) {
+		t.Fatal("raw value with </script> appears in the page")
+	}
+	if got := strings.Count(page, "<script"); got != 2 {
+		t.Errorf("page has %d <script> tags, want 2", got)
+	}
+	if len(data.Rows) != 1 || data.Rows[0].Key != evil {
+		t.Fatalf("embedded key after decoding: got %+v", data.Rows)
+	}
+	var lit string
+	if err := json.Unmarshal([]byte(data.Rows[0].PK[0]), &lit); err != nil || lit != evil {
+		t.Errorf("embedded pk literal %q does not decode to the value (%v)", data.Rows[0].PK[0], err)
+	}
+}
+
+func TestHTMLReportNoRows(t *testing.T) {
+	diff := htmlTestDiff(0, 0, 0, "")
+	diff.Summary.IncompletePairs = []string{"n1/n2"}
+	page, data := renderHTMLTestReport(t, diff)
+
+	if !strings.Contains(page, "No row-level differences were recorded.") {
+		t.Error("empty report has no empty message")
+	}
+	if len(data.Rows) != 0 {
+		t.Errorf("embedded rows: got %d, want 0", len(data.Rows))
+	}
+}
+
+// threeNodeDiff has two node pairs with different row sets, so a mix-up
+// between pairs or nodes shows in the key checks.
+func threeNodeDiff() types.DiffOutput {
+	d := htmlTestDiff(12, 6, 4, "x")
+	pair := d.NodeDiffs["n1/n2"]
+	var n1, n3 []types.OrderedMap
+	for i := 101; i <= 110; i++ {
+		r := types.OrderedMap{{Key: "id", Value: i}, {Key: "val", Value: "a"}, {Key: "note", Value: "y"}}
+		n1 = append(n1, r)
+		if i%2 == 0 {
+			n3 = append(n3, types.OrderedMap{{Key: "id", Value: i}, {Key: "val", Value: "b"}, {Key: "note", Value: "y"}})
+		}
+	}
+	n3 = append(n3, types.OrderedMap{{Key: "id", Value: 200}, {Key: "val", Value: "c"}, {Key: "note", Value: "y"}})
+	d.NodeDiffs = map[string]types.DiffByNodePair{
+		"n1/n2": pair,
+		"n1/n3": {Rows: map[string][]types.OrderedMap{"n1": n1, "n3": n3}},
+	}
+	d.Summary.Nodes = []string{"n1", "n2", "n3"}
+	d.Summary.DiffRowsCount = map[string]int{"n1/n2": 22, "n1/n3": 11}
+	return d
+}
+
+// pageKeys returns, for each section (in page order), the primary keys of the
+// rendered rows by row type.
+func pageKeys(t *testing.T, page string) []map[string][]string {
+	t.Helper()
+	var sections []map[string][]string
+	for _, sec := range strings.Split(page, `<div class="diff-section" `)[1:] {
+		keys := map[string][]string{}
+		re := regexp.MustCompile(`class="row-select" data-pk="([^"]*)" data-type="([^"]*)"`)
+		for _, m := range re.FindAllStringSubmatch(sec, -1) {
+			keys[m[2]] = append(keys[m[2]], m[1])
+		}
+		sections = append(sections, keys)
+	}
+	return sections
+}
+
+// The page script builds repair plans from the embedded rows and picks
+// user choices by data-pk, so the rendered rows and the embedded rows must be
+// the same rows, of the same type, in the same order, for every pair.
+func TestHTMLReportPageAndDataHoldTheSameRows(t *testing.T) {
+	page, data := renderHTMLTestReport(t, threeNodeDiff())
+	sections := pageKeys(t, page)
+	if len(sections) != 2 {
+		t.Fatalf("got %d sections, want 2", len(sections))
+	}
+	pageType := map[string]string{"row_mismatch": "value_diff", "missing_on_n2": "missing_in_b", "missing_on_n1": "missing_in_a"}
+
+	for i, pc := range []struct{ pair, a, b string }{{"n1/n2", "n1", "n2"}, {"n1/n3", "n1", "n3"}} {
+		got := map[string][]string{}
+		for _, r := range data.Rows {
+			if r.Pair != pc.pair {
+				continue
+			}
+			if r.NodeA != pc.a || r.NodeB != pc.b {
+				t.Errorf("%s: row %s has nodes %s/%s", pc.pair, r.Key, r.NodeA, r.NodeB)
+			}
+			if r.PK[0] != r.Key {
+				t.Errorf("%s: pk literal %s does not match key %s", pc.pair, r.PK[0], r.Key)
+			}
+			got[pageType[r.Type]] = append(got[pageType[r.Type]], r.Key)
+		}
+		if fmt.Sprint(got) != fmt.Sprint(sections[i]) {
+			t.Errorf("%s: embedded rows %v, page shows %v", pc.pair, got, sections[i])
+		}
+	}
+	if len(data.Rows) != 22+11 {
+		t.Errorf("embedded rows: got %d, want 33", len(data.Rows))
+	}
+}
+
+// Keys go into the plan as the JSON text of the diff file, so a bigint keeps
+// every digit and a text key that looks like a number stays text. Ranges are
+// allowed only when every key of the diff is a whole number.
+func TestHTMLReportPKLiterals(t *testing.T) {
+	one := func(v1, v2 any) types.DiffOutput {
+		return types.DiffOutput{
+			NodeDiffs: map[string]types.DiffByNodePair{"n1/n2": {Rows: map[string][]types.OrderedMap{
+				"n1": {{{Key: "id", Value: v1}, {Key: "v", Value: "a"}}, {{Key: "id", Value: v2}, {Key: "v", Value: "a"}}},
+				"n2": {{{Key: "id", Value: v1}, {Key: "v", Value: "b"}}},
+			}}},
+			Summary: types.DiffSummary{Schema: "public", Table: "t", PrimaryKey: []string{"id"}, DiffRowsCount: map[string]int{"n1/n2": 2}},
+		}
+	}
+	for _, tc := range []struct {
+		name      string
+		v1, v2    any
+		lit1      string
+		integerPK bool
+	}{
+		{"bigint", int64(9007199254740995), int64(9007199254740996), "9007199254740995", true},
+		{"text that looks like a number", "007", "008", `"007"`, false},
+		{"fraction in another row", int64(1), 1.5, "1", false},
+		{"json number", json.Number("12345678901234567890"), json.Number("1"), "12345678901234567890", true},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			_, data := renderHTMLTestReport(t, one(tc.v1, tc.v2))
+			if data.Rows[0].PK[0] != tc.lit1 {
+				t.Errorf("pk literal: got %s, want %s", data.Rows[0].PK[0], tc.lit1)
+			}
+			if data.HTMLReport.IntegerPK != tc.integerPK {
+				t.Errorf("integer_pk: got %v, want %v", data.HTMLReport.IntegerPK, tc.integerPK)
+			}
+		})
+	}
+}
+
+// The report shows a prefix of the sorted rows, so the sort must not depend
+// on map order. Keys that mix numbers and text used to break that.
+func TestHTMLReportIsDeterministic(t *testing.T) {
+	var a, b []types.OrderedMap
+	for i := 1; i <= 60; i++ {
+		for _, id := range []string{fmt.Sprint(i), fmt.Sprintf("%da", i)} {
+			a = append(a, types.OrderedMap{{Key: "id", Value: id}, {Key: "val", Value: "a"}})
+			b = append(b, types.OrderedMap{{Key: "id", Value: id}, {Key: "val", Value: "b"}})
+		}
+	}
+	a = append(a, types.OrderedMap{{Key: "id", Value: "NaN"}, {Key: "val", Value: "a"}})
+	diff := types.DiffOutput{
+		NodeDiffs: map[string]types.DiffByNodePair{"n1/n2": {Rows: map[string][]types.OrderedMap{"n1": a, "n2": b}}},
+		Summary:   types.DiffSummary{Schema: "public", Table: "t", PrimaryKey: []string{"id"}, DiffRowsCount: map[string]int{"n1/n2": 121}},
+	}
+
+	var first string
+	for run := 0; run < 20; run++ {
+		var buf bytes.Buffer
+		if err := renderHTMLDiffReport(&buf, diff); err != nil {
+			t.Fatal(err)
+		}
+		if run == 0 {
+			first = buf.String()
+			continue
+		}
+		if buf.String() != first {
+			t.Fatalf("run %d rendered a different report", run)
+		}
+	}
+	// Numbers come first, in numeric order.
+	keys := pageKeys(t, first)[0]["value_diff"]
+	if keys[0] != "1" || keys[1] != "2" || keys[19] != "20" {
+		t.Errorf("first shown keys: %v", keys)
+	}
+}
 
 func TestComparePKComponentIsATotalOrder(t *testing.T) {
 	vals := []string{"1", "1.0", "2", "9", "10", "1a", "10a", "9a", "", "NaN", "Inf", "-1", "abc", "a"}
@@ -37,3 +357,63 @@ func TestComparePKComponentIsATotalOrder(t *testing.T) {
 		}
 	}
 }
+
+type failingWriter struct{ left int }
+
+func (w *failingWriter) Write(p []byte) (int, error) {
+	if len(p) > w.left {
+		n := w.left
+		w.left = 0
+		return n, errors.New("disk full")
+	}
+	w.left -= len(p)
+	return len(p), nil
+}
+
+func TestRenderHTMLDiffReportWriteError(t *testing.T) {
+	// A small buffer makes every block reach the writer at once, so the
+	// failure lands where the test puts it.
+	orig := htmlWriteBufferSize
+	htmlWriteBufferSize = 16
+	t.Cleanup(func() { htmlWriteBufferSize = orig })
+
+	diff := htmlTestDiff(4, 2, 2, "x")
+	var full bytes.Buffer
+	if err := renderHTMLDiffReport(&full, diff); err != nil {
+		t.Fatal(err)
+	}
+	page := full.String()
+	rowsAt := strings.Index(page, `class="diff-row"`)
+	dataAt := strings.Index(page, `<script id="diff-data"`)
+	tailAt := strings.LastIndex(page, "<script>")
+	if rowsAt < 0 || dataAt < 0 || tailAt < 0 {
+		t.Fatal("could not find the parts of the page")
+	}
+	for name, at := range map[string]int{"head": 10, "rows": rowsAt + 10, "embedded data": dataAt + 60, "tail": tailAt + 10} {
+		err := renderHTMLDiffReport(&failingWriter{left: at}, diff)
+		if err == nil || !strings.Contains(err.Error(), "disk full") {
+			t.Errorf("write error in the %s (after %d bytes): got %v", name, at, err)
+		}
+	}
+}
+
+// writeHTMLDiffReport must not leave a file behind when it fails.
+func TestWriteHTMLDiffReportRemovesFileOnError(t *testing.T) {
+	dir := t.TempDir()
+	jsonPath := filepath.Join(dir, "r.json")
+	htmlPath := filepath.Join(dir, "r.html")
+	orig := htmlDiffTemplate
+	htmlDiffTemplate = `{{define "report_head"}}{{.NoSuchField}}{{end}}`
+	t.Cleanup(func() { htmlDiffTemplate = orig })
+
+	got, err := writeHTMLDiffReport(htmlTestDiff(1, 0, 0, "x"), jsonPath)
+	if err == nil {
+		t.Fatal("expected an error from a broken template")
+	}
+	if got != "" {
+		t.Errorf("returned path %q on error", got)
+	}
+	if _, statErr := os.Stat(htmlPath); !os.IsNotExist(statErr) {
+		t.Errorf("HTML file left behind after error (stat: %v)", statErr)
+	}
+}
diff --git a/pkg/common/templates/diff_report.html b/pkg/common/templates/diff_report.html
index 32bbef2..2065ff7 100644
--- a/pkg/common/templates/diff_report.html
+++ b/pkg/common/templates/diff_report.html
@@ -1,4 +1,11 @@
-<!DOCTYPE html>
+{{/*
+The report is written in parts, so that the writer can stream it to disk one
+row at a time instead of building the whole document in memory. Each block
+below is executed separately, in the order the blocks appear here. The
+embedded diff data (<script id="diff-data">) is written by the Go code after
+the last pair block and before "report_tail".
+*/}}
+{{define "report_head"}}<!DOCTYPE html>
 <html>
 <head>
     <meta charset="utf-8">
@@ -37,11 +44,16 @@ <h2>Summary</h2>
             </div>
             {{end}}
         </div>
+{{end}}
 
-        {{if .Pairs}}
-            {{range .Pairs}}
+{{define "no_pairs"}}
+            <div class="diff-section">
+                <div class="empty-message">No row-level differences were recorded.</div>
+            </div>
+{{end}}
+
+{{define "pair_head"}}
             <div class="diff-section" data-nodea="{{.NodeA}}" data-nodeb="{{.NodeB}}">
-                {{ $nodeA := .NodeA }}{{ $nodeB := .NodeB }}
                 <div class="diff-header">
                     <div class="pair-title">Differences between {{.NodeA}} and {{.NodeB}}</div>
                     <span class="diff-count-pill">{{.DiffCount}} entries</span>
@@ -56,29 +68,38 @@ <h2>Summary</h2>
                             </tr>
                         </thead>
                         <tbody>
-                        {{if .ValueDiffs}}
-                        <tr class="row-separator"><td colspan="100%">Value Differences</td></tr>
-                        {{range $i, $row := .ValueDiffs}}
-                            {{if $i}}<tr class="row-divider"><td colspan="100%"></td></tr>{{end}}
+{{end}}
+
+{{define "separator"}}
+                        <tr class="row-separator"><td colspan="100%">{{.}}</td></tr>
+{{end}}
+
+{{define "group_head"}}
+                            {{if .DividerBefore}}<tr class="row-divider"><td colspan="100%"></td></tr>{{end}}
+                            <tr class="row-subseparator"><td colspan="100%">{{.Title}}</td></tr>
+{{end}}
+
+{{define "value_row"}}
+                            {{if not .First}}<tr class="row-divider"><td colspan="100%"></td></tr>{{end}}
                             <tr class="diff-row">
                                 <td class="select-cell">
-                                    <input type="checkbox" class="row-select" data-pk="{{$row.PKey}}" data-type="{{$row.RowType}}" data-nodea="{{ $nodeA }}" data-nodeb="{{ $nodeB }}" aria-label="Select row {{$row.PKey}}">
+                                    <input type="checkbox" class="row-select" data-pk="{{.PKey}}" data-type="{{.RowType}}" data-nodea="{{ .NodeA }}" data-nodeb="{{ .NodeB }}" aria-label="Select row {{.PKey}}">
                                 </td>
                                 <td class="action-cell">
                                     <div class="action-wrapper">
                                         <span class="action-label">Row Action</span>
-                                        <select class="plan-action" data-type="mismatch" data-pk="{{$row.PKey}}" data-nodea="{{ $nodeA }}" data-nodeb="{{ $nodeB }}">
+                                        <select class="plan-action" data-type="mismatch" data-pk="{{.PKey}}" data-nodea="{{ .NodeA }}" data-nodeb="{{ .NodeB }}">
                                             <option value="">Use default (keep_n1)</option>
-                                            <option value="keep_n1">Keep {{$nodeA}}</option>
-                                            <option value="keep_n2">Keep {{$nodeB}}</option>
-                                            <option value="apply_from_n1_insert">Apply from {{$nodeA}} (insert if missing)</option>
-                                            <option value="apply_from_n2_insert">Apply from {{$nodeB}} (insert if missing)</option>
+                                            <option value="keep_n1">Keep {{.NodeA}}</option>
+                                            <option value="keep_n2">Keep {{.NodeB}}</option>
+                                            <option value="apply_from_n1_insert">Apply from {{.NodeA}} (insert if missing)</option>
+                                            <option value="apply_from_n2_insert">Apply from {{.NodeB}} (insert if missing)</option>
                                             <option value="delete">Delete</option>
                                             <option value="skip">Skip</option>
                                             <option value="custom">Custom...</option>
                                         </select>
-                                        <div class="row-key" title="Primary key">{{$row.PKey}}</div>
-                                        <div class="custom-editor" data-pk="{{$row.PKey}}" data-nodea="{{ $nodeA }}" data-nodeb="{{ $nodeB }}">
+                                        <div class="row-key" title="Primary key">{{.PKey}}</div>
+                                        <div class="custom-editor" data-pk="{{.PKey}}" data-nodea="{{ .NodeA }}" data-nodeb="{{ .NodeB }}">
                                             <div class="custom-editor-header">Custom action</div>
                                             <label class="custom-field">
                                                 <span>Custom row (JSON)</span>
@@ -89,8 +110,8 @@ <h2>Summary</h2>
                                                         <span>Coalesce priority</span>
                                                         <select class="helper-coalesce">
                                                             <option value="">None</option>
-                                                            <option value="{{$nodeA}},{{$nodeB}}">Prefer {{$nodeA}} then {{$nodeB}}</option>
-                                                            <option value="{{$nodeB}},{{$nodeA}}">Prefer {{$nodeB}} then {{$nodeA}}</option>
+                                                            <option value="{{.NodeA}},{{.NodeB}}">Prefer {{.NodeA}} then {{.NodeB}}</option>
+                                                            <option value="{{.NodeB}},{{.NodeA}}">Prefer {{.NodeB}} then {{.NodeA}}</option>
                                                         </select>
                                                     </label>
                                                     <div class="custom-field freshest-row">
@@ -101,8 +122,8 @@ <h2>Summary</h2>
                                                                 <span>Enable (commit_ts)</span>
                                                             </label>
                                                             <select class="helper-freshest-tie">
-                                                                <option value="{{$nodeA}}">Tie → {{$nodeA}}</option>
-                                                                <option value="{{$nodeB}}">Tie → {{$nodeB}}</option>
+                                                                <option value="{{.NodeA}}">Tie → {{.NodeA}}</option>
+                                                                <option value="{{.NodeB}}">Tie → {{.NodeB}}</option>
                                                             </select>
                                                         </div>
                                                     </div>
@@ -115,12 +136,12 @@ <h2>Summary</h2>
                                         <thead>
                                             <tr>
                                                 <th class="inner-col-header">Column</th>
-                                                <th class="inner-node-header">{{ $nodeA }}</th>
-                                                <th class="inner-node-header">{{ $nodeB }}</th>
+                                                <th class="inner-node-header">{{ .NodeA }}</th>
+                                                <th class="inner-node-header">{{ .NodeB }}</th>
                                             </tr>
                                         </thead>
                                         <tbody>
-                                            {{range $row.Cells}}
+                                            {{range .Cells}}
                                             <tr{{if .HasDiff}} class="has-diff"{{end}}>
                                                 <td class="col-name{{if .IsKey}} key-column{{end}}">{{.Column}}</td>
                                                 <td class="value-cell{{if .NodeAClass}} {{.NodeAClass}}{{end}}">{{.NodeAHTML}}</td>
@@ -131,33 +152,27 @@ <h2>Summary</h2>
                                     </table>
                                 </td>
                             </tr>
-                        {{end}}
-                        {{end}}
+{{end}}
 
-                        {{if .Missing}}
-                        <tr class="row-separator"><td colspan="100%">Missing Rows</td></tr>
-                        {{range $gIndex, $group := .Missing}}
-                            {{if $group.DividerBefore}}<tr class="row-divider"><td colspan="100%"></td></tr>{{end}}
-                            <tr class="row-subseparator"><td colspan="100%">{{$group.Title}}</td></tr>
-                            {{range $rIndex, $row := $group.Rows}}
-                                {{if $rIndex}}<tr class="row-divider"><td colspan="100%"></td></tr>{{end}}
+{{define "missing_row"}}
+                                {{if not .First}}<tr class="row-divider"><td colspan="100%"></td></tr>{{end}}
                                 <tr class="diff-row">
                                     <td class="select-cell">
-                                        <input type="checkbox" class="row-select" data-pk="{{$row.PKey}}" data-type="{{$row.RowType}}" data-nodea="{{ $nodeA }}" data-nodeb="{{ $nodeB }}" aria-label="Select row {{$row.PKey}}">
+                                        <input type="checkbox" class="row-select" data-pk="{{.PKey}}" data-type="{{.RowType}}" data-nodea="{{ .NodeA }}" data-nodeb="{{ .NodeB }}" aria-label="Select row {{.PKey}}">
                                     </td>
                                     <td class="action-cell">
                                         <div class="action-wrapper">
                                             <span class="action-label">Row Action</span>
-                                            <select class="plan-action" data-type="{{if eq $group.Title (print "Missing in " $nodeB)}}missing_in_b{{else}}missing_in_a{{end}}" data-pk="{{$row.PKey}}" data-nodea="{{ $nodeA }}" data-nodeb="{{ $nodeB }}">
+                                            <select class="plan-action" data-type="{{.RowType}}" data-pk="{{.PKey}}" data-nodea="{{ .NodeA }}" data-nodeb="{{ .NodeB }}">
                                                 <option value="">Use default</option>
-                                                <option value="apply_from_n1_insert">Insert from {{$nodeA}}</option>
-                                                <option value="apply_from_n2_insert">Insert from {{$nodeB}}</option>
+                                                <option value="apply_from_n1_insert">Insert from {{.NodeA}}</option>
+                                                <option value="apply_from_n2_insert">Insert from {{.NodeB}}</option>
                                                 <option value="delete">Delete</option>
                                                 <option value="skip">Skip</option>
                                                 <option value="custom">Custom...</option>
                                             </select>
-                                            <div class="row-key" title="Primary key">{{$row.PKey}}</div>
-                                            <div class="custom-editor" data-pk="{{$row.PKey}}" data-nodea="{{ $nodeA }}" data-nodeb="{{ $nodeB }}">
+                                            <div class="row-key" title="Primary key">{{.PKey}}</div>
+                                            <div class="custom-editor" data-pk="{{.PKey}}" data-nodea="{{ .NodeA }}" data-nodeb="{{ .NodeB }}">
                                                 <div class="custom-editor-header">Custom action</div>
                                                 <label class="custom-field">
                                                     <span>Custom row (JSON)</span>
@@ -168,8 +183,8 @@ <h2>Summary</h2>
                                                         <span>Coalesce priority</span>
                                                         <select class="helper-coalesce">
                                                             <option value="">None</option>
-                                                            <option value="{{$nodeA}},{{$nodeB}}">Prefer {{$nodeA}} then {{$nodeB}}</option>
-                                                            <option value="{{$nodeB}},{{$nodeA}}">Prefer {{$nodeB}} then {{$nodeA}}</option>
+                                                            <option value="{{.NodeA}},{{.NodeB}}">Prefer {{.NodeA}} then {{.NodeB}}</option>
+                                                            <option value="{{.NodeB}},{{.NodeA}}">Prefer {{.NodeB}} then {{.NodeA}}</option>
                                                         </select>
                                                     </label>
                                                     <div class="custom-field freshest-row">
@@ -180,8 +195,8 @@ <h2>Summary</h2>
                                                                 <span>Enable (commit_ts)</span>
                                                             </label>
                                                             <select class="helper-freshest-tie">
-                                                                <option value="{{$nodeA}}">Tie → {{$nodeA}}</option>
-                                                                <option value="{{$nodeB}}">Tie → {{$nodeB}}</option>
+                                                                <option value="{{.NodeA}}">Tie → {{.NodeA}}</option>
+                                                                <option value="{{.NodeB}}">Tie → {{.NodeB}}</option>
                                                             </select>
                                                         </div>
                                                     </div>
@@ -194,12 +209,12 @@ <h2>Summary</h2>
                                             <thead>
                                                 <tr>
                                                     <th class="inner-col-header">Column</th>
-                                                    <th class="inner-node-header">{{ $nodeA }}</th>
-                                                    <th class="inner-node-header">{{ $nodeB }}</th>
+                                                    <th class="inner-node-header">{{ .NodeA }}</th>
+                                                    <th class="inner-node-header">{{ .NodeB }}</th>
                                                 </tr>
                                             </thead>
                                             <tbody>
-                                                {{range $row.Cells}}
+                                                {{range .Cells}}
                                                 <tr>
                                                     <td class="col-name{{if .IsKey}} key-column{{end}}">{{.Column}}</td>
                                                     <td class="value-cell{{if .NodeAClass}} {{.NodeAClass}}{{end}}">{{.NodeAHTML}}</td>
@@ -210,10 +225,9 @@ <h2>Summary</h2>
                                         </table>
                                     </td>
                                 </tr>
-                            {{end}}
-                        {{end}}
-                        {{end}}
+{{end}}
 
+{{define "pair_tail"}}
                         {{if not .HasDiffs}}
                         <tr><td colspan="3" class="empty-message">No column level differences detected for this node pair.</td></tr>
                         {{end}}
@@ -221,14 +235,11 @@ <h2>Summary</h2>
                     </table>
                 </div>
             </div>
-            {{end}}
-        {{else}}
-            <div class="diff-section">
-                <div class="empty-message">No row-level differences were recorded.</div>
-            </div>
-        {{end}}
-        <script id="diff-data" type="application/json">{{ .RawDiffJSON }}</script>
+{{end}}
+
+{{define "report_tail"}}
         <script>{{.JS}}</script>
     </div>
 </body>
 </html>
+{{end}}
diff --git a/pkg/common/templates/diff_report.js b/pkg/common/templates/diff_report.js
index 29a2936..7a6feb9 100644
--- a/pkg/common/templates/diff_report.js
+++ b/pkg/common/templates/diff_report.js
@@ -232,12 +232,13 @@
         if (!pkCols.length) throw new Error('No primary key info available');
         const tableKey = diff.summary.schema + '.' + diff.summary.table;
 
+        const report = diff.html_report || {};
         const defaultAction = { type: 'keep_n1' };
         const targetKeys = selectionInfo?.usingSelection ? selectionInfo.selectedKeys : null;
         const usingSelection = !!selectionInfo?.usingSelection;
         const allSelected = usingSelection && selectionInfo.selectedCount === selectionInfo.totalRows && selectionInfo.totalRows > 0;
 
-        const rows = collectRows(diff, pkCols, targetKeys, defaultAction);
+        const rows = collectRows(diff, targetKeys, defaultAction);
 
         const grouped = groupRows(rows, pkCols);
         const rules = [];
@@ -245,7 +246,7 @@
 
         grouped.forEach(group => {
             const useRulesForGroup = allSelected || group.keys.length > 1;
-            const pkMatchers = buildPKMatchers(group.pkTuples, pkCols);
+            const pkMatchers = buildPKMatchers(group.pkTuples, pkCols, !!report.integer_pk);
 
             if (useRulesForGroup) {
                 if (!pkMatchers.length) return;
@@ -259,9 +260,8 @@
             }
 
             // Fallback to per-row override for singletons when not all rows are selected.
-            const pkMap = group.pkMaps[0];
             const name = 'pk_' + group.keys[0].replace(/\|/g, '_');
-            overrides.push({ name, pk: pkMap, action: group.action });
+            overrides.push({ name, pk: group.pkTuples[0], action: group.action });
         });
 
         const lines = [];
@@ -278,9 +278,9 @@
                     lines.push('        pk_in:');
                     for (const matcher of rule.pk_in) {
                         if (matcher.range) {
-                            lines.push('          - range: { from: ' + scalar(matcher.range.from) + ', to: ' + scalar(matcher.range.to) + ' }');
+                            lines.push('          - range: { from: ' + matcher.range.from + ', to: ' + matcher.range.to + ' }');
                         } else if (matcher.equals && matcher.equals.length) {
-                            lines.push('          - equals: ' + formatList(matcher.equals));
+                            lines.push('          - equals: ' + formatLiteralList(matcher.equals));
                         }
                     }
                 }
@@ -296,10 +296,9 @@
             for (const ov of overrides) {
                 lines.push('      - name: ' + quote(ov.name));
                 lines.push('        pk:');
-                for (const col of pkCols) {
-                    const v = ov.pk[col];
-                    lines.push('          ' + col + ': ' + scalar(v));
-                }
+                pkCols.forEach((col, i) => {
+                    lines.push('          ' + col + ': ' + ov.pk[i]);
+                });
                 lines.push('        action:');
                 emitActionYaml(lines, '          ', ov.action);
             }
@@ -307,50 +306,37 @@
         return lines.join('\n') + '\n';
     }
 
-    function collectRows(diff, pkCols, targetKeys, defaultAction) {
+    // collectRows turns the shown rows (diff.rows, written by the Go code)
+    // into plan entries. A row's pk is a list of JSON literals copied from the
+    // diff file; they go into the YAML as they are and are never turned into
+    // JavaScript numbers, which would lose digits of a bigint and turn a text
+    // key such as "007" into the number 7.
+    function collectRows(diff, targetKeys, defaultAction) {
         const rows = [];
-        const nodeDiffs = diff.NodeDiffs || diff.diffs || {};
         const seen = new Set();
 
-        for (const pairKey of Object.keys(nodeDiffs)) {
-            const nodeDiff = nodeDiffs[pairKey];
-            if (!nodeDiff || !nodeDiff.Rows && !nodeDiff.rows) continue;
-            const rowsMap = nodeDiff.Rows || nodeDiff.rows;
-            const nodeNames = Object.keys(rowsMap || {}).sort();
-            if (nodeNames.length < 2) continue;
-            const n1 = nodeNames[0];
-            const n2 = nodeNames[1];
-            const rows1 = rowsMap[n1] || [];
-            const rows2 = rowsMap[n2] || [];
-
-            const map1 = rowsToMap(rows1, pkCols);
-            const map2 = rowsToMap(rows2, pkCols);
-
-            const keys = new Set([...map1.keys(), ...map2.keys()]);
-            for (const key of keys) {
-                if (seen.has(key)) continue;
-                seen.add(key);
-                if (targetKeys && !targetKeys.has(key)) continue;
-
-                const row1 = map1.get(key);
-                const row2 = map2.get(key);
-                const pkMap = keyToPkMap(key, pkCols);
-                const pkTuple = pkCols.map(col => pkMap[col]);
-                const diffType = diffTypeForRow(row1, row2);
-
-                let action = selectionForKey(key) || defaultAction;
-                if (row1 && !row2) {
-                    action = selectionForKey(key) || { type: 'apply_from', from: n1, mode: 'insert' };
-                } else if (row2 && !row1) {
-                    action = selectionForKey(key) || { type: 'apply_from', from: n2, mode: 'insert' };
+        for (const r of (diff.rows || [])) {
+            const key = r.key;
+            if (seen.has(key)) continue;
+            seen.add(key);
+            if (targetKeys && !targetKeys.has(key)) continue;
+
+            let action = selectionForKey(key);
+            if (!action) {
+                if (r.type === 'missing_on_n2') {
+                    action = { type: 'apply_from', from: r.node_a, mode: 'insert' };
+                } else if (r.type === 'missing_on_n1') {
+                    action = { type: 'apply_from', from: r.node_b, mode: 'insert' };
+                } else {
+                    action = defaultAction;
                 }
+            }
 
-                // Skip emitting explicit instructions for rows that match the table default.
-                const matchesDefault = isSameAction(action, defaultAction) && diffType === 'row_mismatch';
-                if (matchesDefault) continue;
+            // Skip emitting explicit instructions for rows that match the table default.
+            const matchesDefault = isSameAction(action, defaultAction) && r.type === 'row_mismatch';
+            if (matchesDefault) continue;
 
-                rows.push({ key, pk: pkMap, pkTuple, action, diffType });
-            }
+            rows.push({ key, pkTuple: r.pk, action, diffType: r.type });
         }
 
         return rows;
@@ -362,67 +348,60 @@
             const sig = actionSignature(row.action) + '|' + (row.diffType || '') + '|' + pkCols.length;
             let group = groupsByKey.get(sig);
             if (!group) {
-                group = { action: row.action, diffType: row.diffType, pkTuples: [], pkMaps: [], keys: [] };
+                group = { action: row.action, diffType: row.diffType, pkTuples: [], keys: [] };
                 groupsByKey.set(sig, group);
             }
             group.pkTuples.push(row.pkTuple);
-            group.pkMaps.push(row.pk);
             group.keys.push(row.key);
         });
         return Array.from(groupsByKey.values());
     }
 
-    function buildPKMatchers(pkTuples, pkCols) {
+    // buildPKMatchers returns pk_in matchers whose values are JSON literals.
+    // Ranges are used only when the Go code says that every key of the diff
+    // is a whole number (integerPK): then a range over consecutive shown keys
+    // cannot match any key that is not shown. BigInt keeps bigint keys exact.
+    function buildPKMatchers(pkTuples, pkCols, integerPK) {
         if (!pkTuples.length) return [];
-        if (pkCols.length === 1) {
-            const values = pkTuples.map(t => t[0]);
-            const numeric = [];
-            const nonNumeric = [];
-            values.forEach(v => (isFiniteNumber(v) ? numeric : nonNumeric).push(v));
-
-            const matchers = [];
-            if (numeric.length) {
-                const uniq = Array.from(new Set(numeric)).sort((a, b) => a - b);
-                const singles = [];
-                let start = uniq[0];
-                let prev = uniq[0];
-                for (let i = 1; i <= uniq.length; i++) {
-                    const curr = uniq[i];
-                    const contiguous = curr !== undefined && curr === prev + 1;
-                    if (contiguous) {
-                        prev = curr;
-                        continue;
-                    }
-                    const span = prev - start + 1;
-                    if (span > 1) {
-                        matchers.push({ range: { from: start, to: prev } });
-                    } else {
-                        singles.push(start);
-                    }
-                    if (curr !== undefined) {
-                        start = curr;
-                        prev = curr;
-                    }
-                }
-                if (singles.length) matchers.push({ equals: singles });
+        if (pkCols.length !== 1) {
+            // Composite PKs: use equals tuples.
+            return [{ equals: pkTuples }];
+        }
+
+        const values = Array.from(new Set(pkTuples.map(t => t[0])));
+        if (!integerPK) {
+            return [{ equals: values }];
+        }
+
+        const nums = values.map(v => BigInt(v)).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+        const matchers = [];
+        const singles = [];
+        let start = nums[0];
+        let prev = nums[0];
+        for (let i = 1; i <= nums.length; i++) {
+            const curr = nums[i];
+            if (curr !== undefined && curr === prev + 1n) {
+                prev = curr;
+                continue;
+            }
+            if (prev > start) {
+                matchers.push({ range: { from: start.toString(), to: prev.toString() } });
+            } else {
+                singles.push(start.toString());
             }
-            if (nonNumeric.length) {
-                const uniq = Array.from(new Set(nonNumeric));
-                matchers.push({ equals: uniq });
+            if (curr !== undefined) {
+                start = curr;
+                prev = curr;
             }
-            return matchers;
         }
-
-        // Composite PKs: use equals tuples.
-        const equalsTuples = pkTuples.map(tuple => tuple);
-        return equalsTuples.length ? [{ equals: equalsTuples }] : [];
+        if (singles.length) matchers.push({ equals: singles });
+        return matchers;
     }
 
-    function diffTypeForRow(row1, row2) {
-        if (row1 && row2) return 'row_mismatch';
-        if (row1 && !row2) return 'missing_on_n2';
-        if (!row1 && row2) return 'missing_on_n1';
-        return '';
+    // formatLiteralList writes a flow list of values that are already YAML
+    // literals (JSON text), or lists of them.
+    function formatLiteralList(values) {
+        return '[' + values.map(v => Array.isArray(v) ? formatLiteralList(v) : v).join(', ') + ']';
     }
 
     function isSameAction(a, b) {
@@ -439,10 +418,6 @@
         return parts.join('|');
     }
 
-    function isFiniteNumber(v) {
-        return typeof v === 'number' && Number.isFinite(v);
-    }
-
     function formatList(values) {
         if (!Array.isArray(values)) return '[]';
         const rendered = values.map(v => Array.isArray(v) ? formatList(v) : scalar(v));
@@ -543,35 +518,6 @@
         return action;
     }
 
-    function rowsToMap(rows, pkCols) {
-        const m = new Map();
-        for (const r of rows) {
-            const keyParts = pkCols.map(c => stringify(r[c]));
-            const k = keyParts.join('|');
-            m.set(k, r);
-        }
-        return m;
-    }
-
-    function keyToPkMap(key, pkCols) {
-        const parts = key.split('|');
-        const pk = {};
-        pkCols.forEach((c, i) => pk[c] = parseMaybeNumber(parts[i]));
-        return pk;
-    }
-
-    function stringify(v) {
-        if (v === null || v === undefined) return '';
-        return '' + v;
-    }
-
-    function parseMaybeNumber(v) {
-        if (v === undefined || v === null) return v;
-        const n = Number(v);
-        if (!Number.isNaN(n) && v !== '') return n;
-        return v;
-    }
-
     function quote(s) {
         if (/^[A-Za-z0-9._-]+$/.test(s)) return s;
         return JSON.stringify(s);
diff --git a/pkg/common/utils.go b/pkg/common/utils.go
index a6be8c0..dfc270c 100644
--- a/pkg/common/utils.go
+++ b/pkg/common/utils.go
@@ -1567,7 +1567,8 @@ func WriteDiffReport(diffResult types.DiffOutput, schema, table, format string)
 	if strings.EqualFold(format, "html") {
 		htmlPath, err = writeHTMLDiffReport(diffResult, jsonFileName)
 		if err != nil {
-			return "", "", err
+			// The JSON report is complete; say where it is, so the run is not lost.
+			return jsonFileName, "", fmt.Errorf("%w (the JSON report %s was written)", err, jsonFileName)
 		}
 		if htmlPath != "" {
 			logger.Info("HTML diff report written to %s", htmlPath)

From 2c3a74a33f634d0d9f7b6604b906fa1651aec06f Mon Sep 17 00:00:00 2001
From: Andrei Lepikhov <lepihov@gmail.com>
Date: Thu, 24 Sep 2026 15:51:37 +0200
Subject: [PATCH 3/7] Show at most max_html_rows rows per node pair in the HTML
 report

Streaming keeps table-diff alive, but a report of hundreds of thousands
of rows is still gigabytes of markup that no browser can open. The HTML
report now shows at most DefaultMaxHTMLRows (10,000) rows for each node
pair. A row is one primary key: a value difference or a row missing on
one node. Rows are taken in report order: value differences, then rows
missing on the second node, then rows missing on the first. The JSON
report does not change and always has every row.

A truncated report says so: a banner at the top, a summary item, the
count in the section header ("25 of 53 rows shown"), a note under the
section toolbar with the hidden rows by kind, and a last table row. In a
truncated section the bulk controls say "all 25 shown rows", and they
come after the notes.

The repair plan needs care here. table-repair applies the plan's
default_action to every row of the diff file that no rule matches, and
that includes the rows the page did not show. With the old default
keep_n1, a hidden row missing on n1 made table-repair reject the whole
plan, and hidden value differences silently got keep_n1. So a plan built
on a truncated page now has default_action: skip and an explicit rule
for every shown row, and the YAML starts with a comment that says so and
how to cover all rows. A complete report gives the same plan as before.

Known limit: plan rules match by key and kind of difference, not by node
pair. With three or more nodes, a rule for a key shown in one pair also
acts on that key where it is hidden in another pair.

Every count in a section now comes from the rows the report renders. If
table-diff counted rows that show no visible difference (1 against
"1"), a note says how many. The row action default is labelled with the
action it takes, for example "Default: insert from n1".

WriteDiffReport takes the limit as a new argument. Callers pass 0 (the
default) until the next commit adds the setting.

Tests: truncation in value differences and in missing rows, the counts,
the plan data of a truncated page, and a Node.js test that a plan from a
truncated report resolves and changes only the shown rows.
---
 internal/consistency/diff/table_diff.go       |   2 +-
 internal/consistency/mtree/merkle.go          |   2 +-
 .../consistency/repair/html_plan_e2e_test.go  |  44 +++-
 pkg/common/html_reporter.go                   | 219 ++++++++++++++----
 pkg/common/html_reporter_test.go              | 183 +++++++++++++--
 pkg/common/secure_file_test.go                |   2 +-
 pkg/common/templates/diff_report.css          |  46 ++++
 pkg/common/templates/diff_report.html         |  24 +-
 pkg/common/templates/diff_report.js           |  63 ++++-
 pkg/common/utils.go                           |   8 +-
 pkg/common/utils_test.go                      |   4 +-
 11 files changed, 509 insertions(+), 88 deletions(-)

diff --git a/internal/consistency/diff/table_diff.go b/internal/consistency/diff/table_diff.go
index e35e2ea..268edb7 100644
--- a/internal/consistency/diff/table_diff.go
+++ b/internal/consistency/diff/table_diff.go
@@ -1641,7 +1641,7 @@ func (t *TableDiffTask) ExecuteTask() (err error) {
 
 	t.AddPrimaryKeyToDiffSummary()
 
-	jsonPath, _, err := utils.WriteDiffReport(t.DiffResult, t.Schema, t.BaseTable, t.Output)
+	jsonPath, _, err := utils.WriteDiffReport(t.DiffResult, t.Schema, t.BaseTable, t.Output, 0)
 	if err != nil {
 		return err
 	}
diff --git a/internal/consistency/mtree/merkle.go b/internal/consistency/mtree/merkle.go
index eb2f5ed..17a69dd 100644
--- a/internal/consistency/mtree/merkle.go
+++ b/internal/consistency/mtree/merkle.go
@@ -2615,7 +2615,7 @@ func (m *MerkleTreeTask) DiffMtree() (err error) {
 			logger.Warn("mtree table-diff stopped after reaching max_diff_rows=%d; additional differences may exist", m.MaxDiffRows)
 		}
 
-		diffPath, _, writeErr := utils.WriteDiffReport(m.DiffResult, m.Schema, m.Table, m.Output)
+		diffPath, _, writeErr := utils.WriteDiffReport(m.DiffResult, m.Schema, m.Table, m.Output, 0)
 		if writeErr != nil {
 			return writeErr
 		}
diff --git a/internal/consistency/repair/html_plan_e2e_test.go b/internal/consistency/repair/html_plan_e2e_test.go
index 974776d..5a29051 100644
--- a/internal/consistency/repair/html_plan_e2e_test.go
+++ b/internal/consistency/repair/html_plan_e2e_test.go
@@ -57,10 +57,10 @@ func e2eRow(id any, v string) types.OrderedMap {
 	return types.OrderedMap{{Key: "id", Value: id}, {Key: "v", Value: v}}
 }
 
-// runHTMLPlan writes the reports for diff, builds the plan on the page, and
-// resolves it. It returns the upserted primary keys per
+// runHTMLPlan writes the reports for diff with the given limit, builds the
+// plan on the page, and resolves it. It returns the upserted primary keys per
 // node, the plan, and the resolver error.
-func runHTMLPlan(t *testing.T, diff types.DiffOutput) (map[string][]string, string, error) {
+func runHTMLPlan(t *testing.T, diff types.DiffOutput, limit int64) (map[string][]string, string, error) {
 	t.Helper()
 	node, err := exec.LookPath("node")
 	if err != nil {
@@ -69,7 +69,7 @@ func runHTMLPlan(t *testing.T, diff types.DiffOutput) (map[string][]string, stri
 	dir := t.TempDir()
 	t.Chdir(dir) // WriteDiffReport writes into the current directory
 
-	jsonPath, htmlPath, err := utils.WriteDiffReport(diff, "public", "t", "html")
+	jsonPath, htmlPath, err := utils.WriteDiffReport(diff, "public", "t", "html", limit)
 	if err != nil {
 		t.Fatalf("WriteDiffReport: %v", err)
 	}
@@ -114,6 +114,15 @@ func runHTMLPlan(t *testing.T, diff types.DiffOutput) (map[string][]string, stri
 	return got, string(planText), err
 }
 
+func idRange(from, to int) []string {
+	var out []string
+	for i := from; i <= to; i++ {
+		out = append(out, fmt.Sprint(i))
+	}
+	sort.Strings(out)
+	return out
+}
+
 // twoNodeDiff: 30 value differences (1..30), 15 rows missing on n2
 // (31..45), 8 rows missing on n1 (46..53).
 func twoNodeDiff() types.DiffOutput {
@@ -135,18 +144,31 @@ func twoNodeDiff() types.DiffOutput {
 	}
 }
 
-// Every row is on the page, so the plan covers every row: the default
-// keep_n1 for value differences, and explicit inserts for missing rows.
+// Before the fix, the hidden rows missing on n1 got keep_n1 and the whole
+// plan was rejected.
+func TestHTMLPlanTruncatedTwoNodes(t *testing.T) {
+	got, plan, err := runHTMLPlan(t, twoNodeDiff(), 25)
+	if err != nil {
+		t.Fatalf("plan from a truncated report does not resolve: %v\n%s", err, plan)
+	}
+	if want := idRange(1, 25); fmt.Sprint(got["n2"]) != fmt.Sprint(want) || len(got["n1"]) != 0 {
+		t.Errorf("upserts: got %v, want n2=%v and nothing on n1\n%s", got, want, plan)
+	}
+	if !strings.Contains(plan, "type: skip") || !strings.Contains(plan, "# WARNING") {
+		t.Errorf("plan has no skip default or no warning:\n%s", plan)
+	}
+}
+
 func TestHTMLPlanCompleteReport(t *testing.T) {
-	got, plan, err := runHTMLPlan(t, twoNodeDiff())
+	got, plan, err := runHTMLPlan(t, twoNodeDiff(), 0)
 	if err != nil {
 		t.Fatalf("plan does not resolve: %v\n%s", err, plan)
 	}
 	if len(got["n2"]) != 45 || len(got["n1"]) != 8 {
 		t.Errorf("upserts: got n1=%d n2=%d, want n1=8 n2=45", len(got["n1"]), len(got["n2"]))
 	}
-	if !strings.Contains(plan, "type: keep_n1") {
-		t.Errorf("plan has no keep_n1 default:\n%s", plan)
+	if strings.Contains(plan, "# WARNING") || !strings.Contains(plan, "type: keep_n1") {
+		t.Errorf("complete report must give the old plan:\n%s", plan)
 	}
 }
 
@@ -161,7 +183,7 @@ func TestHTMLPlanBigintKeys(t *testing.T) {
 		Summary: types.DiffSummary{Schema: "public", Table: "t", PrimaryKey: []string{"id"},
 			DiffRowsCount: map[string]int{"n1/n2": 3}},
 	}
-	got, plan, err := runHTMLPlan(t, diff)
+	got, plan, err := runHTMLPlan(t, diff, 0)
 	if err != nil {
 		t.Fatalf("plan does not resolve: %v\n%s", err, plan)
 	}
@@ -187,7 +209,7 @@ func TestHTMLPlanTextKeysThatLookNumeric(t *testing.T) {
 		Summary: types.DiffSummary{Schema: "public", Table: "t", PrimaryKey: []string{"id"},
 			DiffRowsCount: map[string]int{"n1/n2": 3}},
 	}
-	got, plan, err := runHTMLPlan(t, diff)
+	got, plan, err := runHTMLPlan(t, diff, 0)
 	if err != nil {
 		t.Fatalf("plan does not resolve: %v\n%s", err, plan)
 	}
diff --git a/pkg/common/html_reporter.go b/pkg/common/html_reporter.go
index 6e515ac..07223d5 100644
--- a/pkg/common/html_reporter.go
+++ b/pkg/common/html_reporter.go
@@ -27,6 +27,7 @@ import (
 	"strings"
 	"time"
 
+	"github.com/pgedge/ace/pkg/logger"
 	"github.com/pgedge/ace/pkg/types"
 )
 
@@ -39,6 +40,13 @@ var htmlDiffCSS string
 //go:embed templates/diff_report.js
 var htmlDiffJS string
 
+// DefaultMaxHTMLRows is how many rows the HTML report shows for each node pair
+// when neither the command line nor the config file sets max_html_rows. A row
+// here is one primary key, whether it differs in value or is missing on one
+// node. One row takes several kilobytes of markup, so without a limit a large
+// diff gives a file of gigabytes that no browser can open.
+const DefaultMaxHTMLRows int64 = 10000
+
 // htmlWriteBufferSize is the size of the buffer in front of the report file.
 // It is a variable only so that tests can make every write reach the writer.
 var htmlWriteBufferSize = 256 * 1024
@@ -59,9 +67,19 @@ type htmlSummaryData struct {
 	Breakdown []htmlPairCount
 }
 
+// htmlTruncation is shown at the top of a report that does not show every
+// row of the diff.
+type htmlTruncation struct {
+	Shown    string
+	Total    string
+	Limit    string
+	DiffFile string
+}
+
 type htmlReportHead struct {
-	CSS     template.CSS
-	Summary htmlSummaryData
+	CSS        template.CSS
+	Truncation *htmlTruncation
+	Summary    htmlSummaryData
 }
 
 type htmlReportTail struct {
@@ -69,11 +87,20 @@ type htmlReportTail struct {
 }
 
 // htmlPairHead is the data for the "pair_head" and "pair_tail" blocks.
+// Hidden is empty when the section shows every row of the pair. NotRendered
+// is empty unless table-diff counted rows that the report leaves out because
+// they show no difference (see buildHTMLPairPlan).
 type htmlPairHead struct {
-	NodeA     string
-	NodeB     string
-	DiffCount string
-	HasDiffs  bool
+	NodeA           string
+	NodeB           string
+	DiffCount       string
+	Shown           string
+	Total           string
+	Hidden          string
+	HiddenBreakdown string
+	NotRendered     string
+	DiffFile        string
+	HasDiffs        bool
 }
 
 type htmlGroupHead struct {
@@ -102,14 +129,19 @@ type htmlRow struct {
 	NodeAJSON string
 }
 
-// htmlReportInfo goes into the embedded diff data, next to the list of rows
-// (see writeHTMLDiffData).
+// htmlReportInfo goes into the embedded diff data, so that the page script
+// knows when the repair plan it builds covers only part of the diff. The
+// list of rows follows it in the page (see writeHTMLDiffData).
 type htmlReportInfo struct {
-	IntegerPK bool `json:"integer_pk"`
+	Truncated bool           `json:"truncated"`
+	MaxRows   int64          `json:"max_html_rows"`
+	DiffFile  string         `json:"diff_file"`
+	IntegerPK bool           `json:"integer_pk"`
+	Pairs     []htmlPairInfo `json:"pairs"`
 }
 
 // htmlPlanRow is what the page script needs to write a repair-plan rule for
-// one row of the report. Key is the display key, as in data-pk. Type uses the names
+// one shown row. Key is the display key, as in data-pk. Type uses the names
 // of the repair executor. PK holds each primary key value as the JSON text
 // that the diff file has for it. The script copies that text into the YAML
 // as it is and never turns it into a JavaScript number, so a bigint keeps
@@ -123,6 +155,12 @@ type htmlPlanRow struct {
 	PK    []string `json:"pk"`
 }
 
+type htmlPairInfo struct {
+	Pair  string `json:"pair"`
+	Shown int    `json:"shown"`
+	Total int    `json:"total"`
+}
+
 // htmlPairPlan lists the report rows of one node pair, in report order:
 // value differences, then rows missing on node B, then rows missing on node A.
 // It holds only row keys. The row data stays in the diff result, and the
@@ -138,12 +176,59 @@ type htmlPairPlan struct {
 	valueKeys  []string
 	missingInB []string
 	missingInA []string
+
+	// How many rows of each list the report shows.
+	shownValue    int
+	shownMissingB int
+	shownMissingA int
 }
 
 func (p *htmlPairPlan) total() int {
 	return len(p.valueKeys) + len(p.missingInB) + len(p.missingInA)
 }
 
+func (p *htmlPairPlan) shown() int {
+	return p.shownValue + p.shownMissingB + p.shownMissingA
+}
+
+// applyLimit shows at most limit rows of the pair and takes them in report
+// order. So when value differences alone reach the limit, no missing rows
+// are shown; the section note and footer then give the count of each kind.
+func (p *htmlPairPlan) applyLimit(limit int64) {
+	remaining := limit
+	take := func(n int) int {
+		if int64(n) > remaining {
+			n = int(remaining)
+		}
+		remaining -= int64(n)
+		return n
+	}
+	p.shownValue = take(len(p.valueKeys))
+	p.shownMissingB = take(len(p.missingInB))
+	p.shownMissingA = take(len(p.missingInA))
+}
+
+// hiddenBreakdown describes the rows that the report does not show, for
+// example "400,000 value differences, 50,000 missing in n3".
+func (p *htmlPairPlan) hiddenBreakdown() string {
+	var parts []string
+	add := func(one, many string, all, shown int) {
+		hidden := all - shown
+		if hidden <= 0 {
+			return
+		}
+		label := many
+		if hidden == 1 {
+			label = one
+		}
+		parts = append(parts, formatInt64WithCommas(int64(hidden))+" "+label)
+	}
+	add("value difference", "value differences", len(p.valueKeys), p.shownValue)
+	add("missing in "+p.nodeB, "missing in "+p.nodeB, len(p.missingInB), p.shownMissingB)
+	add("missing in "+p.nodeA, "missing in "+p.nodeA, len(p.missingInA), p.shownMissingA)
+	return strings.Join(parts, ", ")
+}
+
 // planType is the repair executor's name for the kind of difference of a row
 // in this pair: row_mismatch, missing_on_n2 or missing_on_n1, where n1 and n2
 // are node A and node B of the pair.
@@ -172,8 +257,8 @@ var integerLiteralRe = regexp.MustCompile(`^-?[0-9]+$`)
 
 // htmlIntegerPK tells whether the primary key is a single column and every
 // row of the diff, in every pair, has a whole number in it. Only then can the
-// page script write a range rule: a range over the keys 1 and 2 would also
-// match a key 1.5 that has a rule of its own.
+// page script write a range rule: a range over the shown keys 1 and 2 would
+// also match a key 1.5 that the page did not show.
 func htmlIntegerPK(plans []*htmlPairPlan, primaryKey []string) bool {
 	if len(primaryKey) != 1 {
 		return false
@@ -197,7 +282,8 @@ func htmlIntegerPK(plans []*htmlPairPlan, primaryKey []string) bool {
 // buildHTMLPairPlan pairs the rows of the two nodes and sorts them. A row
 // that exists on both nodes but shows no difference after stringifyCellValue
 // (for example 1 against "1", or a difference only in _spock_metadata_) is
-// left out, as before. It returns nil when the pair has no rows to show.
+// left out, as before; writeHTMLPair reports how many. It returns nil when
+// the pair has no rows to show.
 func buildHTMLPairPlan(pairKey string, nodeDiff types.DiffByNodePair, primaryKey []string) *htmlPairPlan {
 	nodeNames := strings.Split(pairKey, "/")
 	if len(nodeNames) != 2 {
@@ -338,13 +424,19 @@ func (p *htmlPairPlan) missingRow(key string, missingInB bool, pkSet map[string]
 	return row
 }
 
-func buildHTMLSummaryItems(summary types.DiffSummary) []htmlSummaryItem {
+func buildHTMLSummaryItems(summary types.DiffSummary, shown, total int, truncated bool) []htmlSummaryItem {
 	items := []htmlSummaryItem{
 		{Label: "Table", Value: fmt.Sprintf("%s.%s", summary.Schema, summary.Table)},
 		{Label: "Nodes", Value: strings.Join(summary.Nodes, ", ")},
 		{Label: "Primary Key", Value: formatPrimaryKey(summary.PrimaryKey)},
 		{Label: "Total Differences", Value: formatInt64WithCommas(totalDiffs(summary.DiffRowsCount))},
 	}
+	if truncated {
+		items = append(items, htmlSummaryItem{
+			Label: "Rows Shown in Report",
+			Value: formatInt64WithCommas(int64(shown)) + " of " + formatInt64WithCommas(int64(total)),
+		})
+	}
 	items = append(items,
 		htmlSummaryItem{Label: "Total Rows Checked", Value: formatInt64WithCommas(summary.TotalRowsChecked)},
 		htmlSummaryItem{Label: "Initial Ranges", Value: formatInt64WithCommas(int64(summary.InitialRangesCount))},
@@ -389,8 +481,10 @@ func buildHTMLSummaryItems(summary types.DiffSummary) []htmlSummaryItem {
 	return filtered
 }
 
-// writeHTMLDiffReport writes the HTML report next to the JSON report.
-func writeHTMLDiffReport(diffResult types.DiffOutput, jsonFilePath string) (htmlPath string, err error) {
+// writeHTMLDiffReport writes the HTML report next to the JSON report. It shows
+// at most maxRows rows for each node pair; a value <= 0 means
+// DefaultMaxHTMLRows.
+func writeHTMLDiffReport(diffResult types.DiffOutput, jsonFilePath string, maxRows int64) (htmlPath string, err error) {
 	if jsonFilePath == "" {
 		return "", nil
 	}
@@ -411,7 +505,7 @@ func writeHTMLDiffReport(diffResult types.DiffOutput, jsonFilePath string) (html
 		}
 	}()
 
-	if err = renderHTMLDiffReport(f, diffResult); err != nil {
+	if err = renderHTMLDiffReport(f, diffResult, filepath.Base(jsonFilePath), maxRows); err != nil {
 		return "", err
 	}
 	if err = f.Close(); err != nil {
@@ -420,13 +514,18 @@ func writeHTMLDiffReport(diffResult types.DiffOutput, jsonFilePath string) (html
 	return path, nil
 }
 
-// renderHTMLDiffReport writes the report to out.
+// renderHTMLDiffReport writes the report to out. diffFile is the name of the
+// JSON report, which the page refers to for the full diff.
 //
 // The report goes out block by block through a buffered writer. Only the row
 // keys of the whole diff are held in memory, never the markup: at several
 // kilobytes of markup per row, a document built in memory for a diff of half a
 // million rows needs gigabytes.
-func renderHTMLDiffReport(out io.Writer, diffResult types.DiffOutput) error {
+func renderHTMLDiffReport(out io.Writer, diffResult types.DiffOutput, diffFile string, maxRows int64) error {
+	if maxRows <= 0 {
+		maxRows = DefaultMaxHTMLRows
+	}
+
 	tmpl, err := template.New("tableDiffReport").Parse(htmlDiffTemplate)
 	if err != nil {
 		return fmt.Errorf("failed to parse HTML template: %w", err)
@@ -444,20 +543,39 @@ func renderHTMLDiffReport(out io.Writer, diffResult types.DiffOutput) error {
 	}
 	sort.Strings(pairKeys)
 
+	// The page header says whether the report is truncated, so every pair
+	// must be counted before the first byte is written.
 	var plans []*htmlPairPlan
+	var shownAll, totalAll int
 	for _, pairKey := range pairKeys {
-		if p := buildHTMLPairPlan(pairKey, diffResult.NodeDiffs[pairKey], summary.PrimaryKey); p != nil {
-			plans = append(plans, p)
+		p := buildHTMLPairPlan(pairKey, diffResult.NodeDiffs[pairKey], summary.PrimaryKey)
+		if p == nil {
+			continue
 		}
+		p.applyLimit(maxRows)
+		shownAll += p.shown()
+		totalAll += p.total()
+		plans = append(plans, p)
 	}
+	truncated := shownAll < totalAll
 
 	head := htmlReportHead{
 		CSS: template.CSS(htmlDiffCSS),
 		Summary: htmlSummaryData{
-			Items:     buildHTMLSummaryItems(summary),
+			Items:     buildHTMLSummaryItems(summary, shownAll, totalAll, truncated),
 			Breakdown: buildDiffBreakdown(summary.DiffRowsCount),
 		},
 	}
+	if truncated {
+		head.Truncation = &htmlTruncation{
+			Shown:    formatInt64WithCommas(int64(shownAll)),
+			Total:    formatInt64WithCommas(int64(totalAll)),
+			Limit:    formatInt64WithCommas(maxRows),
+			DiffFile: diffFile,
+		}
+		logger.Warn("HTML report shows %d of %d rows (max_html_rows=%d per node pair); the full diff is in %s",
+			shownAll, totalAll, maxRows, diffFile)
+	}
 
 	w := bufio.NewWriterSize(out, htmlWriteBufferSize)
 	if err := tmpl.ExecuteTemplate(w, "report_head", head); err != nil {
@@ -469,12 +587,21 @@ func renderHTMLDiffReport(out io.Writer, diffResult types.DiffOutput) error {
 		}
 	}
 	for _, p := range plans {
-		if err := writeHTMLPair(tmpl, w, p, summary, pkSet); err != nil {
+		if err := writeHTMLPair(tmpl, w, p, summary, pkSet, diffFile); err != nil {
 			return fmt.Errorf("failed to render HTML diff report: %w", err)
 		}
 	}
 
-	info := htmlReportInfo{IntegerPK: htmlIntegerPK(plans, summary.PrimaryKey)}
+	info := htmlReportInfo{
+		Truncated: truncated,
+		MaxRows:   maxRows,
+		DiffFile:  diffFile,
+		IntegerPK: htmlIntegerPK(plans, summary.PrimaryKey),
+		Pairs:     make([]htmlPairInfo, 0, len(plans)),
+	}
+	for _, p := range plans {
+		info.Pairs = append(info.Pairs, htmlPairInfo{Pair: p.pairKey, Shown: p.shown(), Total: p.total()})
+	}
 	if err := writeHTMLDiffData(w, summary, plans, info, summary.PrimaryKey); err != nil {
 		return fmt.Errorf("failed to embed diff data in HTML report: %w", err)
 	}
@@ -489,23 +616,37 @@ func renderHTMLDiffReport(out io.Writer, diffResult types.DiffOutput) error {
 }
 
 // writeHTMLPair writes the section of one node pair, one row at a time.
-func writeHTMLPair(tmpl *template.Template, w io.Writer, p *htmlPairPlan, summary types.DiffSummary, pkSet map[string]struct{}) error {
+func writeHTMLPair(tmpl *template.Template, w io.Writer, p *htmlPairPlan, summary types.DiffSummary, pkSet map[string]struct{}, diffFile string) error {
+	// Every count in the section comes from the plan, so the numbers on the
+	// page always add up. The engine's own count can be higher; the note
+	// below says why.
+	counted := summary.DiffRowsCount[p.pairKey]
 	head := htmlPairHead{
 		NodeA:     p.nodeA,
 		NodeB:     p.nodeB,
-		DiffCount: formatInt64WithCommas(int64(summary.DiffRowsCount[p.pairKey])),
+		DiffCount: formatInt64WithCommas(int64(counted)),
+		Total:     formatInt64WithCommas(int64(p.total())),
+		DiffFile:  diffFile,
 		HasDiffs:  p.total() > 0,
 	}
+	if hidden := p.total() - p.shown(); hidden > 0 {
+		head.Shown = formatInt64WithCommas(int64(p.shown()))
+		head.Hidden = formatInt64WithCommas(int64(hidden))
+		head.HiddenBreakdown = p.hiddenBreakdown()
+	}
+	if notRendered := counted - p.total(); notRendered > 0 {
+		head.NotRendered = formatInt64WithCommas(int64(notRendered))
+	}
 
 	if err := tmpl.ExecuteTemplate(w, "pair_head", head); err != nil {
 		return err
 	}
 
-	if len(p.valueKeys) > 0 {
+	if p.shownValue > 0 {
 		if err := tmpl.ExecuteTemplate(w, "separator", "Value Differences"); err != nil {
 			return err
 		}
-		for i, key := range p.valueKeys {
+		for i, key := range p.valueKeys[:p.shownValue] {
 			row := p.valueRow(key, pkSet)
 			row.First = i == 0
 			if err := tmpl.ExecuteTemplate(w, "value_row", row); err != nil {
@@ -514,7 +655,7 @@ func writeHTMLPair(tmpl *template.Template, w io.Writer, p *htmlPairPlan, summar
 		}
 	}
 
-	if len(p.missingInB) > 0 || len(p.missingInA) > 0 {
+	if p.shownMissingB > 0 || p.shownMissingA > 0 {
 		if err := tmpl.ExecuteTemplate(w, "separator", "Missing Rows"); err != nil {
 			return err
 		}
@@ -523,8 +664,8 @@ func writeHTMLPair(tmpl *template.Template, w io.Writer, p *htmlPairPlan, summar
 			missingInB bool
 			title      string
 		}{
-			{p.missingInB, true, "Missing in " + p.nodeB},
-			{p.missingInA, false, "Missing in " + p.nodeA},
+			{p.missingInB[:p.shownMissingB], true, "Missing in " + p.nodeB},
+			{p.missingInA[:p.shownMissingA], false, "Missing in " + p.nodeA},
 		}
 		groupWritten := false
 		for _, g := range groups {
@@ -550,7 +691,7 @@ func writeHTMLPair(tmpl *template.Template, w io.Writer, p *htmlPairPlan, summar
 
 // writeHTMLDiffData embeds the data that the page script needs to build a
 // repair plan: the diff summary, htmlReportInfo, and one htmlPlanRow for each
-// row of the report, in report order. The rows are written one at a time, so the
+// shown row, in report order. The rows are written one at a time, so the
 // list never exists in memory as a whole.
 //
 // json.Marshal escapes '<', '>' and '&', so no value can close the script
@@ -581,9 +722,9 @@ func writeHTMLDiffData(w *bufio.Writer, summary types.DiffSummary, plans []*html
 			rows     map[string]types.OrderedMap
 			planType string
 		}{
-			{p.valueKeys, p.rowMapA, planTypeMismatch},
-			{p.missingInB, p.rowMapA, planTypeMissingN2},
-			{p.missingInA, p.rowMapB, planTypeMissingN1},
+			{p.valueKeys[:p.shownValue], p.rowMapA, planTypeMismatch},
+			{p.missingInB[:p.shownMissingB], p.rowMapA, planTypeMissingN2},
+			{p.missingInA[:p.shownMissingA], p.rowMapB, planTypeMissingN1},
 		}
 		for _, l := range lists {
 			for _, key := range l.keys {
@@ -968,10 +1109,10 @@ func comparePKKey(a, b string) int {
 }
 
 // comparePKComponent orders numbers by value and before all other strings,
-// and other strings byte-wise. The order must be total. The keys come from
-// map iteration, and with an order that is not transitive (as when a number
-// and a string compared as strings, so that "1a" < "9" < "10" but
-// "10" < "1a") sort.Slice put the rows in a different order on each run.
+// and other strings byte-wise. The order must be total: the HTML report shows
+// a prefix of the sorted rows, and with an order that is not transitive (as
+// when a number and a string compared as strings, so that "1a" < "9" < "10"
+// but "10" < "1a") the prefix changed from one run to the next.
 func comparePKComponent(a, b string) int {
 	numA, okA := parseNumeric(a)
 	numB, okB := parseNumeric(b)
diff --git a/pkg/common/html_reporter_test.go b/pkg/common/html_reporter_test.go
index ea0d83c..33ca3c1 100644
--- a/pkg/common/html_reporter_test.go
+++ b/pkg/common/html_reporter_test.go
@@ -86,10 +86,10 @@ var diffDataRe = regexp.MustCompile(`(?s)<script id="diff-data" type="applicatio
 
 // renderHTMLTestReport writes the report and returns the page and the parsed
 // embedded diff data.
-func renderHTMLTestReport(t *testing.T, diff types.DiffOutput) (string, htmlTestData) {
+func renderHTMLTestReport(t *testing.T, diff types.DiffOutput, maxRows int64) (string, htmlTestData) {
 	t.Helper()
 	jsonPath := filepath.Join(t.TempDir(), "public_t_diffs-20260101000000.json")
-	htmlPath, err := writeHTMLDiffReport(diff, jsonPath)
+	htmlPath, err := writeHTMLDiffReport(diff, jsonPath, maxRows)
 	if err != nil {
 		t.Fatalf("writeHTMLDiffReport: %v", err)
 	}
@@ -120,11 +120,18 @@ func countRows(page, rowType string) int {
 	return len(re.FindAllStringIndex(page, -1))
 }
 
-func TestHTMLReportRowsAndData(t *testing.T) {
-	page, data := renderHTMLTestReport(t, htmlTestDiff(4, 2, 1, "x"))
+func TestHTMLReportNotTruncated(t *testing.T) {
+	page, data := renderHTMLTestReport(t, htmlTestDiff(4, 2, 1, "x"), 0)
 
-	if !strings.Contains(page, ">7 entries<") {
-		t.Error("section pill does not show the entry count")
+	// Look for the elements, not the bare class names: the embedded CSS
+	// always has those.
+	for _, marker := range []string{`class="truncation-banner"`, `class="truncation-note"`, `class="truncation-row"`, "Rows Shown in Report"} {
+		if strings.Contains(page, marker) {
+			t.Errorf("report that shows every entry contains %q", marker)
+		}
+	}
+	if !strings.Contains(page, ">7 rows<") {
+		t.Error("section pill does not show the plain row count")
 	}
 	if got := countRows(page, "value_diff"); got != 4 {
 		t.Errorf("value rows: got %d, want 4", got)
@@ -136,6 +143,12 @@ func TestHTMLReportRowsAndData(t *testing.T) {
 		t.Errorf("missing_in_a rows: got %d, want 1", got)
 	}
 
+	if data.HTMLReport.Truncated {
+		t.Error("html_report.truncated is true for a complete report")
+	}
+	if data.HTMLReport.MaxRows != DefaultMaxHTMLRows {
+		t.Errorf("max_html_rows: got %d, want the default %d", data.HTMLReport.MaxRows, DefaultMaxHTMLRows)
+	}
 	want := map[string]int{"row_mismatch": 4, "missing_on_n2": 2, "missing_on_n1": 1}
 	if got := data.typeCounts("n1/n2"); fmt.Sprint(got) != fmt.Sprint(want) {
 		t.Errorf("embedded rows: got %v, want %v", got, want)
@@ -145,6 +158,87 @@ func TestHTMLReportRowsAndData(t *testing.T) {
 	}
 }
 
+// The limit takes entries in report order: value differences first, then
+// rows missing on n2, then rows missing on n1.
+func TestHTMLReportTruncated(t *testing.T) {
+	// 25 value differences, 10 missing on n2, 5 missing on n1; limit 30.
+	page, data := renderHTMLTestReport(t, htmlTestDiff(25, 10, 5, "x"), 30)
+
+	if got := countRows(page, "value_diff"); got != 25 {
+		t.Errorf("value rows: got %d, want 25", got)
+	}
+	if got := countRows(page, "missing_in_b"); got != 5 {
+		t.Errorf("missing_in_b rows: got %d, want 5", got)
+	}
+	if got := countRows(page, "missing_in_a"); got != 0 {
+		t.Errorf("missing_in_a rows: got %d, want 0", got)
+	}
+	if !strings.Contains(page, ">Missing in n2<") {
+		t.Error("group of rows missing on n2 is not shown")
+	}
+	if strings.Contains(page, ">Missing in n1<") {
+		t.Error("group header for rows missing on n1 is shown, but none of its rows are")
+	}
+
+	for _, want := range []string{
+		"This report shows 30 of 40 rows",
+		"public_t_diffs-20260101000000.json",
+		"Its default action is <code>skip</code>",
+		"Rows Shown in Report",
+		"30 of 40 rows shown",
+		"Not shown: 5 missing in n2, 5 missing in n1.",
+		"table-repair skips the other rows",
+		"they stay different",
+		"--max-html-rows",
+		"10 more rows are not shown (5 missing in n2, 5 missing in n1)",
+		"Default: insert from n1",
+		`data-truncated="true"`,
+	} {
+		if !strings.Contains(page, want) {
+			t.Errorf("truncated report does not contain %q", want)
+		}
+	}
+
+	// The page script builds repair plans from the embedded data, so it
+	// must hold exactly the rows on the page and say that it is partial.
+	want := map[string]int{"row_mismatch": 25, "missing_on_n2": 5}
+	if got := data.typeCounts("n1/n2"); fmt.Sprint(got) != fmt.Sprint(want) {
+		t.Errorf("embedded rows: got %v, want %v", got, want)
+	}
+	info := data.HTMLReport
+	if !info.Truncated || info.MaxRows != 30 || info.DiffFile != "public_t_diffs-20260101000000.json" {
+		t.Errorf("html_report: got %+v", info)
+	}
+	if len(info.Pairs) != 1 || info.Pairs[0] != (htmlPairInfo{Pair: "n1/n2", Shown: 30, Total: 40}) {
+		t.Errorf("html_report.pairs: got %+v", info.Pairs)
+	}
+}
+
+func TestHTMLReportTruncatedInsideValueDiffs(t *testing.T) {
+	page, data := renderHTMLTestReport(t, htmlTestDiff(25, 10, 5, "x"), 20)
+
+	if got := countRows(page, "value_diff"); got != 20 {
+		t.Errorf("value rows: got %d, want 20", got)
+	}
+	if strings.Contains(page, ">Missing Rows<") {
+		t.Error("missing rows separator is shown, but no missing row is")
+	}
+	want := "20 more rows are not shown (5 value differences, 10 missing in n2, 5 missing in n1)"
+	if !strings.Contains(page, want) {
+		t.Errorf("footer does not contain %q", want)
+	}
+
+	// The shown rows are the first 20 primary keys.
+	if len(data.Rows) != 20 {
+		t.Fatalf("embedded rows: got %d, want 20", len(data.Rows))
+	}
+	for i, r := range data.Rows {
+		if r.PK[0] != fmt.Sprint(i+1) {
+			t.Fatalf("embedded row %d has pk %v, want %d", i, r.PK, i+1)
+		}
+	}
+}
+
 // Primary key values go into the embedded JSON inside a <script> element,
 // twice: as the display key and as a JSON literal. A value must not be able
 // to close that element.
@@ -157,7 +251,7 @@ func TestHTMLReportEmbeddedDataCannotCloseScript(t *testing.T) {
 		}}},
 		Summary: types.DiffSummary{Schema: "public", Table: "t", PrimaryKey: []string{"id"}, DiffRowsCount: map[string]int{"n1/n2": 1}},
 	}
-	page, data := renderHTMLTestReport(t, diff)
+	page, data := renderHTMLTestReport(t, diff, 0)
 
 	if strings.Contains(page, evil) {
 		t.Fatal("raw value with </script> appears in the page")
@@ -177,7 +271,7 @@ func TestHTMLReportEmbeddedDataCannotCloseScript(t *testing.T) {
 func TestHTMLReportNoRows(t *testing.T) {
 	diff := htmlTestDiff(0, 0, 0, "")
 	diff.Summary.IncompletePairs = []string{"n1/n2"}
-	page, data := renderHTMLTestReport(t, diff)
+	page, data := renderHTMLTestReport(t, diff, 0)
 
 	if !strings.Contains(page, "No row-level differences were recorded.") {
 		t.Error("empty report has no empty message")
@@ -187,6 +281,31 @@ func TestHTMLReportNoRows(t *testing.T) {
 	}
 }
 
+func TestHTMLPairPlanApplyLimit(t *testing.T) {
+	p := &htmlPairPlan{
+		valueKeys:  make([]string, 3),
+		missingInB: make([]string, 4),
+		missingInA: make([]string, 5),
+	}
+	for _, tc := range []struct {
+		limit            int64
+		value, mb, ma, n int
+	}{
+		{limit: 1, value: 1, n: 1},
+		{limit: 3, value: 3, n: 3},
+		{limit: 5, value: 3, mb: 2, n: 5},
+		{limit: 9, value: 3, mb: 4, ma: 2, n: 9},
+		{limit: 12, value: 3, mb: 4, ma: 5, n: 12},
+		{limit: 1000, value: 3, mb: 4, ma: 5, n: 12},
+	} {
+		p.applyLimit(tc.limit)
+		if p.shownValue != tc.value || p.shownMissingB != tc.mb || p.shownMissingA != tc.ma || p.shown() != tc.n {
+			t.Errorf("limit %d: got %d/%d/%d (%d), want %d/%d/%d (%d)", tc.limit,
+				p.shownValue, p.shownMissingB, p.shownMissingA, p.shown(), tc.value, tc.mb, tc.ma, tc.n)
+		}
+	}
+}
+
 // threeNodeDiff has two node pairs with different row sets, so a mix-up
 // between pairs or nodes shows in the key checks.
 func threeNodeDiff() types.DiffOutput {
@@ -230,7 +349,7 @@ func pageKeys(t *testing.T, page string) []map[string][]string {
 // user choices by data-pk, so the rendered rows and the embedded rows must be
 // the same rows, of the same type, in the same order, for every pair.
 func TestHTMLReportPageAndDataHoldTheSameRows(t *testing.T) {
-	page, data := renderHTMLTestReport(t, threeNodeDiff())
+	page, data := renderHTMLTestReport(t, threeNodeDiff(), 8)
 	sections := pageKeys(t, page)
 	if len(sections) != 2 {
 		t.Fatalf("got %d sections, want 2", len(sections))
@@ -254,9 +373,16 @@ func TestHTMLReportPageAndDataHoldTheSameRows(t *testing.T) {
 		if fmt.Sprint(got) != fmt.Sprint(sections[i]) {
 			t.Errorf("%s: embedded rows %v, page shows %v", pc.pair, got, sections[i])
 		}
+		n := len(got["value_diff"]) + len(got["missing_in_b"]) + len(got["missing_in_a"])
+		if n != 8 {
+			t.Errorf("%s: %d rows, want the limit 8", pc.pair, n)
+		}
+		if info := data.HTMLReport.Pairs[i]; info.Pair != pc.pair || info.Shown != n {
+			t.Errorf("%s: html_report says %+v, page shows %d rows", pc.pair, info, n)
+		}
 	}
-	if len(data.Rows) != 22+11 {
-		t.Errorf("embedded rows: got %d, want 33", len(data.Rows))
+	if data.HTMLReport.Pairs[0].Total != 22 || data.HTMLReport.Pairs[1].Total != 11 {
+		t.Errorf("pair totals: got %+v", data.HTMLReport.Pairs)
 	}
 }
 
@@ -285,7 +411,7 @@ func TestHTMLReportPKLiterals(t *testing.T) {
 		{"json number", json.Number("12345678901234567890"), json.Number("1"), "12345678901234567890", true},
 	} {
 		t.Run(tc.name, func(t *testing.T) {
-			_, data := renderHTMLTestReport(t, one(tc.v1, tc.v2))
+			_, data := renderHTMLTestReport(t, one(tc.v1, tc.v2), 0)
 			if data.Rows[0].PK[0] != tc.lit1 {
 				t.Errorf("pk literal: got %s, want %s", data.Rows[0].PK[0], tc.lit1)
 			}
@@ -315,7 +441,7 @@ func TestHTMLReportIsDeterministic(t *testing.T) {
 	var first string
 	for run := 0; run < 20; run++ {
 		var buf bytes.Buffer
-		if err := renderHTMLDiffReport(&buf, diff); err != nil {
+		if err := renderHTMLDiffReport(&buf, diff, "d.json", 20); err != nil {
 			t.Fatal(err)
 		}
 		if run == 0 {
@@ -358,6 +484,31 @@ func TestComparePKComponentIsATotalOrder(t *testing.T) {
 	}
 }
 
+// table-diff can count a row that the report leaves out because its values
+// look the same (1 against "1"). The section counts must still add up, and
+// the page must say why the numbers differ.
+func TestHTMLReportRowsWithoutVisibleDifference(t *testing.T) {
+	d := htmlTestDiff(2, 0, 0, "x")
+	pair := d.NodeDiffs["n1/n2"]
+	pair.Rows["n1"] = append(pair.Rows["n1"], types.OrderedMap{{Key: "id", Value: 3}, {Key: "val", Value: 1}, {Key: "note", Value: "x"}})
+	pair.Rows["n2"] = append(pair.Rows["n2"], types.OrderedMap{{Key: "id", Value: 3}, {Key: "val", Value: "1"}, {Key: "note", Value: "x"}})
+	d.Summary.DiffRowsCount["n1/n2"] = 3
+
+	page, data := renderHTMLTestReport(t, d, 2)
+	if strings.Contains(page, `class="truncation-banner"`) {
+		t.Error("report shows a truncation banner, but every row with a difference is shown")
+	}
+	if !strings.Contains(page, ">2 rows<") {
+		t.Error("section pill does not count the rendered rows")
+	}
+	if !strings.Contains(page, "1 of the 3 rows that table-diff found for this pair have no visible difference") {
+		t.Error("section does not explain the row left out")
+	}
+	if data.HTMLReport.Truncated {
+		t.Error("html_report.truncated is true")
+	}
+}
+
 type failingWriter struct{ left int }
 
 func (w *failingWriter) Write(p []byte) (int, error) {
@@ -379,7 +530,7 @@ func TestRenderHTMLDiffReportWriteError(t *testing.T) {
 
 	diff := htmlTestDiff(4, 2, 2, "x")
 	var full bytes.Buffer
-	if err := renderHTMLDiffReport(&full, diff); err != nil {
+	if err := renderHTMLDiffReport(&full, diff, "d.json", 0); err != nil {
 		t.Fatal(err)
 	}
 	page := full.String()
@@ -390,7 +541,7 @@ func TestRenderHTMLDiffReportWriteError(t *testing.T) {
 		t.Fatal("could not find the parts of the page")
 	}
 	for name, at := range map[string]int{"head": 10, "rows": rowsAt + 10, "embedded data": dataAt + 60, "tail": tailAt + 10} {
-		err := renderHTMLDiffReport(&failingWriter{left: at}, diff)
+		err := renderHTMLDiffReport(&failingWriter{left: at}, diff, "d.json", 0)
 		if err == nil || !strings.Contains(err.Error(), "disk full") {
 			t.Errorf("write error in the %s (after %d bytes): got %v", name, at, err)
 		}
@@ -406,7 +557,7 @@ func TestWriteHTMLDiffReportRemovesFileOnError(t *testing.T) {
 	htmlDiffTemplate = `{{define "report_head"}}{{.NoSuchField}}{{end}}`
 	t.Cleanup(func() { htmlDiffTemplate = orig })
 
-	got, err := writeHTMLDiffReport(htmlTestDiff(1, 0, 0, "x"), jsonPath)
+	got, err := writeHTMLDiffReport(htmlTestDiff(1, 0, 0, "x"), jsonPath, 0)
 	if err == nil {
 		t.Fatal("expected an error from a broken template")
 	}
diff --git a/pkg/common/secure_file_test.go b/pkg/common/secure_file_test.go
index f630331..5aab1a5 100644
--- a/pkg/common/secure_file_test.go
+++ b/pkg/common/secure_file_test.go
@@ -96,7 +96,7 @@ func TestWriteDiffReportIsNotWorldReadable(t *testing.T) {
 				},
 			}
 
-			jsonPath, htmlPath, err := WriteDiffReport(diff, "public", "customers", format)
+			jsonPath, htmlPath, err := WriteDiffReport(diff, "public", "customers", format, 0)
 			if err != nil {
 				t.Fatalf("WriteDiffReport: %v", err)
 			}
diff --git a/pkg/common/templates/diff_report.css b/pkg/common/templates/diff_report.css
index dbe49b6..d4aea1a 100644
--- a/pkg/common/templates/diff_report.css
+++ b/pkg/common/templates/diff_report.css
@@ -573,6 +573,52 @@ h1 {
     padding: 0;
 }
 
+.truncation-banner {
+    margin: 1.5rem 0;
+    padding: 1rem 1.25rem;
+    border: 1px solid var(--warning-color);
+    border-radius: 8px;
+    background: #fff8e1;
+    color: #6f4e00;
+}
+
+.truncation-title {
+    font-weight: 650;
+    font-size: 1.05rem;
+    margin-bottom: 0.25rem;
+}
+
+.truncation-note {
+    padding: 0.75rem 1.5rem;
+    background: #fff8e1;
+    color: #6f4e00;
+    border-bottom: 1px solid var(--border-color);
+    font-size: 0.9rem;
+}
+
+.truncation-row td {
+    background: var(--bg-secondary);
+    color: var(--text-secondary);
+    text-align: center;
+    padding: 0.85rem;
+    font-weight: 600;
+    border-top: 1px solid var(--border-color);
+}
+
+.truncation-banner code,
+.truncation-note code,
+.truncation-row code {
+    overflow-wrap: anywhere;
+}
+
+.section-note {
+    padding: 0.6rem 1.5rem;
+    background: var(--bg-secondary);
+    color: var(--text-secondary);
+    border-bottom: 1px solid var(--border-color);
+    font-size: 0.85rem;
+}
+
 .empty-message {
     padding: 1.5rem;
     color: var(--text-secondary);
diff --git a/pkg/common/templates/diff_report.html b/pkg/common/templates/diff_report.html
index 2065ff7..e522133 100644
--- a/pkg/common/templates/diff_report.html
+++ b/pkg/common/templates/diff_report.html
@@ -15,6 +15,13 @@
 <body>
     <div class="container">
         <h1>ACE Table Diff Report</h1>
+        {{if .Truncation}}
+        <div class="truncation-banner" role="status">
+            <div class="truncation-title">This report shows {{.Truncation.Shown}} of {{.Truncation.Total}} rows</div>
+            <div>The HTML report shows at most {{.Truncation.Limit}} rows for each node pair (max_html_rows). The full diff is in <code>{{.Truncation.DiffFile}}</code>.</div>
+            <div>A repair plan built on this page has rules only for the rows shown. Its default action is <code>skip</code>, so table-repair does not change the other rows, and they stay different between the nodes. To see or repair them, run table-diff again with a larger <code>--max-html-rows</code>.</div>
+        </div>
+        {{end}}
         <div class="plan-builder">
             <h3>Build an advanced repair plan</h3>
             <p>Create a starter repair plan (YAML) from this diff. The plan will set <code>keep_n1</code> for mismatches, <code>apply_from n1 insert</code> for rows missing on node2, and <code>apply_from n2 insert</code> for rows missing on node1. You can edit the plan to add rules or change actions.</p>
@@ -53,11 +60,17 @@ <h2>Summary</h2>
 {{end}}
 
 {{define "pair_head"}}
-            <div class="diff-section" data-nodea="{{.NodeA}}" data-nodeb="{{.NodeB}}">
+            <div class="diff-section" data-nodea="{{.NodeA}}" data-nodeb="{{.NodeB}}"{{if .Hidden}} data-truncated="true"{{end}}>
                 <div class="diff-header">
                     <div class="pair-title">Differences between {{.NodeA}} and {{.NodeB}}</div>
-                    <span class="diff-count-pill">{{.DiffCount}} entries</span>
+                    <span class="diff-count-pill">{{if .Hidden}}{{.Shown}} of {{.Total}} rows shown{{else}}{{.Total}} rows{{end}}</span>
                 </div>
+                {{if .Hidden}}
+                <div class="truncation-note">This section shows {{.Shown}} of {{.Total}} rows. Not shown: {{.HiddenBreakdown}}. The repair plan from this page has rules only for the rows shown; table-repair skips the other rows, and they stay different.</div>
+                {{end}}
+                {{if .NotRendered}}
+                <div class="section-note">{{.NotRendered}} of the {{.DiffCount}} rows that table-diff found for this pair have no visible difference in the compared columns, so the report does not show them.</div>
+                {{end}}
                 <div class="table-wrapper">
                     <table class="diff-table">
                         <thead>
@@ -89,7 +102,7 @@ <h2>Summary</h2>
                                     <div class="action-wrapper">
                                         <span class="action-label">Row Action</span>
                                         <select class="plan-action" data-type="mismatch" data-pk="{{.PKey}}" data-nodea="{{ .NodeA }}" data-nodeb="{{ .NodeB }}">
-                                            <option value="">Use default (keep_n1)</option>
+                                            <option value="">Default: keep_n1</option>
                                             <option value="keep_n1">Keep {{.NodeA}}</option>
                                             <option value="keep_n2">Keep {{.NodeB}}</option>
                                             <option value="apply_from_n1_insert">Apply from {{.NodeA}} (insert if missing)</option>
@@ -164,7 +177,7 @@ <h2>Summary</h2>
                                         <div class="action-wrapper">
                                             <span class="action-label">Row Action</span>
                                             <select class="plan-action" data-type="{{.RowType}}" data-pk="{{.PKey}}" data-nodea="{{ .NodeA }}" data-nodeb="{{ .NodeB }}">
-                                                <option value="">Use default</option>
+                                                <option value="">Default: insert from {{if eq .RowType "missing_in_b"}}{{.NodeA}}{{else}}{{.NodeB}}{{end}}</option>
                                                 <option value="apply_from_n1_insert">Insert from {{.NodeA}}</option>
                                                 <option value="apply_from_n2_insert">Insert from {{.NodeB}}</option>
                                                 <option value="delete">Delete</option>
@@ -228,6 +241,9 @@ <h2>Summary</h2>
 {{end}}
 
 {{define "pair_tail"}}
+                        {{if .Hidden}}
+                        <tr class="truncation-row"><td colspan="3">{{.Hidden}} more rows are not shown ({{.HiddenBreakdown}}). See <code>{{.DiffFile}}</code> for the full list.</td></tr>
+                        {{end}}
                         {{if not .HasDiffs}}
                         <tr><td colspan="3" class="empty-message">No column level differences detected for this node pair.</td></tr>
                         {{end}}
diff --git a/pkg/common/templates/diff_report.js b/pkg/common/templates/diff_report.js
index 7a6feb9..4073a06 100644
--- a/pkg/common/templates/diff_report.js
+++ b/pkg/common/templates/diff_report.js
@@ -11,12 +11,16 @@
         if (controls.length === 0 && checkboxes.length === 0) return;
         const nodeALabel = section.dataset.nodea || 'node A';
         const nodeBLabel = section.dataset.nodeb || 'node B';
+        // A truncated section holds only part of the pair's rows. The bulk
+        // controls act on the rows on this page, so their labels must not
+        // say "all rows" there.
+        const sectionTruncated = section.dataset.truncated === 'true';
         const bulkBar = document.createElement('div');
         bulkBar.className = 'bulk-bar';
         const selectAllBtn = document.createElement('button');
         selectAllBtn.type = 'button';
         selectAllBtn.className = 'select-all-btn';
-        selectAllBtn.textContent = 'Select all rows';
+        selectAllBtn.textContent = allRowsLabel('Select all');
         selectAllBtn.addEventListener('click', () => {
             if (!checkboxes.length) return;
             const shouldSelectAll = !checkboxes.every(cb => cb.checked);
@@ -44,7 +48,7 @@
         });
         const label = document.createElement('span');
         label.className = 'bulk-label';
-        label.textContent = 'Apply to all rows for ' + nodeALabel + ' vs ' + nodeBLabel + ':';
+        label.textContent = 'Apply to ' + allRowsLabel('all').toLowerCase() + ' for ' + nodeALabel + ' vs ' + nodeBLabel + ':';
         const select = document.createElement('select');
         select.className = 'bulk-select';
         select.setAttribute('aria-label', 'Bulk action for ' + nodeALabel + ' and ' + nodeBLabel);
@@ -102,7 +106,9 @@
         bulkBar.appendChild(selectAllBtn);
         bulkBar.appendChild(copyBtn);
         bulkBar.appendChild(downloadBtn);
-        section.insertBefore(bulkBar, section.children[1]);
+        // Put the bar after the section notes, so that the warnings come
+        // before the buttons that export the plan.
+        section.insertBefore(bulkBar, section.querySelector('.table-wrapper'));
 
         function toggleRowSelection(cb) {
             const row = cb.closest('.diff-row');
@@ -120,7 +126,7 @@
                 return;
             }
             const allSelected = checkboxes.every(cb => cb.checked);
-            selectAllBtn.textContent = allSelected ? 'Clear selection' : 'Select all rows';
+            selectAllBtn.textContent = allSelected ? 'Clear selection' : allRowsLabel('Select all');
             selectAllBtn.classList.toggle('is-active', allSelected);
             selectAllBtn.setAttribute('aria-pressed', allSelected ? 'true' : 'false');
         }
@@ -129,10 +135,16 @@
             if (selectedCount > 0) {
                 label.textContent = 'Apply to ' + selectedCount + ' selected ' + (selectedCount === 1 ? 'row' : 'rows') + ' for ' + nodeALabel + ' vs ' + nodeBLabel + ':';
             } else {
-                label.textContent = 'Apply to all rows for ' + nodeALabel + ' vs ' + nodeBLabel + ':';
+                label.textContent = 'Apply to ' + allRowsLabel('all').toLowerCase() + ' for ' + nodeALabel + ' vs ' + nodeBLabel + ':';
             }
         }
 
+        // "Select all rows", or "Select all 25 shown rows" in a truncated report.
+        function allRowsLabel(prefix) {
+            if (!sectionTruncated) return prefix + ' rows';
+            return prefix + ' ' + checkboxes.length + ' shown ' + (checkboxes.length === 1 ? 'row' : 'rows');
+        }
+
         function toggleCustomEditor(selectEl) {
             const wrapper = selectEl.closest('.action-wrapper');
             if (!wrapper) return;
@@ -232,13 +244,22 @@
         if (!pkCols.length) throw new Error('No primary key info available');
         const tableKey = diff.summary.schema + '.' + diff.summary.table;
 
+        // rowDefault is what "Default" means for a mismatched row on the
+        // page. planDefault is the plan's default_action, which table-repair
+        // applies to every row of the diff file that no rule or override
+        // matches. In a truncated report that includes the rows the user never
+        // saw, so the plan must leave them alone: its default is skip, and
+        // every shown row gets an explicit rule. keep_n1 would also be wrong
+        // for rows missing on n1, and table-repair rejects the whole plan then.
         const report = diff.html_report || {};
-        const defaultAction = { type: 'keep_n1' };
+        const truncated = !!report.truncated;
+        const rowDefault = { type: 'keep_n1' };
+        const planDefault = truncated ? { type: 'skip' } : rowDefault;
         const targetKeys = selectionInfo?.usingSelection ? selectionInfo.selectedKeys : null;
         const usingSelection = !!selectionInfo?.usingSelection;
         const allSelected = usingSelection && selectionInfo.selectedCount === selectionInfo.totalRows && selectionInfo.totalRows > 0;
 
-        const rows = collectRows(diff, targetKeys, defaultAction);
+        const rows = collectRows(diff, targetKeys, rowDefault, planDefault);
 
         const grouped = groupRows(rows, pkCols);
         const rules = [];
@@ -265,11 +286,31 @@
         });
 
         const lines = [];
+        // The YAML file leaves this page, so the warning must travel inside it.
+        if (truncated) {
+            lines.push('# WARNING: this plan was built from a truncated HTML report.');
+            if (usingSelection) {
+                lines.push('# It has rules only for the ' + selectionInfo.selectedCount + ' rows selected in that report.');
+                lines.push('# The report shows:');
+            } else {
+                lines.push('# It has rules only for the rows shown in that report:');
+            }
+            (report.pairs || []).forEach(p => {
+                if (p.shown < p.total) {
+                    lines.push('#   ' + p.pair + ': ' + p.shown + ' of ' + p.total + ' rows shown');
+                }
+            });
+            lines.push('# default_action is skip, so table-repair does not change any other');
+            lines.push('# row of the diff file, and those rows stay different. To cover all');
+            lines.push('# rows, run table-diff again with a larger max_html_rows');
+            lines.push('# (or --max-html-rows), or add rules by hand.');
+            lines.push('# Full diff: ' + JSON.stringify(report.diff_file || ''));
+        }
         lines.push('version: 1');
         lines.push('tables:');
         lines.push('  ' + tableKey + ':');
         lines.push('    default_action:');
-        lines.push('      type: ' + defaultAction.type);
+        lines.push('      type: ' + planDefault.type);
         if (rules.length) {
             lines.push('    rules:');
             rules.forEach(rule => {
@@ -311,7 +352,7 @@
     // diff file; they go into the YAML as they are and are never turned into
     // JavaScript numbers, which would lose digits of a bigint and turn a text
     // key such as "007" into the number 7.
-    function collectRows(diff, targetKeys, defaultAction) {
+    function collectRows(diff, targetKeys, rowDefault, planDefault) {
         const rows = [];
         const seen = new Set();
 
@@ -328,12 +369,12 @@
                 } else if (r.type === 'missing_on_n1') {
                     action = { type: 'apply_from', from: r.node_b, mode: 'insert' };
                 } else {
-                    action = defaultAction;
+                    action = rowDefault;
                 }
             }
 
             // Skip emitting explicit instructions for rows that match the table default.
-            const matchesDefault = isSameAction(action, defaultAction) && r.type === 'row_mismatch';
+            const matchesDefault = isSameAction(action, planDefault) && r.type === 'row_mismatch';
             if (matchesDefault) continue;
 
             rows.push({ key, pkTuple: r.pk, action, diffType: r.type });
diff --git a/pkg/common/utils.go b/pkg/common/utils.go
index dfc270c..d4b85b8 100644
--- a/pkg/common/utils.go
+++ b/pkg/common/utils.go
@@ -1503,7 +1503,11 @@ func MapToOrderedMap(m map[string]any, cols []string) types.OrderedMap {
 	return om
 }
 
-func WriteDiffReport(diffResult types.DiffOutput, schema, table, format string) (string, string, error) {
+// WriteDiffReport writes the JSON diff report and, when format is "html", an
+// HTML report next to it. maxHTMLRows limits how many entries the HTML report
+// shows for each node pair; a value <= 0 means DefaultMaxHTMLRows. The JSON
+// report always has every row.
+func WriteDiffReport(diffResult types.DiffOutput, schema, table, format string, maxHTMLRows int64) (string, string, error) {
 	// An empty NodeDiffs means "the tables match" only if every node pair was
 	// really compared. If work items were lost to errors, it means "we do not
 	// know", and the summary that names those pairs is still worth writing to
@@ -1565,7 +1569,7 @@ func WriteDiffReport(diffResult types.DiffOutput, schema, table, format string)
 
 	var htmlPath string
 	if strings.EqualFold(format, "html") {
-		htmlPath, err = writeHTMLDiffReport(diffResult, jsonFileName)
+		htmlPath, err = writeHTMLDiffReport(diffResult, jsonFileName, maxHTMLRows)
 		if err != nil {
 			// The JSON report is complete; say where it is, so the run is not lost.
 			return jsonFileName, "", fmt.Errorf("%w (the JSON report %s was written)", err, jsonFileName)
diff --git a/pkg/common/utils_test.go b/pkg/common/utils_test.go
index 3e4f573..f8aff05 100644
--- a/pkg/common/utils_test.go
+++ b/pkg/common/utils_test.go
@@ -524,7 +524,7 @@ func TestWriteDiffReportNoMatchVerdictWhenIncomplete(t *testing.T) {
 	clean := types.DiffOutput{
 		Summary: types.DiffSummary{Schema: "public", Table: "t"},
 	}
-	jsonPath, _, err := WriteDiffReport(clean, "public", "t", "json")
+	jsonPath, _, err := WriteDiffReport(clean, "public", "t", "json", 0)
 	require.NoError(t, err)
 	require.Empty(t, jsonPath, "a fully compared run with no diffs is a match, so nothing is written")
 
@@ -535,7 +535,7 @@ func TestWriteDiffReportNoMatchVerdictWhenIncomplete(t *testing.T) {
 			IncompletePairs: []string{"n1/n2"},
 		},
 	}
-	jsonPath, _, err = WriteDiffReport(incomplete, "public", "t", "json")
+	jsonPath, _, err = WriteDiffReport(incomplete, "public", "t", "json", 0)
 	require.NoError(t, err)
 	require.NotEmpty(t, jsonPath, "an incomplete comparison must not be reported as a match")
 	require.FileExists(t, jsonPath)

From b3e33abb360d6e339809a7492e9210d284bd1eca Mon Sep 17 00:00:00 2001
From: Andrei Lepikhov <lepihov@gmail.com>
Date: Thu, 24 Sep 2026 15:51:55 +0200
Subject: [PATCH 4/7] Add the max_html_rows setting

The HTML report limit was fixed at the default. It can now be set:

- table_diff.max_html_rows and mtree.diff.max_html_rows in ace.yaml;
- --max-html-rows on table-diff and mtree table-diff;
- max_html_rows in the args of a scheduled table-diff job.

The command-line value wins, then the config value, then the default of
10,000 rows per node pair. 0 means "not set". There is no setting for
"no limit"; a large number does the same. A negative value is an error
in every place, where before a negative config value would have been
ignored without a word. repset-diff and schema-diff take the value from
table_diff in the config. The sample and default configs list the key.

Tests: how TableDiffTask.Validate resolves the value, and the errors for
negative values.
---
 ace.sample.yaml                               |  3 +
 internal/cli/cli.go                           | 12 ++++
 internal/cli/default_config.yaml              |  3 +
 internal/consistency/diff/table_diff.go       | 17 ++++-
 .../diff/table_diff_html_rows_test.go         | 69 +++++++++++++++++++
 internal/consistency/mtree/merkle.go          | 18 ++++-
 internal/jobs/config.go                       |  5 ++
 pkg/config/config.go                          |  2 +
 8 files changed, 127 insertions(+), 2 deletions(-)
 create mode 100644 internal/consistency/diff/table_diff_html_rows_test.go

diff --git a/ace.sample.yaml b/ace.sample.yaml
index f80dbe3..9cbc85f 100644
--- a/ace.sample.yaml
+++ b/ace.sample.yaml
@@ -22,6 +22,7 @@ postgres:
 table_diff:
   concurrency_factor: 0.5
   max_diff_rows: 1000000
+  max_html_rows: 10000         # max rows per node pair in the HTML report
   min_diff_block_size: 1
   max_diff_block_size: 1000000
   diff_block_size: 1000
@@ -52,6 +53,8 @@ mtree:
     max_block_size: 1000000
     # Max differing rows collected per node pair; 0 or absent means unbounded.
     max_diff_rows: 1000000
+    # Max rows per node pair in the HTML report (--output html).
+    max_html_rows: 10000
 
 # Example scheduler configuration:
 # schedule_jobs:
diff --git a/internal/cli/cli.go b/internal/cli/cli.go
index 400e45c..4dbf49d 100644
--- a/internal/cli/cli.go
+++ b/internal/cli/cli.go
@@ -142,6 +142,11 @@ func SetupCLI(version string) *cli.Command {
 
 	tableDiffFlags := append(commonFlags, diffFlags...)
 	tableDiffFlags = append(tableDiffFlags,
+		&cli.Int64Flag{
+			Name:  "max-html-rows",
+			Usage: "Max rows per node pair in the HTML report (0 = use max_html_rows from config, default 10000)",
+			Value: 0,
+		},
 		&cli.StringFlag{
 			Name:    "table-filter",
 			Aliases: []string{"F"},
@@ -376,6 +381,11 @@ func SetupCLI(version string) *cli.Command {
 	mtreeUpdateFlags = append(mtreeUpdateFlags, commonFlags...)
 
 	mtreeDiffFlags := []cli.Flag{
+		&cli.Int64Flag{
+			Name:  "max-html-rows",
+			Usage: "Max rows per node pair in the HTML report (0 = use max_html_rows from config, default 10000)",
+			Value: 0,
+		},
 		&cli.Float64Flag{
 			Name:    "max-cpu-ratio",
 			Aliases: []string{"m"},
@@ -948,6 +958,7 @@ func TableDiffCLI(cmd *cli.Command) error {
 	task.MaxConnections = cmd.Int("max-connections")
 	task.CompareUnitSize = cmd.Int("compare-unit-size")
 	task.Output = strings.ToLower(cmd.String("output"))
+	task.MaxHTMLRows = cmd.Int64("max-html-rows")
 	task.Nodes = cmd.String("nodes")
 	task.EnsurePgcrypto = cmd.Bool("ensure-pgcrypto")
 	scheduleEnabled := cmd.Bool("schedule")
@@ -1205,6 +1216,7 @@ func MtreeDiffCLI(cmd *cli.Command) error {
 	task.QuietMode = cmd.Bool("quiet")
 	task.MaxCpuRatio = cmd.Float64("max-cpu-ratio")
 	task.Output = cmd.String("output")
+	task.MaxHTMLRows = cmd.Int64("max-html-rows")
 	task.NoCDC = cmd.Bool("skip-cdc")
 	task.CDCTimeoutSec = cmd.Int("cdc-timeout")
 	task.Until = cmd.String("until")
diff --git a/internal/cli/default_config.yaml b/internal/cli/default_config.yaml
index f80dbe3..9cbc85f 100644
--- a/internal/cli/default_config.yaml
+++ b/internal/cli/default_config.yaml
@@ -22,6 +22,7 @@ postgres:
 table_diff:
   concurrency_factor: 0.5
   max_diff_rows: 1000000
+  max_html_rows: 10000         # max rows per node pair in the HTML report
   min_diff_block_size: 1
   max_diff_block_size: 1000000
   diff_block_size: 1000
@@ -52,6 +53,8 @@ mtree:
     max_block_size: 1000000
     # Max differing rows collected per node pair; 0 or absent means unbounded.
     max_diff_rows: 1000000
+    # Max rows per node pair in the HTML report (--output html).
+    max_html_rows: 10000
 
 # Example scheduler configuration:
 # schedule_jobs:
diff --git a/internal/consistency/diff/table_diff.go b/internal/consistency/diff/table_diff.go
index 268edb7..774c1c0 100644
--- a/internal/consistency/diff/table_diff.go
+++ b/internal/consistency/diff/table_diff.go
@@ -105,6 +105,10 @@ type TableDiffTask struct {
 
 	CompareUnitSize int
 	MaxDiffRows     int64
+	// MaxHTMLRows limits how many entries the HTML report shows for each
+	// node pair. 0 means table_diff.max_html_rows from the config, and if
+	// that is not set either, utils.DefaultMaxHTMLRows.
+	MaxHTMLRows int64
 
 	DiffResult types.DiffOutput
 	diffMutex  sync.Mutex
@@ -680,6 +684,16 @@ func (t *TableDiffTask) Validate() error {
 		t.MaxDiffRows = cfg.TableDiff.MaxDiffRows
 	}
 
+	if t.MaxHTMLRows < 0 {
+		return fmt.Errorf("max_html_rows must be >= 0")
+	}
+	if cfg.TableDiff.MaxHTMLRows < 0 {
+		return fmt.Errorf("table_diff.max_html_rows in the config must be >= 0, got %d", cfg.TableDiff.MaxHTMLRows)
+	}
+	if t.MaxHTMLRows == 0 && cfg.TableDiff.MaxHTMLRows > 0 {
+		t.MaxHTMLRows = cfg.TableDiff.MaxHTMLRows
+	}
+
 	if t.ConcurrencyFactor > 4.0 || t.ConcurrencyFactor <= 0 {
 		return fmt.Errorf("invalid value range for concurrency_factor, must be > 0 and <= 4.0")
 	}
@@ -1053,6 +1067,7 @@ func (t *TableDiffTask) CloneForSchedule(ctx context.Context) *TableDiffTask {
 	cloned.InvokeMethod = t.InvokeMethod
 	cloned.CompareUnitSize = t.CompareUnitSize
 	cloned.MaxDiffRows = t.MaxDiffRows
+	cloned.MaxHTMLRows = t.MaxHTMLRows
 	cloned.EnsurePgcrypto = t.EnsurePgcrypto
 	cloned.AgainstOrigin = t.AgainstOrigin
 	cloned.Until = t.Until
@@ -1641,7 +1656,7 @@ func (t *TableDiffTask) ExecuteTask() (err error) {
 
 	t.AddPrimaryKeyToDiffSummary()
 
-	jsonPath, _, err := utils.WriteDiffReport(t.DiffResult, t.Schema, t.BaseTable, t.Output, 0)
+	jsonPath, _, err := utils.WriteDiffReport(t.DiffResult, t.Schema, t.BaseTable, t.Output, t.MaxHTMLRows)
 	if err != nil {
 		return err
 	}
diff --git a/internal/consistency/diff/table_diff_html_rows_test.go b/internal/consistency/diff/table_diff_html_rows_test.go
new file mode 100644
index 0000000..5c1f84d
--- /dev/null
+++ b/internal/consistency/diff/table_diff_html_rows_test.go
@@ -0,0 +1,69 @@
+// ///////////////////////////////////////////////////////////////////////////
+//
+// # ACE - Active Consistency Engine
+//
+// Copyright (C) 2023 - 2026, pgEdge (https://www.pgedge.com/)
+//
+// This software is released under the PostgreSQL License:
+// https://opensource.org/license/postgresql
+//
+// ///////////////////////////////////////////////////////////////////////////
+
+package diff
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/pgedge/ace/pkg/config"
+)
+
+// TestValidateMaxHTMLRows checks how Validate resolves max_html_rows: the
+// task value wins, 0 falls back to table_diff.max_html_rows, and a negative
+// value in either place is an error. Validate goes on to fail on other
+// checks later (the task here is incomplete), so only the max_html_rows
+// errors and the resolved value are checked.
+func TestValidateMaxHTMLRows(t *testing.T) {
+	for _, tc := range []struct {
+		name     string
+		task     int64
+		cfg      int64
+		want     int64
+		wantErrs string
+	}{
+		{name: "task value wins", task: 7, cfg: 500, want: 7},
+		{name: "config when task is 0", task: 0, cfg: 500, want: 500},
+		{name: "both 0 leave the default to the writer", task: 0, cfg: 0, want: 0},
+		{name: "negative task value", task: -1, cfg: 500, wantErrs: "max_html_rows must be >= 0"},
+		{name: "negative config value", task: 0, cfg: -5, wantErrs: "table_diff.max_html_rows in the config must be >= 0"},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			cfg := &config.Config{}
+			cfg.TableDiff.MinBlockSize = 1
+			cfg.TableDiff.MaxBlockSize = 1000000
+			cfg.TableDiff.MaxHTMLRows = tc.cfg
+			config.Set(cfg)
+			t.Cleanup(func() { config.Set(nil) })
+
+			task := NewTableDiffTask()
+			task.ClusterName = "c"
+			task.QualifiedTableName = "public.t"
+			task.BlockSize = 1000
+			task.MaxHTMLRows = tc.task
+
+			err := task.Validate()
+			if tc.wantErrs != "" {
+				if err == nil || !strings.Contains(err.Error(), tc.wantErrs) {
+					t.Fatalf("Validate: got error %v, want one containing %q", err, tc.wantErrs)
+				}
+				return
+			}
+			if err != nil && strings.Contains(err.Error(), "max_html_rows") {
+				t.Fatalf("Validate: unexpected max_html_rows error: %v", err)
+			}
+			if task.MaxHTMLRows != tc.want {
+				t.Errorf("MaxHTMLRows after Validate: got %d, want %d", task.MaxHTMLRows, tc.want)
+			}
+		})
+	}
+}
diff --git a/internal/consistency/mtree/merkle.go b/internal/consistency/mtree/merkle.go
index 17a69dd..054fc81 100644
--- a/internal/consistency/mtree/merkle.go
+++ b/internal/consistency/mtree/merkle.go
@@ -110,6 +110,11 @@ type MerkleTreeTask struct {
 	// and OOM the process.
 	MaxDiffRows int64
 
+	// MaxHTMLRows limits how many entries the HTML report shows for each
+	// node pair. 0 means mtree.diff.max_html_rows from the config, and if
+	// that is not set either, utils.DefaultMaxHTMLRows.
+	MaxHTMLRows int64
+
 	DiffResult     types.DiffOutput
 	diffMutex      sync.Mutex
 	diffRowKeySets map[string]map[string]map[string]struct{}
@@ -2401,6 +2406,12 @@ func (m *MerkleTreeTask) DiffMtree() (err error) {
 	if m.MaxDiffRows < 0 {
 		return fmt.Errorf("max_diff_rows must be >= 0, got %d", m.MaxDiffRows)
 	}
+	if m.MaxHTMLRows < 0 {
+		return fmt.Errorf("max_html_rows must be >= 0, got %d", m.MaxHTMLRows)
+	}
+	if cfg := config.Get(); cfg != nil && cfg.MTree.Diff.MaxHTMLRows < 0 {
+		return fmt.Errorf("mtree.diff.max_html_rows in the config must be >= 0, got %d", cfg.MTree.Diff.MaxHTMLRows)
+	}
 
 	if err = m.UpdateMtree(true); err != nil {
 		// A missing tree already carries a complete, actionable message;
@@ -2443,6 +2454,11 @@ func (m *MerkleTreeTask) DiffMtree() (err error) {
 			m.MaxDiffRows = cfg.MTree.Diff.MaxDiffRows
 		}
 	}
+	if m.MaxHTMLRows == 0 {
+		if cfg := config.Get(); cfg != nil && cfg.MTree.Diff.MaxHTMLRows > 0 {
+			m.MaxHTMLRows = cfg.MTree.Diff.MaxHTMLRows
+		}
+	}
 	m.diffRowCounts = make(map[string]int64)
 	m.diffLimitWarned = false
 	m.pairCompareErrs = make(map[string]bool)
@@ -2615,7 +2631,7 @@ func (m *MerkleTreeTask) DiffMtree() (err error) {
 			logger.Warn("mtree table-diff stopped after reaching max_diff_rows=%d; additional differences may exist", m.MaxDiffRows)
 		}
 
-		diffPath, _, writeErr := utils.WriteDiffReport(m.DiffResult, m.Schema, m.Table, m.Output, 0)
+		diffPath, _, writeErr := utils.WriteDiffReport(m.DiffResult, m.Schema, m.Table, m.Output, m.MaxHTMLRows)
 		if writeErr != nil {
 			return writeErr
 		}
diff --git a/internal/jobs/config.go b/internal/jobs/config.go
index a89256b..57edf77 100644
--- a/internal/jobs/config.go
+++ b/internal/jobs/config.go
@@ -109,6 +109,11 @@ func buildTableDiffJob(cfg *config.Config, def config.JobDef, spec scheduleSpec)
 	if v := intArg(def.Args, "max_diff_rows", 0); v > 0 {
 		base.MaxDiffRows = int64(v)
 	}
+	if v := intArg(def.Args, "max_html_rows", 0); v < 0 {
+		return Job{}, fmt.Errorf("max_html_rows must be >= 0 for table-diff jobs, got %d", v)
+	} else if v > 0 {
+		base.MaxHTMLRows = int64(v)
+	}
 	base.MaxConnections = intArg(def.Args, "max_connections", 0)
 	if out := stringArg(def.Args, "output"); out != "" {
 		base.Output = out
diff --git a/pkg/config/config.go b/pkg/config/config.go
index 5eb4673..1516034 100644
--- a/pkg/config/config.go
+++ b/pkg/config/config.go
@@ -47,6 +47,7 @@ type PostgresConfig struct {
 type DiffConfig struct {
 	ConcurrencyFactor float64 `yaml:"concurrency_factor"`
 	MaxDiffRows       int64   `yaml:"max_diff_rows"`
+	MaxHTMLRows       int64   `yaml:"max_html_rows"`
 	MinBlockSize      int     `yaml:"min_diff_block_size"`
 	MaxBlockSize      int     `yaml:"max_diff_block_size"`
 	DiffBlockSize     int     `yaml:"diff_block_size"`
@@ -81,6 +82,7 @@ type MTreeConfig struct {
 		BlockSize    int   `yaml:"block_size"`
 		MaxBlockSize int   `yaml:"max_block_size"`
 		MaxDiffRows  int64 `yaml:"max_diff_rows"`
+		MaxHTMLRows  int64 `yaml:"max_html_rows"`
 	} `yaml:"diff"`
 }
 

From c476dadeb4231a0df1dbf7d4e6eb2f210aa821c2 Mon Sep 17 00:00:00 2001
From: Andrei Lepikhov <lepihov@gmail.com>
Date: Thu, 24 Sep 2026 15:52:22 +0200
Subject: [PATCH 5/7] Document the HTML report limit

The table-diff and mtree table-diff docs describe --max-html-rows and
the max_html_rows keys, what a truncated report shows, and what a
repair plan built on a truncated page does: rules only for the shown
rows and default_action: skip for the rest. They also state the known
limit for three or more nodes, where a plan rule acts on a key in every
node pair.

The CHANGELOG lists the OOM fix, the exact keys in repair plans, and the
stable key order.
---
 docs/CHANGELOG.md                       | 24 ++++++++++++++++++++++++
 docs/commands/diff/table-diff.md        | 20 ++++++++++++++++++++
 docs/commands/mtree/mtree-table-diff.md |  8 ++++++++
 3 files changed, 52 insertions(+)

diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index 6be6843..7967e02 100644
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@@ -5,6 +5,30 @@ All notable changes to ACE will be captured in this document. This project follo
 ## [Unreleased]
 
 ### Fixed
+- **`table-diff --output html` was killed by the OOM killer on large diffs.**
+  The HTML writer built the whole report in memory: a copy of the diff as
+  JSON, the markup of every row, and the final document in one buffer. With
+  several kilobytes of markup per row, a diff of 493,200 rows used about 4 GB
+  before the process was killed.
+  The writer now streams the report to disk one row at a time. It also shows
+  at most `max_html_rows` rows for each node pair (default `10000`, set in
+  `table_diff` and `mtree.diff` in `ace.yaml`, or with `--max-html-rows`),
+  because a report with hundreds of thousands of rows is too large for a
+  browser anyway. A truncated report says so at the top and in each node pair
+  section. A repair plan built in it has rules only for the rows shown and
+  `default_action: skip`, so `table-repair` does not change the rows that the
+  report did not show; the YAML starts with a comment that says this. With
+  three or more nodes this holds per key only: a plan rule is not tied to a
+  node pair, so it also acts on a key that the report hides in another pair.
+  The JSON report is not changed and always contains every row.
+- **HTML report: repair plans named the wrong rows for some primary keys.**
+  The page script read keys as JavaScript numbers, so a bigint above 2^53
+  could name the neighbouring row, and a text key such as `"007"` became the
+  number 7 and matched nothing. The plan now uses the keys exactly as the
+  diff file has them.
+- **HTML report: rows with primary keys that mix numbers and text were sorted
+  in a different order on each run.** The key comparison now puts numbers
+  before text, so the order is stable.
 - **Spock `add_node` failed on clusters where `mtree init` had been run.**
   `mtree init` created a `#` operator on `bytea_xor` without a schema name, so
   it landed in `public` while the function stayed in the ACE schema. Spock's
diff --git a/docs/commands/diff/table-diff.md b/docs/commands/diff/table-diff.md
index 4bf941c..d30d154 100644
--- a/docs/commands/diff/table-diff.md
+++ b/docs/commands/diff/table-diff.md
@@ -20,6 +20,7 @@ This command compares the data in the specified table across nodes in a cluster
 | `--concurrency-factor <float>` | `-c` | CPU ratio for concurrency (0.0–4.0, e.g. 0.5 uses half of available CPUs). Default `0.5`. |
 | `--compare-unit-size <int>` | `-u` | Recursive split size for mismatched blocks. Default `10000`. |
 | `--output <json\|html>` | `-o` | Report format. Default `json`. When `html`, both JSON and HTML files share the same timestamped prefix. |
+| `--max-html-rows <int>` |  | Maximum number of rows for each node pair in the HTML report. Default `0`, which means `table_diff.max_html_rows` from `ace.yaml`, or `10000` when that is not set either. There is no setting for "no limit"; set a large number instead. The JSON report always contains every row. |
 | `--nodes <list>` | `-n` | Comma-separated node list or `all`. Up to three-way diffs are supported. |
 | `--table-filter <WHERE>` | `-F` | Optional SQL `WHERE` clause applied on every node before hashing. |
 | `--against-origin <node>` |  | Limit the diff to rows whose `node_origin` matches this Spock node id or name (useful for failed-node recovery). |
@@ -119,6 +120,25 @@ ace table-diff my-cluster public._events \
       summary as both the raw filter and the effective filter (which also
       includes `--against-origin`/`--until` if set).
 3. Prefer `--output html` when you'll manually review diffs.
+    - The HTML report shows at most `max_html_rows` rows for each node pair
+      (default `10000`). A row is one primary key: a value difference or a
+      row missing on one node. Each row takes several kilobytes of markup, so
+      a report with hundreds of thousands of rows is too large for a browser.
+      When the diff has more rows, the report says so at the top and in each
+      node pair section, and the full list stays in the JSON file. Rows are
+      taken in report order: value differences, then rows missing on the
+      second node, then rows missing on the first node.
+    - A repair plan that you build in a truncated report has rules only for
+      the rows shown, and its `default_action` is `skip`. So when you run
+      `table-repair` with that plan and the full diff file, the rows that the
+      report did not show are not changed. The downloaded YAML starts with a
+      comment that says this. To repair every row, run `table-diff` again with
+      a larger `--max-html-rows`, or write the plan by hand.
+    - Known limit: a plan rule matches a primary key and a kind of
+      difference, not a node pair. With three or more nodes, a rule for a
+      key shown in one pair also acts on the same key in another pair, even
+      where the report hides it there. Check such keys before you run
+      `table-repair`.
 4. Use `--override-block-size` sparingly; the guardrails in `ace.yaml` prevent
    allocations that can overwhelm memory.
 5. The `max_diff_rows` setting caps the number of differing rows that
diff --git a/docs/commands/mtree/mtree-table-diff.md b/docs/commands/mtree/mtree-table-diff.md
index 363cda0..60b57d3 100644
--- a/docs/commands/mtree/mtree-table-diff.md
+++ b/docs/commands/mtree/mtree-table-diff.md
@@ -31,6 +31,7 @@ holding the node's slot, then re-run, if you need a guaranteed-current drain.
 | `--nodes` | `-n` | Nodes to include (comma or `all`) | `all` |
 | `--max-cpu-ratio` | `-m` | Max CPU ratio | `0.5` |
 | `--output` | `-o` | `json` or `html` | `json` |
+| `--max-html-rows` |  | Max rows per node pair in the HTML report (`0` = use `mtree.diff.max_html_rows`, or `10000`) | `0` |
 | `--skip-cdc` | `-U` | Skip CDC processing (only rehash and compare) | `false` |
 | `--cdc-timeout` |  | Seconds to drain CDC before giving up (`0` = use `cdc_processing_timeout` / default) | `0` |
 | `--quiet` | `-q` | Suppress output | `false` |
@@ -45,6 +46,13 @@ holding the node's slot, then re-run, if you need a guaranteed-current drain.
 **Notes**
 
 - With `--output html`, both JSON and HTML reports are generated with matching timestamps.
+- The HTML report shows at most `max_html_rows` rows for each node pair
+  (`mtree.diff.max_html_rows`, default `10000`). The JSON report always
+  contains every row. When the HTML report is truncated, it says so, and a
+  repair plan built in it has rules only for the rows shown and
+  `default_action: skip`, so `table-repair` does not change the other rows.
+  With three or more nodes this holds per key, not per node pair: see the
+  known limit in the `table-diff` docs.
 - The number of differing rows collected per node pair is bounded by
   `mtree.diff.max_diff_rows` (the shipped `ace.yaml` sets `1000000`; if the key
   is absent or `0`, the diff is unbounded). When the cap is reached, enumeration

From 6d890bd1bb7df0b68e84230e40e993436543e5ca Mon Sep 17 00:00:00 2001
From: Andrei Lepikhov <lepihov@gmail.com>
Date: Thu, 24 Sep 2026 16:15:10 +0200
Subject: [PATCH 6/7] Split the HTML report writer into smaller functions

Codacy flagged five functions of the new report code as too complex
(cyclomatic complexity above 8, or more than 50 lines). The behaviour
does not change: for the same diff, the page markup and the embedded
data are the same bytes as before.

- renderHTMLDiffReport and writeHTMLPair had an error check after every
  template block. A small htmlBlockWriter now keeps the first error and
  skips the rest, so one check at the end is enough. The pair plans, the
  page head and the report info are built in their own functions, and
  the value rows and the missing rows of a pair are written by two.
- buildHTMLPairPlan: finding the node names, indexing the rows of one
  node, and sorting the rows into their lists are now three helpers.
- writeHTMLDiffData and buildHTMLSummaryItems got one helper each, to
  stay under the same limits.
- In the page script, collectRows and buildPKMatchers each give part of
  their work to a helper: picking the rows once per key, the default
  action of a row, and the ranges over whole numbers.

One error message changes: a failure in any part of the page now reads
"failed to write HTML diff report".
---
 pkg/common/html_reporter.go         | 412 ++++++++++++++++------------
 pkg/common/templates/diff_report.js |  78 +++---
 2 files changed, 275 insertions(+), 215 deletions(-)

diff --git a/pkg/common/html_reporter.go b/pkg/common/html_reporter.go
index 07223d5..a25ef50 100644
--- a/pkg/common/html_reporter.go
+++ b/pkg/common/html_reporter.go
@@ -285,60 +285,75 @@ func htmlIntegerPK(plans []*htmlPairPlan, primaryKey []string) bool {
 // left out, as before; writeHTMLPair reports how many. It returns nil when
 // the pair has no rows to show.
 func buildHTMLPairPlan(pairKey string, nodeDiff types.DiffByNodePair, primaryKey []string) *htmlPairPlan {
-	nodeNames := strings.Split(pairKey, "/")
-	if len(nodeNames) != 2 {
-		nodeNames = nodeNames[:0]
-		for name := range nodeDiff.Rows {
-			nodeNames = append(nodeNames, name)
-		}
-		sort.Strings(nodeNames)
-		if len(nodeNames) < 2 {
-			return nil
-		}
-	}
-
-	p := &htmlPairPlan{
-		pairKey: pairKey,
-		nodeA:   nodeNames[0],
-		nodeB:   nodeNames[1],
+	nodeA, nodeB, ok := pairNodeNames(pairKey, nodeDiff)
+	if !ok {
+		return nil
 	}
-	rowsA := nodeDiff.Rows[p.nodeA]
-	rowsB := nodeDiff.Rows[p.nodeB]
+	rowsA := nodeDiff.Rows[nodeA]
+	rowsB := nodeDiff.Rows[nodeB]
 	if len(rowsA) == 0 && len(rowsB) == 0 {
 		return nil
 	}
 
-	p.columns = collectColumnsInOrder(primaryKey, rowsA, rowsB)
-
-	// Two keys per row, and they are not interchangeable. buildRowKey is
-	// the collision-proof identity used to pair a row on A with the same
-	// row on B; buildRowDisplayKey is the plain rendering shown in the
-	// report and embedded in data-pk, which the report's own JavaScript
-	// interpolates into a CSS attribute selector and so cannot carry the
-	// quotes the identity encoding adds.
-	p.display = make(map[string]string, len(rowsA)+len(rowsB))
+	p := &htmlPairPlan{
+		pairKey: pairKey,
+		nodeA:   nodeA,
+		nodeB:   nodeB,
+		columns: collectColumnsInOrder(primaryKey, rowsA, rowsB),
+		display: make(map[string]string, len(rowsA)+len(rowsB)),
+	}
+	p.rowMapA = p.indexRows(rowsA, primaryKey)
+	p.rowMapB = p.indexRows(rowsB, primaryKey)
+	p.classifyRows()
+	return p
+}
 
-	p.rowMapA = make(map[string]types.OrderedMap, len(rowsA))
-	for idx, row := range rowsA {
-		key := buildRowKey(row, primaryKey, idx)
-		p.rowMapA[key] = row
-		p.display[key] = buildRowDisplayKey(row, primaryKey, idx)
+// pairNodeNames returns the two nodes of a pair: from the "nodeA/nodeB" key,
+// or, if the key has another form, from the sorted node names of its rows.
+func pairNodeNames(pairKey string, nodeDiff types.DiffByNodePair) (string, string, bool) {
+	if names := strings.Split(pairKey, "/"); len(names) == 2 {
+		return names[0], names[1], true
+	}
+	names := make([]string, 0, len(nodeDiff.Rows))
+	for name := range nodeDiff.Rows {
+		names = append(names, name)
 	}
+	if len(names) < 2 {
+		return "", "", false
+	}
+	sort.Strings(names)
+	return names[0], names[1], true
+}
 
-	p.rowMapB = make(map[string]types.OrderedMap, len(rowsB))
-	for idx, row := range rowsB {
+// indexRows maps the rows of one node by their identity key and records the
+// display key of each.
+//
+// Two keys per row, and they are not interchangeable. buildRowKey is the
+// collision-proof identity used to pair a row on A with the same row on B;
+// buildRowDisplayKey is the plain rendering shown in the report and embedded
+// in data-pk, which the report's own JavaScript interpolates into a CSS
+// attribute selector and so cannot carry the quotes the identity encoding
+// adds.
+func (p *htmlPairPlan) indexRows(rows []types.OrderedMap, primaryKey []string) map[string]types.OrderedMap {
+	byKey := make(map[string]types.OrderedMap, len(rows))
+	for idx, row := range rows {
 		key := buildRowKey(row, primaryKey, idx)
-		p.rowMapB[key] = row
+		byKey[key] = row
 		p.display[key] = buildRowDisplayKey(row, primaryKey, idx)
 	}
+	return byKey
+}
 
+// classifyRows puts every row into valueKeys, missingInB or missingInA, and
+// sorts each list.
+func (p *htmlPairPlan) classifyRows() {
 	for key, rowA := range p.rowMapA {
-		if rowB, ok := p.rowMapB[key]; ok {
-			if rowsDiffer(rowA, rowB, p.columns) {
-				p.valueKeys = append(p.valueKeys, key)
-			}
-		} else {
+		rowB, ok := p.rowMapB[key]
+		switch {
+		case !ok:
 			p.missingInB = append(p.missingInB, key)
+		case rowsDiffer(rowA, rowB, p.columns):
+			p.valueKeys = append(p.valueKeys, key)
 		}
 	}
 	for key := range p.rowMapB {
@@ -350,7 +365,6 @@ func buildHTMLPairPlan(pairKey string, nodeDiff types.DiffByNodePair, primaryKey
 	sortPKKeys(p.valueKeys, p.display)
 	sortPKKeys(p.missingInA, p.display)
 	sortPKKeys(p.missingInB, p.display)
-	return p
 }
 
 func (p *htmlPairPlan) valueRow(key string, pkSet map[string]struct{}) htmlRow {
@@ -448,7 +462,21 @@ func buildHTMLSummaryItems(summary types.DiffSummary, shown, total int, truncate
 		htmlSummaryItem{Label: "Start Time", Value: formatTimestampHuman(summary.StartTime)},
 		htmlSummaryItem{Label: "End Time", Value: formatTimestampHuman(summary.EndTime)},
 	)
+	items = append(items, summaryLimitItems(summary)...)
+
+	var filtered []htmlSummaryItem
+	for _, item := range items {
+		if item.Value != "" && item.Value != "0" {
+			filtered = append(filtered, item)
+		}
+	}
+	return filtered
+}
 
+// summaryLimitItems returns the summary items that tell the reader the diff
+// may be incomplete.
+func summaryLimitItems(summary types.DiffSummary) []htmlSummaryItem {
+	var items []htmlSummaryItem
 	if summary.MaxDiffRows > 0 {
 		items = append(items, htmlSummaryItem{
 			Label: "Max Diff Rows",
@@ -471,14 +499,7 @@ func buildHTMLSummaryItems(summary types.DiffSummary, shown, total int, truncate
 			Value: strings.Join(summary.IncompletePairs, ", ") + " (counts are lower bounds)",
 		})
 	}
-
-	var filtered []htmlSummaryItem
-	for _, item := range items {
-		if item.Value != "" && item.Value != "0" {
-			filtered = append(filtered, item)
-		}
-	}
-	return filtered
+	return items
 }
 
 // writeHTMLDiffReport writes the HTML report next to the JSON report. It shows
@@ -514,6 +535,25 @@ func writeHTMLDiffReport(diffResult types.DiffOutput, jsonFilePath string, maxRo
 	return path, nil
 }
 
+// htmlBlockWriter runs template blocks and other writes, and keeps the first
+// error. After an error it does nothing more, so a long run of writes needs a
+// single check at the end.
+type htmlBlockWriter struct {
+	tmpl *template.Template
+	w    *bufio.Writer
+	err  error
+}
+
+func (b *htmlBlockWriter) do(fn func() error) {
+	if b.err == nil {
+		b.err = fn()
+	}
+}
+
+func (b *htmlBlockWriter) block(name string, data any) {
+	b.do(func() error { return b.tmpl.ExecuteTemplate(b.w, name, data) })
+}
+
 // renderHTMLDiffReport writes the report to out. diffFile is the name of the
 // JSON report, which the page refers to for the full diff.
 //
@@ -525,48 +565,85 @@ func renderHTMLDiffReport(out io.Writer, diffResult types.DiffOutput, diffFile s
 	if maxRows <= 0 {
 		maxRows = DefaultMaxHTMLRows
 	}
-
 	tmpl, err := template.New("tableDiffReport").Parse(htmlDiffTemplate)
 	if err != nil {
 		return fmt.Errorf("failed to parse HTML template: %w", err)
 	}
 
 	summary := diffResult.Summary
+	// The page header says whether the report is truncated, so every pair
+	// must be counted before the first byte is written.
+	plans := buildHTMLPairPlans(diffResult, maxRows)
+	head, info := buildHTMLReportHead(summary, plans, diffFile, maxRows)
 	pkSet := make(map[string]struct{}, len(summary.PrimaryKey))
 	for _, col := range summary.PrimaryKey {
 		pkSet[col] = struct{}{}
 	}
 
+	w := bufio.NewWriterSize(out, htmlWriteBufferSize)
+	bw := &htmlBlockWriter{tmpl: tmpl, w: w}
+	bw.block("report_head", head)
+	if len(plans) == 0 {
+		bw.block("no_pairs", nil)
+	}
+	for _, p := range plans {
+		writeHTMLPair(bw, p, summary, pkSet, diffFile)
+	}
+	bw.do(func() error { return writeHTMLDiffData(w, summary, plans, info) })
+	bw.block("report_tail", htmlReportTail{JS: template.JS(htmlDiffJS)})
+	bw.do(w.Flush)
+	if bw.err != nil {
+		return fmt.Errorf("failed to write HTML diff report: %w", bw.err)
+	}
+	return nil
+}
+
+// buildHTMLPairPlans builds the plan of every pair that has rows, in pair
+// order, and applies the row limit to each.
+func buildHTMLPairPlans(diffResult types.DiffOutput, maxRows int64) []*htmlPairPlan {
 	pairKeys := make([]string, 0, len(diffResult.NodeDiffs))
 	for key := range diffResult.NodeDiffs {
 		pairKeys = append(pairKeys, key)
 	}
 	sort.Strings(pairKeys)
 
-	// The page header says whether the report is truncated, so every pair
-	// must be counted before the first byte is written.
 	var plans []*htmlPairPlan
-	var shownAll, totalAll int
 	for _, pairKey := range pairKeys {
-		p := buildHTMLPairPlan(pairKey, diffResult.NodeDiffs[pairKey], summary.PrimaryKey)
+		p := buildHTMLPairPlan(pairKey, diffResult.NodeDiffs[pairKey], diffResult.Summary.PrimaryKey)
 		if p == nil {
 			continue
 		}
 		p.applyLimit(maxRows)
+		plans = append(plans, p)
+	}
+	return plans
+}
+
+// buildHTMLReportHead returns the data of the page head and the report info
+// for the page script. Both say whether the report is truncated.
+func buildHTMLReportHead(summary types.DiffSummary, plans []*htmlPairPlan, diffFile string, maxRows int64) (htmlReportHead, htmlReportInfo) {
+	info := htmlReportInfo{
+		MaxRows:   maxRows,
+		DiffFile:  diffFile,
+		IntegerPK: htmlIntegerPK(plans, summary.PrimaryKey),
+		Pairs:     make([]htmlPairInfo, 0, len(plans)),
+	}
+	var shownAll, totalAll int
+	for _, p := range plans {
 		shownAll += p.shown()
 		totalAll += p.total()
-		plans = append(plans, p)
+		info.Pairs = append(info.Pairs, htmlPairInfo{Pair: p.pairKey, Shown: p.shown(), Total: p.total()})
 	}
-	truncated := shownAll < totalAll
+	info.Truncated = shownAll < totalAll
 
 	head := htmlReportHead{
 		CSS: template.CSS(htmlDiffCSS),
 		Summary: htmlSummaryData{
-			Items:     buildHTMLSummaryItems(summary, shownAll, totalAll, truncated),
+			Items:     buildHTMLSummaryItems(summary, shownAll, totalAll, info.Truncated),
 			Breakdown: buildDiffBreakdown(summary.DiffRowsCount),
 		},
 	}
-	if truncated {
+	if info.Truncated {
 		head.Truncation = &htmlTruncation{
 			Shown:    formatInt64WithCommas(int64(shownAll)),
 			Total:    formatInt64WithCommas(int64(totalAll)),
@@ -576,50 +653,22 @@ func renderHTMLDiffReport(out io.Writer, diffResult types.DiffOutput, diffFile s
 		logger.Warn("HTML report shows %d of %d rows (max_html_rows=%d per node pair); the full diff is in %s",
 			shownAll, totalAll, maxRows, diffFile)
 	}
-
-	w := bufio.NewWriterSize(out, htmlWriteBufferSize)
-	if err := tmpl.ExecuteTemplate(w, "report_head", head); err != nil {
-		return fmt.Errorf("failed to render HTML diff report: %w", err)
-	}
-	if len(plans) == 0 {
-		if err := tmpl.ExecuteTemplate(w, "no_pairs", nil); err != nil {
-			return fmt.Errorf("failed to render HTML diff report: %w", err)
-		}
-	}
-	for _, p := range plans {
-		if err := writeHTMLPair(tmpl, w, p, summary, pkSet, diffFile); err != nil {
-			return fmt.Errorf("failed to render HTML diff report: %w", err)
-		}
-	}
-
-	info := htmlReportInfo{
-		Truncated: truncated,
-		MaxRows:   maxRows,
-		DiffFile:  diffFile,
-		IntegerPK: htmlIntegerPK(plans, summary.PrimaryKey),
-		Pairs:     make([]htmlPairInfo, 0, len(plans)),
-	}
-	for _, p := range plans {
-		info.Pairs = append(info.Pairs, htmlPairInfo{Pair: p.pairKey, Shown: p.shown(), Total: p.total()})
-	}
-	if err := writeHTMLDiffData(w, summary, plans, info, summary.PrimaryKey); err != nil {
-		return fmt.Errorf("failed to embed diff data in HTML report: %w", err)
-	}
-
-	if err := tmpl.ExecuteTemplate(w, "report_tail", htmlReportTail{JS: template.JS(htmlDiffJS)}); err != nil {
-		return fmt.Errorf("failed to render HTML diff report: %w", err)
-	}
-	if err := w.Flush(); err != nil {
-		return fmt.Errorf("failed to write HTML diff report: %w", err)
-	}
-	return nil
+	return head, info
 }
 
 // writeHTMLPair writes the section of one node pair, one row at a time.
-func writeHTMLPair(tmpl *template.Template, w io.Writer, p *htmlPairPlan, summary types.DiffSummary, pkSet map[string]struct{}, diffFile string) error {
-	// Every count in the section comes from the plan, so the numbers on the
-	// page always add up. The engine's own count can be higher; the note
-	// below says why.
+func writeHTMLPair(bw *htmlBlockWriter, p *htmlPairPlan, summary types.DiffSummary, pkSet map[string]struct{}, diffFile string) {
+	head := p.pairHead(summary, diffFile)
+	bw.block("pair_head", head)
+	writeHTMLValueRows(bw, p, pkSet)
+	writeHTMLMissingRows(bw, p, pkSet)
+	bw.block("pair_tail", head)
+}
+
+// pairHead returns the data of the pair head and tail. Every count in the
+// section comes from the plan, so the numbers on the page always add up. The
+// engine's own count can be higher; NotRendered says by how much.
+func (p *htmlPairPlan) pairHead(summary types.DiffSummary, diffFile string) htmlPairHead {
 	counted := summary.DiffRowsCount[p.pairKey]
 	head := htmlPairHead{
 		NodeA:     p.nodeA,
@@ -637,56 +686,53 @@ func writeHTMLPair(tmpl *template.Template, w io.Writer, p *htmlPairPlan, summar
 	if notRendered := counted - p.total(); notRendered > 0 {
 		head.NotRendered = formatInt64WithCommas(int64(notRendered))
 	}
+	return head
+}
 
-	if err := tmpl.ExecuteTemplate(w, "pair_head", head); err != nil {
-		return err
+func writeHTMLValueRows(bw *htmlBlockWriter, p *htmlPairPlan, pkSet map[string]struct{}) {
+	if p.shownValue == 0 {
+		return
 	}
-
-	if p.shownValue > 0 {
-		if err := tmpl.ExecuteTemplate(w, "separator", "Value Differences"); err != nil {
-			return err
-		}
-		for i, key := range p.valueKeys[:p.shownValue] {
-			row := p.valueRow(key, pkSet)
-			row.First = i == 0
-			if err := tmpl.ExecuteTemplate(w, "value_row", row); err != nil {
-				return err
-			}
+	bw.block("separator", "Value Differences")
+	for i, key := range p.valueKeys[:p.shownValue] {
+		if bw.err != nil {
+			return
 		}
+		row := p.valueRow(key, pkSet)
+		row.First = i == 0
+		bw.block("value_row", row)
 	}
+}
 
-	if p.shownMissingB > 0 || p.shownMissingA > 0 {
-		if err := tmpl.ExecuteTemplate(w, "separator", "Missing Rows"); err != nil {
-			return err
-		}
-		groups := []struct {
-			keys       []string
-			missingInB bool
-			title      string
-		}{
-			{p.missingInB[:p.shownMissingB], true, "Missing in " + p.nodeB},
-			{p.missingInA[:p.shownMissingA], false, "Missing in " + p.nodeA},
+func writeHTMLMissingRows(bw *htmlBlockWriter, p *htmlPairPlan, pkSet map[string]struct{}) {
+	if p.shownMissingB == 0 && p.shownMissingA == 0 {
+		return
+	}
+	bw.block("separator", "Missing Rows")
+	groups := []struct {
+		keys       []string
+		missingInB bool
+		title      string
+	}{
+		{p.missingInB[:p.shownMissingB], true, "Missing in " + p.nodeB},
+		{p.missingInA[:p.shownMissingA], false, "Missing in " + p.nodeA},
+	}
+	groupWritten := false
+	for _, g := range groups {
+		if len(g.keys) == 0 {
+			continue
 		}
-		groupWritten := false
-		for _, g := range groups {
-			if len(g.keys) == 0 {
-				continue
-			}
-			if err := tmpl.ExecuteTemplate(w, "group_head", htmlGroupHead{Title: g.title, DividerBefore: groupWritten}); err != nil {
-				return err
-			}
-			groupWritten = true
-			for i, key := range g.keys {
-				row := p.missingRow(key, g.missingInB, pkSet)
-				row.First = i == 0
-				if err := tmpl.ExecuteTemplate(w, "missing_row", row); err != nil {
-					return err
-				}
+		bw.block("group_head", htmlGroupHead{Title: g.title, DividerBefore: groupWritten})
+		groupWritten = true
+		for i, key := range g.keys {
+			if bw.err != nil {
+				return
 			}
+			row := p.missingRow(key, g.missingInB, pkSet)
+			row.First = i == 0
+			bw.block("missing_row", row)
 		}
 	}
-
-	return tmpl.ExecuteTemplate(w, "pair_tail", head)
 }
 
 // writeHTMLDiffData embeds the data that the page script needs to build a
@@ -696,53 +742,20 @@ func writeHTMLPair(tmpl *template.Template, w io.Writer, p *htmlPairPlan, summar
 //
 // json.Marshal escapes '<', '>' and '&', so no value can close the script
 // element early.
-func writeHTMLDiffData(w *bufio.Writer, summary types.DiffSummary, plans []*htmlPairPlan, info htmlReportInfo, primaryKey []string) error {
-	writeJSON := func(v any) error {
-		b, err := json.Marshal(v)
-		if err != nil {
-			return err
-		}
-		w.Write(b)
-		return nil
-	}
-
+func writeHTMLDiffData(w *bufio.Writer, summary types.DiffSummary, plans []*htmlPairPlan, info htmlReportInfo) error {
 	w.WriteString(`<script id="diff-data" type="application/json">{"summary":`)
-	if err := writeJSON(summary); err != nil {
+	if err := writeJSONTo(w, summary); err != nil {
 		return err
 	}
 	w.WriteString(`,"html_report":`)
-	if err := writeJSON(info); err != nil {
+	if err := writeJSONTo(w, info); err != nil {
 		return err
 	}
 	w.WriteString(`,"rows":[`)
 	first := true
 	for _, p := range plans {
-		lists := []struct {
-			keys     []string
-			rows     map[string]types.OrderedMap
-			planType string
-		}{
-			{p.valueKeys[:p.shownValue], p.rowMapA, planTypeMismatch},
-			{p.missingInB[:p.shownMissingB], p.rowMapA, planTypeMissingN2},
-			{p.missingInA[:p.shownMissingA], p.rowMapB, planTypeMissingN1},
-		}
-		for _, l := range lists {
-			for _, key := range l.keys {
-				if !first {
-					w.WriteByte(',')
-				}
-				first = false
-				if err := writeJSON(htmlPlanRow{
-					Pair:  p.pairKey,
-					NodeA: p.nodeA,
-					NodeB: p.nodeB,
-					Key:   p.display[key],
-					Type:  l.planType,
-					PK:    pkLiterals(l.rows[key], primaryKey),
-				}); err != nil {
-					return err
-				}
-			}
+		if err := p.writePlanRows(w, summary.PrimaryKey, &first); err != nil {
+			return err
 		}
 	}
 	// bufio.Writer keeps the first write error and returns it from every
@@ -751,6 +764,49 @@ func writeHTMLDiffData(w *bufio.Writer, summary types.DiffSummary, plans []*html
 	return err
 }
 
+// writePlanRows writes the htmlPlanRow of every shown row of the pair. first
+// tells whether no row has been written yet, across all pairs.
+func (p *htmlPairPlan) writePlanRows(w *bufio.Writer, primaryKey []string, first *bool) error {
+	lists := []struct {
+		keys     []string
+		rows     map[string]types.OrderedMap
+		planType string
+	}{
+		{p.valueKeys[:p.shownValue], p.rowMapA, planTypeMismatch},
+		{p.missingInB[:p.shownMissingB], p.rowMapA, planTypeMissingN2},
+		{p.missingInA[:p.shownMissingA], p.rowMapB, planTypeMissingN1},
+	}
+	for _, l := range lists {
+		for _, key := range l.keys {
+			if !*first {
+				w.WriteByte(',')
+			}
+			*first = false
+			row := htmlPlanRow{
+				Pair:  p.pairKey,
+				NodeA: p.nodeA,
+				NodeB: p.nodeB,
+				Key:   p.display[key],
+				Type:  l.planType,
+				PK:    pkLiterals(l.rows[key], primaryKey),
+			}
+			if err := writeJSONTo(w, row); err != nil {
+				return err
+			}
+		}
+	}
+	return nil
+}
+
+func writeJSONTo(w *bufio.Writer, v any) error {
+	b, err := json.Marshal(v)
+	if err != nil {
+		return err
+	}
+	_, err = w.Write(b)
+	return err
+}
+
 func highlightDifference(a, b string) (template.HTML, template.HTML) {
 	if a == b {
 		esc := template.HTMLEscapeString(a)
diff --git a/pkg/common/templates/diff_report.js b/pkg/common/templates/diff_report.js
index 4073a06..99e4963 100644
--- a/pkg/common/templates/diff_report.js
+++ b/pkg/common/templates/diff_report.js
@@ -354,33 +354,34 @@
     // key such as "007" into the number 7.
     function collectRows(diff, targetKeys, rowDefault, planDefault) {
         const rows = [];
-        const seen = new Set();
-
-        for (const r of (diff.rows || [])) {
-            const key = r.key;
-            if (seen.has(key)) continue;
-            seen.add(key);
-            if (targetKeys && !targetKeys.has(key)) continue;
-
-            let action = selectionForKey(key);
-            if (!action) {
-                if (r.type === 'missing_on_n2') {
-                    action = { type: 'apply_from', from: r.node_a, mode: 'insert' };
-                } else if (r.type === 'missing_on_n1') {
-                    action = { type: 'apply_from', from: r.node_b, mode: 'insert' };
-                } else {
-                    action = rowDefault;
-                }
-            }
-
+        for (const r of uniqueTargetRows(diff, targetKeys)) {
+            const action = selectionForKey(r.key) || defaultActionFor(r, rowDefault);
             // Skip emitting explicit instructions for rows that match the table default.
-            const matchesDefault = isSameAction(action, planDefault) && r.type === 'row_mismatch';
-            if (matchesDefault) continue;
+            if (r.type === 'row_mismatch' && isSameAction(action, planDefault)) continue;
+            rows.push({ key: r.key, pkTuple: r.pk, action, diffType: r.type });
+        }
+        return rows;
+    }
 
-            rows.push({ key, pkTuple: r.pk, action, diffType: r.type });
+    // uniqueTargetRows returns the embedded rows once per key, and only the
+    // selected ones when targetKeys is set.
+    function uniqueTargetRows(diff, targetKeys) {
+        const seen = new Set();
+        const out = [];
+        for (const r of (diff.rows || [])) {
+            if (seen.has(r.key)) continue;
+            seen.add(r.key);
+            if (targetKeys && !targetKeys.has(r.key)) continue;
+            out.push(r);
         }
+        return out;
+    }
 
-        return rows;
+    // defaultActionFor is what "Default" means for the row on the page.
+    function defaultActionFor(r, rowDefault) {
+        if (r.type === 'missing_on_n2') return { type: 'apply_from', from: r.node_a, mode: 'insert' };
+        if (r.type === 'missing_on_n1') return { type: 'apply_from', from: r.node_b, mode: 'insert' };
+        return rowDefault;
     }
 
     function groupRows(rows, pkCols) {
@@ -401,20 +402,20 @@
     // buildPKMatchers returns pk_in matchers whose values are JSON literals.
     // Ranges are used only when the Go code says that every key of the diff
     // is a whole number (integerPK): then a range over consecutive shown keys
-    // cannot match any key that is not shown. BigInt keeps bigint keys exact.
+    // cannot match any key that is not shown.
     function buildPKMatchers(pkTuples, pkCols, integerPK) {
         if (!pkTuples.length) return [];
-        if (pkCols.length !== 1) {
-            // Composite PKs: use equals tuples.
-            return [{ equals: pkTuples }];
-        }
-
+        // Composite PKs: use equals tuples.
+        if (pkCols.length !== 1) return [{ equals: pkTuples }];
         const values = Array.from(new Set(pkTuples.map(t => t[0])));
-        if (!integerPK) {
-            return [{ equals: values }];
-        }
+        return integerPK ? integerRangeMatchers(values) : [{ equals: values }];
+    }
 
-        const nums = values.map(v => BigInt(v)).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+    // integerRangeMatchers turns whole-number literals into ranges over runs of
+    // consecutive numbers, and one equals list for the rest. BigInt keeps
+    // bigint keys exact.
+    function integerRangeMatchers(values) {
+        const nums = values.map(v => BigInt(v)).sort(compareBigInt);
         const matchers = [];
         const singles = [];
         let start = nums[0];
@@ -430,15 +431,18 @@
             } else {
                 singles.push(start.toString());
             }
-            if (curr !== undefined) {
-                start = curr;
-                prev = curr;
-            }
+            start = curr;
+            prev = curr;
         }
         if (singles.length) matchers.push({ equals: singles });
         return matchers;
     }
 
+    function compareBigInt(a, b) {
+        if (a < b) return -1;
+        return a > b ? 1 : 0;
+    }
+
     // formatLiteralList writes a flow list of values that are already YAML
     // literals (JSON text), or lists of them.
     function formatLiteralList(values) {

From 9bc3f453a3e3d6e8bd8e8e49ca7b5d31dec648f9 Mon Sep 17 00:00:00 2001
From: Andrei Lepikhov <lepihov@gmail.com>
Date: Thu, 24 Sep 2026 16:15:30 +0200
Subject: [PATCH 7/7] Rename the html_report key of the embedded report data

Codacy reported "Non-HTML variable 'report' is used to store raw HTML"
for `const report = diff.html_report`. The rule judges by names only: a
property whose name has "html" in it is taken to hold markup. This one
holds JSON (truncated, integer_pk, pairs, diff_file), and the page
script only reads its fields into the YAML text of the repair plan. The
script never writes markup into the page.

Call the key report_info, so the check has nothing to match.
---
 pkg/common/html_reporter.go         |  2 +-
 pkg/common/html_reporter_test.go    | 12 ++++++------
 pkg/common/templates/diff_report.js |  2 +-
 3 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/pkg/common/html_reporter.go b/pkg/common/html_reporter.go
index a25ef50..692b83e 100644
--- a/pkg/common/html_reporter.go
+++ b/pkg/common/html_reporter.go
@@ -747,7 +747,7 @@ func writeHTMLDiffData(w *bufio.Writer, summary types.DiffSummary, plans []*html
 	if err := writeJSONTo(w, summary); err != nil {
 		return err
 	}
-	w.WriteString(`,"html_report":`)
+	w.WriteString(`,"report_info":`)
 	if err := writeJSONTo(w, info); err != nil {
 		return err
 	}
diff --git a/pkg/common/html_reporter_test.go b/pkg/common/html_reporter_test.go
index 33ca3c1..589e79c 100644
--- a/pkg/common/html_reporter_test.go
+++ b/pkg/common/html_reporter_test.go
@@ -67,7 +67,7 @@ func htmlTestDiff(valueDiffs, missingOnB, missingOnA int, note string) types.Dif
 
 type htmlTestData struct {
 	Summary    types.DiffSummary `json:"summary"`
-	HTMLReport htmlReportInfo    `json:"html_report"`
+	HTMLReport htmlReportInfo    `json:"report_info"`
 	Rows       []htmlPlanRow     `json:"rows"`
 }
 
@@ -144,7 +144,7 @@ func TestHTMLReportNotTruncated(t *testing.T) {
 	}
 
 	if data.HTMLReport.Truncated {
-		t.Error("html_report.truncated is true for a complete report")
+		t.Error("report_info.truncated is true for a complete report")
 	}
 	if data.HTMLReport.MaxRows != DefaultMaxHTMLRows {
 		t.Errorf("max_html_rows: got %d, want the default %d", data.HTMLReport.MaxRows, DefaultMaxHTMLRows)
@@ -207,10 +207,10 @@ func TestHTMLReportTruncated(t *testing.T) {
 	}
 	info := data.HTMLReport
 	if !info.Truncated || info.MaxRows != 30 || info.DiffFile != "public_t_diffs-20260101000000.json" {
-		t.Errorf("html_report: got %+v", info)
+		t.Errorf("report_info: got %+v", info)
 	}
 	if len(info.Pairs) != 1 || info.Pairs[0] != (htmlPairInfo{Pair: "n1/n2", Shown: 30, Total: 40}) {
-		t.Errorf("html_report.pairs: got %+v", info.Pairs)
+		t.Errorf("report_info.pairs: got %+v", info.Pairs)
 	}
 }
 
@@ -378,7 +378,7 @@ func TestHTMLReportPageAndDataHoldTheSameRows(t *testing.T) {
 			t.Errorf("%s: %d rows, want the limit 8", pc.pair, n)
 		}
 		if info := data.HTMLReport.Pairs[i]; info.Pair != pc.pair || info.Shown != n {
-			t.Errorf("%s: html_report says %+v, page shows %d rows", pc.pair, info, n)
+			t.Errorf("%s: report_info says %+v, page shows %d rows", pc.pair, info, n)
 		}
 	}
 	if data.HTMLReport.Pairs[0].Total != 22 || data.HTMLReport.Pairs[1].Total != 11 {
@@ -505,7 +505,7 @@ func TestHTMLReportRowsWithoutVisibleDifference(t *testing.T) {
 		t.Error("section does not explain the row left out")
 	}
 	if data.HTMLReport.Truncated {
-		t.Error("html_report.truncated is true")
+		t.Error("report_info.truncated is true")
 	}
 }
 
diff --git a/pkg/common/templates/diff_report.js b/pkg/common/templates/diff_report.js
index 99e4963..e355c83 100644
--- a/pkg/common/templates/diff_report.js
+++ b/pkg/common/templates/diff_report.js
@@ -251,7 +251,7 @@
         // saw, so the plan must leave them alone: its default is skip, and
         // every shown row gets an explicit rule. keep_n1 would also be wrong
         // for rows missing on n1, and table-repair rejects the whole plan then.
-        const report = diff.html_report || {};
+        const report = diff.report_info || {};
         const truncated = !!report.truncated;
         const rowDefault = { type: 'keep_n1' };
         const planDefault = truncated ? { type: 'skip' } : rowDefault;