test: expand v4→v5 upgrade matrix with clustering config and hdb_status sub-cases

Closes #1187.

- Adds version matrix comment documenting HARPER_LEGACY_V43_PATH through
  V47_PATH env vars so CI can run the same suite against each v4 minor.
- Adds hdb_status GTM table backward-compat suite: seeds a record via v4,
  upgrades to v5, verifies the record is readable (checks both data and
  system databases in case v5 migrated the table).
- Adds v4.3.x clustering: config key suite: starts v4.3, seeds data, appends
  the old-style `clustering:` YAML block directly to the on-disk config file
  (bypassing HARPER_SET_CONFIG, which predates v4.3), then upgrades to v5 and
  asserts no crash and data survival.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: kriszyp

integrationTests/upgrade/4.x-upgrade.test.ts

@@ -1,6 +1,27 @@
 /**
- * This tests that transaction log replay works on crash. There is a bunch of data written to the system
- * database, so replay needs to work for harper to startup.
+ * Upgrade compatibility tests: v4.x → v5.
+ *
+ * Tests transaction log replay on crash (data written to system DB before kill),
+ * downgrade-and-re-upgrade round-trips, LMDB→RocksDB migration, and v4-specific
+ * backward-compat sub-cases (hdb_status GTM table, clustering: config key).
+ *
+ * ## Version matrix
+ *
+ * The suite is parameterized by env vars pointing at legacy Harper installations:
+ *
+ *   HARPER_LEGACY_VERSION_PATH  — primary; maps to "the v4.x build under test" (any minor)
+ *   HARPER_LEGACY_V43_PATH      — v4.3.x-specific build (for version-gated sub-tests)
+ *   HARPER_LEGACY_V44_PATH      — v4.4.x-specific build
+ *   HARPER_LEGACY_V45_PATH      — v4.5.x-specific build
+ *   HARPER_LEGACY_V46_PATH      — v4.6.x-specific build
+ *   HARPER_LEGACY_V47_PATH      — v4.7.x-specific build
+ *
+ * To run the matrix in CI, launch once per env var, e.g.:
+ *   HARPER_LEGACY_VERSION_PATH=/opt/harper-4.3 npm run test:integration -- upgrade
+ *   HARPER_LEGACY_VERSION_PATH=/opt/harper-4.7 npm run test:integration -- upgrade
+ *
+ * Sub-tests that require a specific minor may use the version-specific var instead
+ * of the generic one, and skip when that var is absent.
  */
 import { suite, test, before, after } from 'node:test';
 import {
@@ -10,9 +31,9 @@ import {
 	type ContextWithHarper,
 	killHarper,
 } from '@harperfast/integration-testing';
-import { ok, deepStrictEqual } from 'node:assert';
+import { ok, deepStrictEqual, strictEqual } from 'node:assert';
 import { join } from 'node:path';
-import { existsSync, readdirSync, statSync } from 'node:fs';
+import { existsSync, readdirSync, statSync, writeFileSync } from 'node:fs';
 
 const WIDGET_COUNT = 60;
 const buildWidgets = () =>
@@ -254,3 +275,200 @@ suite(
 		});
 	}
 );
+
+// ---------------------------------------------------------------------------
+// hdb_status GTM table backward-compat
+//
+// Verifies that a record written to data.hdb_status in v4 is still readable
+// via the v5 REST API after upgrade. Uses HARPER_LEGACY_VERSION_PATH (same
+// as the primary suite) and is skipped when it is absent.
+//
+// Note: hdb_status is a system-managed table; not all v4 minor versions expose
+// it through the public upsert API. The before() hook skips the upsert when the
+// table is absent (table-not-found error), and the test is skipped in that case.
+// ---------------------------------------------------------------------------
+
+let hdbStatusSeeded = false;
+
+suite(
+	'v4->v5: hdb_status GTM table backward-compat',
+	{ skip: !legacyPath || testsBun || process.platform === 'win32' },
+	(ctx: ContextWithHarper) => {
+		before(async () => {
+			await startHarper(ctx, {
+				config: {},
+				env: {
+					TC_AGREEMENT: 'yes',
+					REPLICATION_HOSTNAME: 'localhost',
+				},
+				harperBinPath: join(legacyPath!, 'bin', 'harperdb.js'),
+			});
+
+			// Write a sentinel record to data.hdb_status in v4.
+			// Not all v4 builds expose hdb_status via the operations API; if upsert
+			// fails with a table-not-found-style error we note it and skip assertion below.
+			try {
+				await sendOperation(ctx.harper, {
+					operation: 'upsert',
+					database: 'data',
+					table: 'hdb_status',
+					records: [{ id: 1, status: 200, message: 'ok' }],
+				});
+				hdbStatusSeeded = true;
+			} catch (err: any) {
+				// Table absent on this v4 minor — acceptable; the test will skip.
+				if (
+					!String(err?.message ?? err)
+						.toLowerCase()
+						.includes('not found')
+				)
+					throw err;
+			}
+		});
+
+		after(async () => {
+			await teardownHarper(ctx);
+		});
+
+		test('hdb_status record is readable after upgrade to v5', async (t) => {
+			if (!hdbStatusSeeded) {
+				t.skip('hdb_status table not available via operations API on this v4 build');
+				return;
+			}
+
+			await killHarper(ctx);
+
+			// Start v5 on the same dataRootDir — upgrade directives run automatically.
+			await startHarper(ctx, { config: {}, env: {} });
+
+			// In v4, hdb_status lived in the data database. v5 may migrate it to system.
+			// Try data first; fall back to system so the test covers both locations.
+			let rows: any[] | null = null;
+			try {
+				rows = await sendOperation(ctx.harper, {
+					operation: 'search_by_conditions',
+					database: 'data',
+					table: 'hdb_status',
+					conditions: [{ attribute: 'id', comparator: 'equals', value: 1 }],
+				});
+			} catch {
+				// data.hdb_status may have been migrated to system
+			}
+
+			if (!rows || rows.length === 0) {
+				rows = await sendOperation(ctx.harper, {
+					operation: 'search_by_conditions',
+					database: 'system',
+					table: 'hdb_status',
+					conditions: [{ attribute: 'id', comparator: 'equals', value: 1 }],
+				});
+			}
+
+			ok(
+				Array.isArray(rows) && rows.length === 1,
+				`expected 1 hdb_status row in data or system after upgrade, got ${JSON.stringify(rows)}`
+			);
+			strictEqual(rows![0].status, 200, 'hdb_status.status should be 200 after upgrade');
+			strictEqual(rows![0].message, 'ok', 'hdb_status.message should be "ok" after upgrade');
+		});
+	}
+);
+
+// ---------------------------------------------------------------------------
+// v4.3.x clustering: config key backward-compat
+//
+// v4.3.x used `clustering: { enabled: true, ... }` in harper.json. v5 renamed
+// this key. This test verifies that v5 either migrates the old key gracefully
+// or emits an actionable error — it must not crash silently.
+//
+// Requires HARPER_LEGACY_V43_PATH to point at a v4.3.x installation. Skipped
+// when the env var is absent so the CI matrix can omit the v4.3 slot without
+// breaking the suite.
+// ---------------------------------------------------------------------------
+
+const legacyV43Path = process.env.HARPER_LEGACY_V43_PATH;
+
+suite(
+	'v4.3.x→v5: clustering: config key does not cause silent failure',
+	{ skip: !legacyV43Path || testsBun || process.platform === 'win32' },
+	(ctx: ContextWithHarper) => {
+		before(async () => {
+			// Start v4.3.x without any special config — HARPER_SET_CONFIG is a v5
+			// mechanism that v4.3 predates, so the clustering key must be injected
+			// by writing directly to the on-disk config file after the data dir is
+			// created. The first startHarper call just populates ctx.harper.dataRootDir.
+			await startHarper(ctx, {
+				config: {},
+				env: {
+					TC_AGREEMENT: 'yes',
+					REPLICATION_HOSTNAME: 'localhost',
+				},
+				harperBinPath: join(legacyV43Path!, 'bin', 'harperdb.js'),
+			});
+
+			// Seed a small table so we have something to verify survives.
+			await sendOperation(ctx.harper, {
+				operation: 'create_table',
+				table: 'cluster_compat_test',
+				primary_key: 'id',
+				attributes: [{ name: 'id', type: 'ID' }],
+			});
+			await sendOperation(ctx.harper, {
+				operation: 'upsert',
+				table: 'cluster_compat_test',
+				records: [{ id: 'sentinel' }],
+			});
+
+			// Write the old-style clustering: config key directly into the on-disk
+			// config file so that v5 reads it on startup (not v4 — v4 is already up).
+			// v4.3 used harperdb-config.yaml; fall back to harper-config.yaml if absent.
+			const legacyConfigPath = join(ctx.harper.dataRootDir, 'harperdb-config.yaml');
+			const newConfigPath = join(ctx.harper.dataRootDir, 'harper-config.yaml');
+			const configPath = existsSync(legacyConfigPath) ? legacyConfigPath : newConfigPath;
+
+			// Append the old-style clustering block to the existing config file.
+			// YAML block append: a trailing newline then a top-level clustering key.
+			const clusteringYaml = [
+				'',
+				'# v4.3 legacy clustering key — injected by upgrade compat test',
+				'clustering:',
+				'  enabled: true',
+				'  nodeName: test-node',
+				'  server:',
+				'    port: 12345',
+				'',
+			].join('\n');
+			writeFileSync(configPath, clusteringYaml, { flag: 'a' });
+		});
+
+		after(async () => {
+			await teardownHarper(ctx);
+		});
+
+		test('v5 starts successfully despite old clustering: config key', async () => {
+			await killHarper(ctx);
+
+			// startHarper throws HarperStartupError on non-zero exit or timeout.
+			// A successful return here means Harper started and is ready — no crash.
+			await startHarper(ctx, { config: {}, env: {} });
+
+			ok(
+				ctx.harper.process.exitCode === null,
+				'v5 Harper process must still be running after startup with old clustering config'
+			);
+
+			// Optionally verify seeded data survived: checks data integrity not just
+			// startup, but a silent partial-boot (ready signal before tables open)
+			// would be caught here.
+			const rows = await sendOperation(ctx.harper, {
+				operation: 'search_by_conditions',
+				table: 'cluster_compat_test',
+				conditions: [{ attribute: 'id', comparator: 'equals', value: 'sentinel' }],
+			});
+			ok(
+				Array.isArray(rows) && rows.length === 1,
+				`expected sentinel row to survive upgrade, got ${JSON.stringify(rows)}`
+			);
+		});
+	}
+);