From 7fcde108f19b7b670e16a21cf84faab730c6350c Mon Sep 17 00:00:00 2001
From: Melanie Plageman <melanieplageman@gmail.com>
Date: Fri, 20 Nov 2026 13:39:50 -0500
Subject: [PATCH v1 1/2] Stop masking visibility map bits during WAL
 consistency checking

heap_mask() treated visibility map pages as heap pages and masked the
bitmap between pd_lower and pd_upper, hiding differences between the
WAL image and the replayed page.

Pass the fork number to rm_mask() so heap_mask() masks only the LSN and
checksum on visibility map pages. Custom resource managers that provide
an rm_mask callback must update its signature.
---
 doc/src/sgml/custom-rmgr.sgml                |  7 ++--
 src/backend/access/brin/brin_xlog.c          |  2 +-
 src/backend/access/gin/ginxlog.c             |  2 +-
 src/backend/access/gist/gistxlog.c           |  2 +-
 src/backend/access/hash/hash_xlog.c          |  2 +-
 src/backend/access/heap/heapam_xlog.c        |  6 +++-
 src/backend/access/nbtree/nbtxlog.c          |  2 +-
 src/backend/access/spgist/spgxlog.c          |  2 +-
 src/backend/access/transam/generic_xlog.c    |  2 +-
 src/backend/access/transam/xlogrecovery.c    |  4 +--
 src/backend/commands/sequence_xlog.c         |  2 +-
 src/include/access/brin_xlog.h               |  2 +-
 src/include/access/generic_xlog.h            |  2 +-
 src/include/access/ginxlog.h                 |  2 +-
 src/include/access/gistxlog.h                |  2 +-
 src/include/access/hash_xlog.h               |  2 +-
 src/include/access/heapam_xlog.h             |  2 +-
 src/include/access/nbtxlog.h                 |  2 +-
 src/include/access/spgxlog.h                 |  2 +-
 src/include/access/xlog_internal.h           |  7 ++--
 src/include/commands/sequence_xlog.h         |  2 +-
 src/test/regress/expected/misc_functions.out |  9 ++++++
 src/test/regress/regress.c                   | 34 ++++++++++++++++++++
 src/test/regress/sql/misc_functions.sql      |  5 +++
 24 files changed, 80 insertions(+), 26 deletions(-)

diff --git a/doc/src/sgml/custom-rmgr.sgml b/doc/src/sgml/custom-rmgr.sgml
index 3032b2dc0d2..f54aac4daa3 100644
--- a/doc/src/sgml/custom-rmgr.sgml
+++ b/doc/src/sgml/custom-rmgr.sgml
@@ -34,8 +34,9 @@
  * "VACUUM". rm_desc can then be called to obtain additional detail for the
  * record, if available (e.g. the last block).
  *
- * rm_mask takes as input a page modified by the resource manager and masks
- * out bits that shouldn't be flagged by wal_consistency_checking.
+ * rm_mask takes a page modified by the resource manager, its fork number and
+ * block number, and masks out bits that shouldn't be flagged by
+ * wal_consistency_checking.
  *
  * RmgrTable[] is indexed by RmgrId values (see rmgrlist.h). If rm_name is
  * NULL, the corresponding RmgrTable entry is considered invalid.
@@ -48,7 +49,7 @@ typedef struct RmgrData
     const char *(*rm_identify) (uint8 info);
     void        (*rm_startup) (void);
     void        (*rm_cleanup) (void);
-    void        (*rm_mask) (char *pagedata, BlockNumber blkno);
+    void        (*rm_mask) (char *pagedata, ForkNumber forknum, BlockNumber blkno);
     void        (*rm_decode) (struct LogicalDecodingContext *ctx,
                               struct XLogRecordBuffer *buf);
 } RmgrData;
diff --git a/src/backend/access/brin/brin_xlog.c b/src/backend/access/brin/brin_xlog.c
index a07f1d11dde..3c809f6db9c 100644
--- a/src/backend/access/brin/brin_xlog.c
+++ b/src/backend/access/brin/brin_xlog.c
@@ -339,7 +339,7 @@ brin_redo(XLogReaderState *record)
  * Mask a BRIN page before doing consistency checks.
  */
 void
-brin_mask(char *pagedata, BlockNumber blkno)
+brin_mask(char *pagedata, ForkNumber forknum, BlockNumber blkno)
 {
 	Page		page = (Page) pagedata;
 	PageHeader	pagehdr = (PageHeader) page;
diff --git a/src/backend/access/gin/ginxlog.c b/src/backend/access/gin/ginxlog.c
index b1fee3c281f..de7fea32d39 100644
--- a/src/backend/access/gin/ginxlog.c
+++ b/src/backend/access/gin/ginxlog.c
@@ -788,7 +788,7 @@ gin_xlog_cleanup(void)
  * Mask a GIN page before running consistency checks on it.
  */
 void
-gin_mask(char *pagedata, BlockNumber blkno)
+gin_mask(char *pagedata, ForkNumber forknum, BlockNumber blkno)
 {
 	Page		page = (Page) pagedata;
 	PageHeader	pagehdr = (PageHeader) page;
diff --git a/src/backend/access/gist/gistxlog.c b/src/backend/access/gist/gistxlog.c
index 0df162f58f2..b34fde3161f 100644
--- a/src/backend/access/gist/gistxlog.c
+++ b/src/backend/access/gist/gistxlog.c
@@ -442,7 +442,7 @@ gist_xlog_cleanup(void)
  * Mask a Gist page before running consistency checks on it.
  */
 void
-gist_mask(char *pagedata, BlockNumber blkno)
+gist_mask(char *pagedata, ForkNumber forknum, BlockNumber blkno)
 {
 	Page		page = (Page) pagedata;
 
diff --git a/src/backend/access/hash/hash_xlog.c b/src/backend/access/hash/hash_xlog.c
index 46047c6ea27..a9a68a9d472 100644
--- a/src/backend/access/hash/hash_xlog.c
+++ b/src/backend/access/hash/hash_xlog.c
@@ -1125,7 +1125,7 @@ hash_redo(XLogReaderState *record)
  * Mask a hash page before performing consistency checks on it.
  */
 void
-hash_mask(char *pagedata, BlockNumber blkno)
+hash_mask(char *pagedata, ForkNumber forknum, BlockNumber blkno)
 {
 	Page		page = (Page) pagedata;
 	HashPageOpaque opaque;
diff --git a/src/backend/access/heap/heapam_xlog.c b/src/backend/access/heap/heapam_xlog.c
index 5fa1de09cfb..57ed4cb7946 100644
--- a/src/backend/access/heap/heapam_xlog.c
+++ b/src/backend/access/heap/heapam_xlog.c
@@ -1369,13 +1369,17 @@ heap2_redo(XLogReaderState *record)
  * Mask a heap page before performing consistency checks on it.
  */
 void
-heap_mask(char *pagedata, BlockNumber blkno)
+heap_mask(char *pagedata, ForkNumber forknum, BlockNumber blkno)
 {
 	Page		page = (Page) pagedata;
 	OffsetNumber off;
 
 	mask_page_lsn_and_checksum(page);
 
+	/* On VM pages the apparent free space contains the visibility bitmap. */
+	if (forknum == VISIBILITYMAP_FORKNUM)
+		return;
+
 	mask_page_hint_bits(page);
 	mask_unused_space(page);
 
diff --git a/src/backend/access/nbtree/nbtxlog.c b/src/backend/access/nbtree/nbtxlog.c
index dff7d286fc8..bb0e732bb78 100644
--- a/src/backend/access/nbtree/nbtxlog.c
+++ b/src/backend/access/nbtree/nbtxlog.c
@@ -1078,7 +1078,7 @@ btree_xlog_cleanup(void)
  * Mask a btree page before performing consistency checks on it.
  */
 void
-btree_mask(char *pagedata, BlockNumber blkno)
+btree_mask(char *pagedata, ForkNumber forknum, BlockNumber blkno)
 {
 	Page		page = (Page) pagedata;
 	BTPageOpaque maskopaq;
diff --git a/src/backend/access/spgist/spgxlog.c b/src/backend/access/spgist/spgxlog.c
index 55e8066a77b..e50da7a40a7 100644
--- a/src/backend/access/spgist/spgxlog.c
+++ b/src/backend/access/spgist/spgxlog.c
@@ -983,7 +983,7 @@ spg_xlog_cleanup(void)
  * Mask a SpGist page before performing consistency checks on it.
  */
 void
-spg_mask(char *pagedata, BlockNumber blkno)
+spg_mask(char *pagedata, ForkNumber forknum, BlockNumber blkno)
 {
 	Page		page = (Page) pagedata;
 	PageHeader	pagehdr = (PageHeader) page;
diff --git a/src/backend/access/transam/generic_xlog.c b/src/backend/access/transam/generic_xlog.c
index 7f82186d0d6..f14fb279861 100644
--- a/src/backend/access/transam/generic_xlog.c
+++ b/src/backend/access/transam/generic_xlog.c
@@ -536,7 +536,7 @@ generic_redo(XLogReaderState *record)
  * Mask a generic page before performing consistency checks on it.
  */
 void
-generic_mask(char *page, BlockNumber blkno)
+generic_mask(char *page, ForkNumber forknum, BlockNumber blkno)
 {
 	mask_page_lsn_and_checksum(page);
 
diff --git a/src/backend/access/transam/xlogrecovery.c b/src/backend/access/transam/xlogrecovery.c
index e091a3e178b..59fce62350f 100644
--- a/src/backend/access/transam/xlogrecovery.c
+++ b/src/backend/access/transam/xlogrecovery.c
@@ -2551,8 +2551,8 @@ verifyBackupPageConsistency(XLogReaderState *record)
 		 */
 		if (rmgr.rm_mask != NULL)
 		{
-			rmgr.rm_mask(replay_image_masked, blkno);
-			rmgr.rm_mask(primary_image_masked, blkno);
+			rmgr.rm_mask(replay_image_masked, forknum, blkno);
+			rmgr.rm_mask(primary_image_masked, forknum, blkno);
 		}
 
 		/* Time to compare the primary and replay images. */
diff --git a/src/backend/commands/sequence_xlog.c b/src/backend/commands/sequence_xlog.c
index fcb3230cf3b..76b9cf4def1 100644
--- a/src/backend/commands/sequence_xlog.c
+++ b/src/backend/commands/sequence_xlog.c
@@ -73,7 +73,7 @@ seq_redo(XLogReaderState *record)
  * Mask a Sequence page before performing consistency checks on it.
  */
 void
-seq_mask(char *page, BlockNumber blkno)
+seq_mask(char *page, ForkNumber forknum, BlockNumber blkno)
 {
 	mask_page_lsn_and_checksum(page);
 
diff --git a/src/include/access/brin_xlog.h b/src/include/access/brin_xlog.h
index 1c60dc8adb9..23fc686704b 100644
--- a/src/include/access/brin_xlog.h
+++ b/src/include/access/brin_xlog.h
@@ -146,6 +146,6 @@ typedef struct xl_brin_desummarize
 extern void brin_redo(XLogReaderState *record);
 extern void brin_desc(StringInfo buf, XLogReaderState *record);
 extern const char *brin_identify(uint8 info);
-extern void brin_mask(char *pagedata, BlockNumber blkno);
+extern void brin_mask(char *pagedata, ForkNumber forknum, BlockNumber blkno);
 
 #endif							/* BRIN_XLOG_H */
diff --git a/src/include/access/generic_xlog.h b/src/include/access/generic_xlog.h
index 93d93f73ddc..a7179c6518d 100644
--- a/src/include/access/generic_xlog.h
+++ b/src/include/access/generic_xlog.h
@@ -40,6 +40,6 @@ extern void GenericXLogAbort(GenericXLogState *state);
 extern void generic_redo(XLogReaderState *record);
 extern const char *generic_identify(uint8 info);
 extern void generic_desc(StringInfo buf, XLogReaderState *record);
-extern void generic_mask(char *page, BlockNumber blkno);
+extern void generic_mask(char *page, ForkNumber forknum, BlockNumber blkno);
 
 #endif							/* GENERIC_XLOG_H */
diff --git a/src/include/access/ginxlog.h b/src/include/access/ginxlog.h
index 74fdf9b3d7e..629bbf82616 100644
--- a/src/include/access/ginxlog.h
+++ b/src/include/access/ginxlog.h
@@ -214,6 +214,6 @@ extern void gin_desc(StringInfo buf, XLogReaderState *record);
 extern const char *gin_identify(uint8 info);
 extern void gin_xlog_startup(void);
 extern void gin_xlog_cleanup(void);
-extern void gin_mask(char *pagedata, BlockNumber blkno);
+extern void gin_mask(char *pagedata, ForkNumber forknum, BlockNumber blkno);
 
 #endif							/* GINXLOG_H */
diff --git a/src/include/access/gistxlog.h b/src/include/access/gistxlog.h
index 1c2cf6e813a..81234dbb05a 100644
--- a/src/include/access/gistxlog.h
+++ b/src/include/access/gistxlog.h
@@ -112,6 +112,6 @@ extern void gist_desc(StringInfo buf, XLogReaderState *record);
 extern const char *gist_identify(uint8 info);
 extern void gist_xlog_startup(void);
 extern void gist_xlog_cleanup(void);
-extern void gist_mask(char *pagedata, BlockNumber blkno);
+extern void gist_mask(char *pagedata, ForkNumber forknum, BlockNumber blkno);
 
 #endif
diff --git a/src/include/access/hash_xlog.h b/src/include/access/hash_xlog.h
index 149aed69dc5..b0d0bd25971 100644
--- a/src/include/access/hash_xlog.h
+++ b/src/include/access/hash_xlog.h
@@ -265,6 +265,6 @@ typedef struct xl_hash_vacuum_one_page
 extern void hash_redo(XLogReaderState *record);
 extern void hash_desc(StringInfo buf, XLogReaderState *record);
 extern const char *hash_identify(uint8 info);
-extern void hash_mask(char *pagedata, BlockNumber blkno);
+extern void hash_mask(char *pagedata, ForkNumber forknum, BlockNumber blkno);
 
 #endif							/* HASH_XLOG_H */
diff --git a/src/include/access/heapam_xlog.h b/src/include/access/heapam_xlog.h
index 3f79c389a90..af8b96ca119 100644
--- a/src/include/access/heapam_xlog.h
+++ b/src/include/access/heapam_xlog.h
@@ -512,7 +512,7 @@ extern void HeapTupleHeaderAdvanceConflictHorizon(HeapTupleHeader tuple,
 extern void heap_redo(XLogReaderState *record);
 extern void heap_desc(StringInfo buf, XLogReaderState *record);
 extern const char *heap_identify(uint8 info);
-extern void heap_mask(char *pagedata, BlockNumber blkno);
+extern void heap_mask(char *pagedata, ForkNumber forknum, BlockNumber blkno);
 extern void heap2_redo(XLogReaderState *record);
 extern void heap2_desc(StringInfo buf, XLogReaderState *record);
 extern const char *heap2_identify(uint8 info);
diff --git a/src/include/access/nbtxlog.h b/src/include/access/nbtxlog.h
index 3a78ec27fe8..28eece3b15a 100644
--- a/src/include/access/nbtxlog.h
+++ b/src/include/access/nbtxlog.h
@@ -356,7 +356,7 @@ typedef struct xl_btree_newroot
 extern void btree_redo(XLogReaderState *record);
 extern void btree_xlog_startup(void);
 extern void btree_xlog_cleanup(void);
-extern void btree_mask(char *pagedata, BlockNumber blkno);
+extern void btree_mask(char *pagedata, ForkNumber forknum, BlockNumber blkno);
 
 /*
  * prototypes for functions in nbtdesc.c
diff --git a/src/include/access/spgxlog.h b/src/include/access/spgxlog.h
index c257408be66..122ae7b0b85 100644
--- a/src/include/access/spgxlog.h
+++ b/src/include/access/spgxlog.h
@@ -254,6 +254,6 @@ extern void spg_desc(StringInfo buf, XLogReaderState *record);
 extern const char *spg_identify(uint8 info);
 extern void spg_xlog_startup(void);
 extern void spg_xlog_cleanup(void);
-extern void spg_mask(char *pagedata, BlockNumber blkno);
+extern void spg_mask(char *pagedata, ForkNumber forknum, BlockNumber blkno);
 
 #endif							/* SPGXLOG_H */
diff --git a/src/include/access/xlog_internal.h b/src/include/access/xlog_internal.h
index bf609c3c703..3d8c1da5f35 100644
--- a/src/include/access/xlog_internal.h
+++ b/src/include/access/xlog_internal.h
@@ -342,8 +342,9 @@ struct XLogRecordBuffer;
  * "VACUUM". rm_desc can then be called to obtain additional detail for the
  * record, if available (e.g. the last block).
  *
- * rm_mask takes as input a page modified by the resource manager and masks
- * out bits that shouldn't be flagged by wal_consistency_checking.
+ * rm_mask takes a page modified by the resource manager, its fork number and
+ * block number, and masks out bits that shouldn't be flagged by
+ * wal_consistency_checking.
  *
  * RmgrTable[] is indexed by RmgrId values (see rmgrlist.h). If rm_name is
  * NULL, the corresponding RmgrTable entry is considered invalid.
@@ -356,7 +357,7 @@ typedef struct RmgrData
 	const char *(*rm_identify) (uint8 info);
 	void		(*rm_startup) (void);
 	void		(*rm_cleanup) (void);
-	void		(*rm_mask) (char *pagedata, BlockNumber blkno);
+	void		(*rm_mask) (char *pagedata, ForkNumber forknum, BlockNumber blkno);
 	void		(*rm_decode) (struct LogicalDecodingContext *ctx,
 							  struct XLogRecordBuffer *buf);
 } RmgrData;
diff --git a/src/include/commands/sequence_xlog.h b/src/include/commands/sequence_xlog.h
index b0495f41b43..84d0f7e14bd 100644
--- a/src/include/commands/sequence_xlog.h
+++ b/src/include/commands/sequence_xlog.h
@@ -40,6 +40,6 @@ typedef struct xl_seq_rec
 extern void seq_redo(XLogReaderState *record);
 extern void seq_desc(StringInfo buf, XLogReaderState *record);
 extern const char *seq_identify(uint8 info);
-extern void seq_mask(char *page, BlockNumber blkno);
+extern void seq_mask(char *page, ForkNumber forknum, BlockNumber blkno);
 
 #endif							/* SEQUENCE_XLOG_H */
diff --git a/src/test/regress/expected/misc_functions.out b/src/test/regress/expected/misc_functions.out
index 35d6ee2ce9e..7a2b6709039 100644
--- a/src/test/regress/expected/misc_functions.out
+++ b/src/test/regress/expected/misc_functions.out
@@ -817,6 +817,15 @@ SELECT test_relpath();
  
 (1 row)
 
+-- WAL consistency masks for visibility map pages
+CREATE FUNCTION test_vm_mask() RETURNS void
+    AS :'regresslib' LANGUAGE C;
+SELECT test_vm_mask();
+ test_vm_mask 
+--------------
+ 
+(1 row)
+
 -- pg_replication_origin.roname limit
 SELECT pg_replication_origin_create('regress_' || repeat('a', 505));
 ERROR:  replication origin name is too long
diff --git a/src/test/regress/regress.c b/src/test/regress/regress.c
index 6e61c0d201b..a8bb0bd845d 100644
--- a/src/test/regress/regress.c
+++ b/src/test/regress/regress.c
@@ -21,6 +21,8 @@
 
 #include "access/detoast.h"
 #include "access/htup_details.h"
+#include "access/visibilitymapdefs.h"
+#include "access/xlog_internal.h"
 #include "catalog/catalog.h"
 #include "catalog/namespace.h"
 #include "catalog/pg_operator.h"
@@ -1393,6 +1395,38 @@ binary_coercible(PG_FUNCTION_ARGS)
 	PG_RETURN_BOOL(IsBinaryCoercible(srctype, targettype));
 }
 
+/* Check the WAL consistency masks for visibility map pages. */
+PG_FUNCTION_INFO_V1(test_vm_mask);
+Datum
+test_vm_mask(PG_FUNCTION_ARGS)
+{
+	const RmgrId rmids[] = {RM_HEAP_ID, RM_HEAP2_ID};
+	Page		primary = palloc(BLCKSZ);
+	Page		replay = palloc(BLCKSZ);
+
+	for (int i = 0; i < lengthof(rmids); i++)
+	{
+		RmgrData	rmgr = GetRmgr(rmids[i]);
+
+		PageInit(primary, BLCKSZ, 0);
+		*PageGetContents(primary) = VISIBILITYMAP_ALL_VISIBLE;
+		memcpy(replay, primary, BLCKSZ);
+		PageSetLSN(replay, 1);
+		((PageHeader) replay)->pd_checksum = 1;
+
+		rmgr.rm_mask(primary, VISIBILITYMAP_FORKNUM, 0);
+		rmgr.rm_mask(replay, VISIBILITYMAP_FORKNUM, 0);
+		if (memcmp(primary, replay, BLCKSZ) != 0)
+			elog(ERROR, "%s mask retained VM page LSN or checksum", rmgr.rm_name);
+
+		*PageGetContents(replay) |= VISIBILITYMAP_ALL_FROZEN;
+		rmgr.rm_mask(replay, VISIBILITYMAP_FORKNUM, 0);
+		if (memcmp(primary, replay, BLCKSZ) == 0)
+			elog(ERROR, "%s mask hid a VM bitmap difference", rmgr.rm_name);
+	}
+	PG_RETURN_VOID();
+}
+
 /*
  * Sanity checks for functions in relpath.h
  */
diff --git a/src/test/regress/sql/misc_functions.sql b/src/test/regress/sql/misc_functions.sql
index 94b91964c04..3ff07b9ab6c 100644
--- a/src/test/regress/sql/misc_functions.sql
+++ b/src/test/regress/sql/misc_functions.sql
@@ -332,6 +332,11 @@ CREATE FUNCTION test_relpath()
     LANGUAGE C;
 SELECT test_relpath();
 
+-- WAL consistency masks for visibility map pages
+CREATE FUNCTION test_vm_mask() RETURNS void
+    AS :'regresslib' LANGUAGE C;
+SELECT test_vm_mask();
+
 -- pg_replication_origin.roname limit
 SELECT pg_replication_origin_create('regress_' || repeat('a', 505));
 
-- 
2.43.0

