tidy: trim verbose/redundant code comments

De-duplicate the #1135/RangeError/end-of-log rationale that was repeated across the
guard JSDoc, its inline comments, the stress-test helper/body, and the unit-test
header. State each point once in its canonical spot; drop rocksdb-internals detail
that isn't this module's concern. No behavior change.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: heskew

integrationTests/server/replay-stress.test.ts

@@ -135,12 +135,9 @@ function truncateTail(path: string, bytes: number) {
 }
 
 function corruptLastEntryLength(path: string): boolean {
-	// Walk the entry frames to the *last* well-framed entry, then force its declared length
-	// to overrun the log by setting the most-significant byte of its big-endian uint32 length
-	// to 0xff (≥ 4 GB). Targeting the last entry puts the corruption in the unflushed tail
-	// that replay actually reads (replay starts from the last-flushed position), rather than a
-	// flushed prefix it skips over. Deterministic — same frame, same corruption — unlike the
-	// old random byte flips, whose effect depended on what RocksDB had flushed before SIGKILL.
+	// Force the *last* well-framed entry's big-endian uint32 length to overrun the log (top
+	// byte → 0xff, ≥ 4 GB). The last entry sits in the unflushed tail that replay reads
+	// (replay starts from the last-flushed position), so a flushed prefix isn't skipped over.
 	const buf = readFileSync(path);
 	let pos = TRANSACTION_LOG_FILE_HEADER_SIZE;
 	let lastLengthPos = -1;
@@ -218,22 +215,16 @@ suite('Transaction log replay stress', (ctx: ContextWithHarper) => {
 		}
 		let corrupted = 0;
 		await crashAndRestart(ctx, (dataRootDir) => {
-			// User-DB only: corrupting system/ txnlogs trips the version-tracking
-			// upgrade-abort path on next boot — a real but different failure mode.
-			// Here we want the framing-corruption case (#1135): a declared length that
-			// overruns the log used to throw an uncaught RangeError out of the txnlog
-			// iterator and abort startup; replay must now treat it as end-of-log.
+			// User-DB only: corrupting system/ txnlogs trips the upgrade-abort path on next
+			// boot — a different failure mode than the framing corruption (#1135) under test.
 			for (const f of listTxnLogFiles(dataRootDir, { userOnly: true })) {
 				if (corruptLastEntryLength(f)) corrupted++;
 			}
 		});
-		// Fail loudly rather than vacuously pass if the framing ever changes and we corrupt
-		// nothing — otherwise this would silently stop being a regression test for #1135.
+		// Fail loudly, not vacuously, if the framing ever changes and nothing gets corrupted.
 		ok(corrupted > 0, 'expected to corrupt at least one user-DB txnlog');
-		// Behavioral assertion, not a wall-clock budget: crashAndRestart resolving above
-		// means the server came back up (startHarper saw 'successfully started'); a
-		// regression resurfaces as a failed/timed-out restart, not a slow one — so there
-		// is nothing to tune per-runner. Confirm every table is still queryable.
+		// Behavioral, not a wall-clock budget: crashAndRestart resolved → the server came back
+		// up; a regression shows up as a failed restart, not a slow one. Confirm tables queryable.
 		for (const t of TABLES) {
 			const c = await countRows(ctx.harper, t);
 			ok(typeof c === 'number' && c >= 0, `count on ${t} should be a number, got ${c}`);

resources/replayLogsGuards.ts

@@ -42,21 +42,12 @@ export function classifyAuditEntryForReplay(
 }
 
 /**
- * Wraps a transaction-log query iterator so a framing-level corruption error ends
- * iteration of that log cleanly instead of escaping as an uncaughtException.
- *
- * rocksdb-js's txnlog reader throws a bounded `RangeError` when an entry's declared
- * length overruns the log or its header is truncated (intentional hardening — it would
- * otherwise OOM on `allocUnsafe(bogusLength)` or deref an undefined buffer). A torn write
- * at SIGKILL time, or a flipped byte in an unflushed/corrupt log, looks exactly like that.
- * Once the framing is lost we can't locate the next entry, so the corrupt frame marks the
- * usable end of this log (torn-write semantics): entries before it have already been
- * yielded, and startup replay / replication broadcast must continue rather than abort the
- * boot. The latch means a persistently-corrupt log is reported once, not on every re-poll.
- *
- * `onCorruptFrame` is invoked once, with the error, when a corrupt frame is hit — kept as
- * a callback (rather than logging here) so this module stays free of the Harper module
- * graph and the behavior is unit-testable. Non-`RangeError` failures propagate unchanged.
+ * Wraps a transaction-log query iterator so a corrupt/torn frame ends that log's iteration
+ * cleanly instead of escaping as an uncaughtException. rocksdb-js throws a bounded RangeError
+ * when an entry's framing is broken; framing loss means the next entry can't be located, so the
+ * frame marks end-of-log (entries before it were already yielded) and startup replay /
+ * replication broadcast continue. `onCorruptFrame` fires once, latched — kept a callback (not a
+ * direct log) so this module stays out of the Harper module graph and is unit-testable.
  */
 export function endIteratorOnCorruptFrame<T>(
 	iterator: Iterator<T>,
@@ -72,22 +63,16 @@ export function endIteratorOnCorruptFrame<T>(
 			try {
 				return iterator.next();
 			} catch (error) {
-				// rocksdb-js's txnlog reader signals frame corruption with a RangeError; the
-				// message wording is version-dependent (1.4.2 added hex offsets), so we key on
-				// the class, not the text. Anything else is unexpected and propagates. Treating
-				// a stray non-framing RangeError as end-of-log is the deliberate tradeoff: on
-				// this cold replay/boot path it still beats an uncaughtException aborting
-				// startup, and onCorruptFrame logs every occurrence so it is never silent.
+				// Key on the class, not the message: the framing RangeError's wording is
+				// version-dependent (1.4.2 added hex offsets). Anything else re-throws.
 				if (!(error instanceof RangeError)) throw error;
 				stopped = true;
 				onCorruptFrame(error);
 				return { done: true, value: undefined };
 			}
 		},
-		// Forward early termination so the source iterator's cleanup (e.g. releasing a
-		// rocksdb read handle / lock) still runs when a consumer exits a for-of early via
-		// break/return/throw. Mark stopped first so a later next() can't re-enter. The
-		// current rocksdb-js query iterator implements neither, hence the protocol defaults.
+		// Forward early termination (for-of break/return/throw) so the source's cleanup runs;
+		// mark stopped first. Current rocksdb-js implements neither — hence the protocol defaults.
 		return(value?: any): IteratorResult<T> {
 			stopped = true;
 			if (typeof iterator.return === 'function') return iterator.return(value);

unitTests/resources/replayLogs.test.js

@@ -64,10 +64,8 @@ describe('classifyAuditEntryForReplay', () => {
 	});
 });
 
-// Regression tests for HarperFast/harper#1135: rocksdb-js's txnlog reader throws a bounded
-// RangeError when an entry's declared length overruns the log (a torn/corrupt frame). That
-// used to escape uncaught out of the replay/broadcast iterator and abort startup. The wrapper
-// must turn it into a clean end-of-log instead, while leaving every other failure untouched.
+// Regression tests for HarperFast/harper#1135: the wrapper must turn a framing RangeError into
+// a clean end-of-log (so replay/broadcast don't abort the boot) and leave other errors alone.
 describe('endIteratorOnCorruptFrame', () => {
 	it('yields entries up to a corrupt frame, then ends cleanly and reports it once', () => {
 		let calls = 0;