feat(cluster): root-cause-#1 shared undo physical data plane under GCS (D1–D6 integration)

.github/workflows/nightly.yml

@@ -147,7 +147,13 @@ jobs:
           - { name: stage2-gcs,        ranges: "100-118", unit: false, regress: false }
           - { name: stage3-core,       ranges: "203-225", unit: false, regress: false }
           - { name: stage3-recent,     ranges: "228-237", unit: false, regress: false }
-          - { name: stage4-wal,        ranges: "242-248 273 275", unit: false, regress: false }
+          # 255 = spec-5.22b D2-7 undo-block GCS shared-storage data-plane TAP
+          # (2-node ClusterPair + shared cluster_fs; owner-as-master physical
+          # migration).  Registered here (undo/recovery bucket) so the new file
+          # runs in nightly per the "every new t/ file lands in a shard the same
+          # commit" rule.  NOTE: t/249-254 + t/256-272 remain an un-sharded
+          # pre-existing gap (tracked separately), not opened by this commit.
+          - { name: stage4-wal,        ranges: "242-248 255 273 275", unit: false, regress: false }
           - { name: stage4-hardgate,   ranges: "274-274", unit: false, regress: false }
           - { name: stage5-ges-locking, ranges: "276-326", unit: false, regress: false }
           # spec-5.19 D9: Stage 5 integrated acceptance (heavy 4-node ClusterQuad
@@ -212,6 +218,13 @@ jobs:
           # (spec-7.1 family; 368 renamed from the double-occupied t/360 per
           # the hub number ledger -- the lms data-plane faults file keeps 360).
           - { name: stage7-multixact, ranges: "359 368", unit: false, regress: false }
+          # t/369 spec-5.22d dead-owner authority serve + t/370 spec-5.22e
+          # cluster-wide undo retention brake (both 2-node shared-root) +
+          # t/386 spec-2.2 caps-reply directed matrix / rolling-upgrade
+          # compat / generation legs (3-node triple).  Own shard: the brake
+          # legs pin/stall/self-heal on real cleaner cadence and need the
+          # wall clock.
+          - { name: stage5-undo-retention, ranges: "369-370 386", unit: false, regress: false }
     steps:
       - name: Checkout
         uses: actions/checkout@v4

scripts/ci/run-cppcheck.sh

@@ -153,6 +153,12 @@ SHAREDFS_SUPP=(
   # Reason: same PG-Assert-non-trapping pattern -- Assert(lease != NULL);
   # lease->next in cluster_oid_lease_consume (spec-6.14 D6).
   --suppress=nullPointerRedundantCheck:src/backend/cluster/cluster_oid_lease.c
+  # Reason: spec-5.22e D5 cluster_undo_horizon_cluster_floor uses the same
+  # Assert(out_floor != NULL && out_reason != NULL && out_blame_node != NULL);
+  # then writes *out_floor / *out_reason / *out_blame_node -- PG Assert is
+  # non-trapping to cppcheck, so the four post-Assert out-param writes read as
+  # redundant null checks (identical false positive to cluster_shmem.c above).
+  --suppress=nullPointerRedundantCheck:src/backend/cluster/cluster_undo_horizon.c
   # Reason: spec-2.3 D1 cluster_ic_envelope.h uses pg_attribute_packed()
   # macro from c.h to honor spec-2.0 §4 frozen offsets (uint64 epoch at
   # offset 12 / scn at offset 20 are non-8-aligned naturally; without

src/backend/access/heap/heapam_visibility.c

@@ -1986,7 +1986,9 @@ HeapTupleSatisfiesMVCC(HeapTuple htup, Snapshot snapshot, Buffer buffer)
 						cluster_vis53r97_note_xmin_overlay_verdict_ask();
 						if (cluster_runtime_visibility_try_resolve_remote(
 								d1_origin, (uint32)res.ref.undo_segment_id, raw_xmin,
-								snapshot->read_scn, &d1_committed, &d1_scn, &d1_is_bound)) {
+								snapshot->read_scn,
+								false /* derived origin: keep the stripe self-check */,
+								&d1_committed, &d1_scn, &d1_is_bound)) {
 							if (!d1_committed) {
 								/* origin proved ABORTED -> this xmin was never
 								 * visible to any snapshot. */

src/backend/cluster/Makefile

@@ -188,6 +188,14 @@ OBJS = \
 	cluster_visibility_verdict.o \
 	cluster_writer_chain.o \
 	cluster_undo_record.o \
+	cluster_undo_resid.o \
+	cluster_undo_authority.o \
+	cluster_undo_authority_snapshot.o \
+	cluster_undo_gcs.o \
+	cluster_undo_gcs_grant.o \
+	cluster_undo_gcs_stat.o \
+	cluster_undo_horizon.o \
+	cluster_undo_horizon_ic.o \
 	cluster_undo_retention.o \
 	cluster_undo_srf.o \
 	cluster_cr.o \

src/backend/cluster/cluster_cr.c

@@ -176,6 +176,37 @@ typedef struct ClusterCRShared {
 	 * striped cluster).
 	 */
 	pg_atomic_uint64 rtvis_underivable_failclosed_count;
+	/*
+	 * spec-5.22f D6-3: fresh-remote-ITL-ref widening outcome counters.  A
+	 * fresh ref (local_xid == raw_xid, origin != self) that missed the overlay
+	 * and was resolved by the D3 cross-node verdict (classify_ref_guts D6
+	 * branch): resolved = a terminal COMMITTED/ABORTED verdict consumed
+	 * (the L1 root-cause-#1 hard assert lands here, proving the fresh-ref path
+	 * ran rather than an overlay / ordinary-propagation hit); failclosed = a
+	 * STALE integrity mismatch or an UNKNOWN verdict kept 53R97.
+	 */
+	pg_atomic_uint64 vis_freshref_verdict_resolved_count;
+	pg_atomic_uint64 vis_freshref_verdict_failclosed_count;
+	/*
+	 * spec-5.22d D4-4: dead/absent-owner authority block0 serve outcomes.
+	 * serve_hit = self-as-authority served a terminal verdict off the dead
+	 * owner's shared block0 (the D4-8 L1 hard assert lands here, proving the
+	 * Route B serve ran rather than a materialized-copy read); fail_closed =
+	 * the precision chain refused (peer/no authority, epoch moved, block0
+	 * unreadable, or no slot proof) and the caller kept 53R97;
+	 * epoch_stale_reject (D4-5) = the specific epoch axis of a refusal (the
+	 * claim's reconfig epoch no longer is the current one) -- bumped IN
+	 * ADDITION to fail_closed, so fail_closed stays the total-refusal count
+	 * (D4-8 L3 asserts the axis, not just the total).
+	 */
+	pg_atomic_uint64 undo_authority_serve_hit_count;
+	pg_atomic_uint64 undo_authority_fail_closed_count;
+	pg_atomic_uint64 undo_authority_epoch_stale_reject_count;
+	/* spec-5.22d A1 (D4-8): complete-scan refusal attribution — the durable
+	 * segment-set enumeration/parse was incomplete (refuse-all), or the set
+	 * held more than one match for the asked xid (ambiguity). */
+	pg_atomic_uint64 undo_authority_scan_incomplete_reject_count;
+	pg_atomic_uint64 undo_authority_multi_match_reject_count;
 	/*
 	 * spec-7.1 D0/D5: 53R97 per-leg attribution.  Every fail-closed refusal
 	 * on the cross-instance read path is attributed to the leg that produced
@@ -314,6 +345,13 @@ cluster_cr_shmem_init(void)
 		pg_atomic_init_u64(&CRShared->cr_server_multi_verdict_denied_count, 0);
 		pg_atomic_init_u64(&CRShared->cr_server_fence_refused_count, 0);
 		pg_atomic_init_u64(&CRShared->rtvis_underivable_failclosed_count, 0);
+		pg_atomic_init_u64(&CRShared->vis_freshref_verdict_resolved_count, 0);
+		pg_atomic_init_u64(&CRShared->vis_freshref_verdict_failclosed_count, 0);
+		pg_atomic_init_u64(&CRShared->undo_authority_serve_hit_count, 0);
+		pg_atomic_init_u64(&CRShared->undo_authority_fail_closed_count, 0);
+		pg_atomic_init_u64(&CRShared->undo_authority_epoch_stale_reject_count, 0);
+		pg_atomic_init_u64(&CRShared->undo_authority_scan_incomplete_reject_count, 0);
+		pg_atomic_init_u64(&CRShared->undo_authority_multi_match_reject_count, 0);
 		pg_atomic_init_u64(&CRShared->vis53r97_leg_invalid_scn_refuse_count, 0);
 		pg_atomic_init_u64(&CRShared->vis53r97_leg_zero_match_refuse_count, 0);
 		pg_atomic_init_u64(&CRShared->vis53r97_leg_srv_other_refuse_count, 0);
@@ -495,6 +533,59 @@ cluster_rtvis_note_underivable_failclosed(void)
 		pg_atomic_fetch_add_u64(&CRShared->rtvis_underivable_failclosed_count, 1);
 }
 
+/* PGRAC: spec-5.22f D6-3 — fresh-remote-ITL-ref widening outcome bumps
+ * (classify_ref_guts, backend context). */
+void
+cluster_vis_freshref_verdict_note_resolved(void)
+{
+	if (CRShared != NULL)
+		pg_atomic_fetch_add_u64(&CRShared->vis_freshref_verdict_resolved_count, 1);
+}
+
+void
+cluster_vis_freshref_verdict_note_failclosed(void)
+{
+	if (CRShared != NULL)
+		pg_atomic_fetch_add_u64(&CRShared->vis_freshref_verdict_failclosed_count, 1);
+}
+
+/* PGRAC: spec-5.22d D4-4 — dead-owner authority block0 serve bumps
+ * (cluster_runtime_visibility.c precision chain, backend context). */
+void
+cluster_undo_authority_note_serve_hit(void)
+{
+	if (CRShared != NULL)
+		pg_atomic_fetch_add_u64(&CRShared->undo_authority_serve_hit_count, 1);
+}
+
+void
+cluster_undo_authority_note_failclosed(void)
+{
+	if (CRShared != NULL)
+		pg_atomic_fetch_add_u64(&CRShared->undo_authority_fail_closed_count, 1);
+}
+
+void
+cluster_undo_authority_note_epoch_stale_reject(void)
+{
+	if (CRShared != NULL)
+		pg_atomic_fetch_add_u64(&CRShared->undo_authority_epoch_stale_reject_count, 1);
+}
+
+/* PGRAC: spec-5.22d A1 (D4-8) — complete-scan refusal attribution. */
+void
+cluster_undo_authority_note_scan_incomplete_reject(void)
+{
+	if (CRShared != NULL)
+		pg_atomic_fetch_add_u64(&CRShared->undo_authority_scan_incomplete_reject_count, 1);
+}
+
+void
+cluster_undo_authority_note_multi_match_reject(void)
+{
+	if (CRShared != NULL)
+		pg_atomic_fetch_add_u64(&CRShared->undo_authority_multi_match_reject_count, 1);
+}
 /* PGRAC: spec-7.1 D0/D5 — 53R97 per-leg attribution bumps (see the struct
  * comment for each leg's meaning; server legs run in LMS drain context,
  * requester legs in backend context — all plain atomic adds). */
@@ -631,6 +722,20 @@ CR_COUNTER_ACCESSOR(cluster_cr_server_multi_verdict_denied_count,
 					cr_server_multi_verdict_denied_count)
 CR_COUNTER_ACCESSOR(cluster_cr_server_fence_refused_count, cr_server_fence_refused_count)
 CR_COUNTER_ACCESSOR(cluster_rtvis_underivable_failclosed_count, rtvis_underivable_failclosed_count)
+/* spec-5.22f D6-3: fresh-remote-ITL-ref widening outcome counters. */
+CR_COUNTER_ACCESSOR(cluster_vis_freshref_verdict_resolved_count,
+					vis_freshref_verdict_resolved_count)
+CR_COUNTER_ACCESSOR(cluster_vis_freshref_verdict_failclosed_count,
+					vis_freshref_verdict_failclosed_count)
+/* spec-5.22d D4-4/D4-5: dead-owner authority block0 serve counters. */
+CR_COUNTER_ACCESSOR(cluster_undo_authority_serve_hit_count, undo_authority_serve_hit_count)
+CR_COUNTER_ACCESSOR(cluster_undo_authority_fail_closed_count, undo_authority_fail_closed_count)
+CR_COUNTER_ACCESSOR(cluster_undo_authority_epoch_stale_reject_count,
+					undo_authority_epoch_stale_reject_count)
+CR_COUNTER_ACCESSOR(cluster_undo_authority_scan_incomplete_reject_count,
+					undo_authority_scan_incomplete_reject_count)
+CR_COUNTER_ACCESSOR(cluster_undo_authority_multi_match_reject_count,
+					undo_authority_multi_match_reject_count)
 CR_COUNTER_ACCESSOR(cluster_vis53r97_leg_invalid_scn_refuse_count,
 					vis53r97_leg_invalid_scn_refuse_count)
 CR_COUNTER_ACCESSOR(cluster_vis53r97_leg_zero_match_refuse_count,