feat(cluster): spec-5.55 shared resolver cache — CR Source 3 by-xid search-shortcut memo

A per-instance shared-memory memo that caches the position the last own-instance
WRAP_ANY by-xid durable scan (CR Source 3) matched -- (xid_epoch, raw_xid, origin)
-> {seg, slot, wrap} -- so a peer backend re-validates that one slot in O(1) via
cluster_tt_slot_durable_lookup instead of re-running the O(segments) scan.

Six 8.A safety gates (all default-off; entries=0 is byte-identical):
 1. memo non-authoritative: the scn is always a fresh durable re-read.
 2. exact-(xid,wrap) re-validation: a recycled/wrap-bumped slot fails -> re-scan.
 3. acceptance same-segment rerun: a memo hit runs the PHYSICALLY SAME
    cluster_cr_accept_resolved_scn helper (wrap_suspect WRAP_ANY + current horizon
    + sticky retention reliability) the fresh scan runs -> verdict-equivalent by
    construction; the memo never short-circuits acceptance.
 4. xid_epoch fence: a single monotonic own-instance FullTransactionId epoch makes
    a hint from epoch E a key MISS in E+1, before raw_xid can be reused.
 5. cross-instance fail-closed: own-instance scans only.
 6. COMMITTED-only.

Two modes (cluster.resolver_cache_enabled trust / cluster.resolver_cache_measure
diagnostic), both PGC_POSTMASTER, default off. D1 extends the by-xid resolver with
optional matched-slot out params (NULL = legacy, no TTSlot ABI / catversion change).

§0.6 value gate (measure-first): re-probe hit rate is workload-dependent (high
under retained-snapshot multi-reader; the recycle-heavy pure-write leg re-scans
safely via gate 2).  Default off; the non-zero default + sizing are forward 5.58.

Spec: spec-5.55-shared-resolver-cache.md (FROZEN v1.0)

Landed onto post-5.15 main (cherry-pick of v0.115.0-stage5.55 094b84c):
- renumber t/315_cluster_5_55_resolver_cache -> t/316 (resolves collision with
  spec-5.15's t/315_cluster_5_15_online_rejoin; nightly range 276-315 -> 276-316)
- reground pg_cluster_state category-count baselines 48 -> 49 across
  t/017/t/023/t/024/t/030/t/204/t/205/t/206 (reconfig_join from spec-5.15 +
  resolver_cache from spec-5.55 are both always-present categories)

Author: SqlRush

src/backend/cluster/Makefile

@@ -163,6 +163,7 @@ OBJS = \
 	cluster_cr_tuple.o \
 	cluster_cr_tuple_stat.o \
 	cluster_cr_srf.o \
+	cluster_resolver_cache.o \
 	cluster_tt_slot.o \
 	cluster_tt_2pc.o \
 	cluster_tt_2pc_record.o \

src/backend/cluster/cluster_cr.c

@@ -60,6 +60,7 @@
 #include "cluster/cluster_touched_peers.h" /* PGRAC: spec-5.14 D2 class 4 */
 #include "cluster/cluster_itl_slot.h"
 #include "cluster/cluster_shmem.h"
+#include "cluster/cluster_resolver_cache.h"		/* spec-5.55 D0: by-xid scan measure hook */
 #include "cluster/cluster_tt_durable.h"			/* spec-3.11 D6: watermark by-xid resolve */
 #include "cluster/cluster_tt_slot.h"			/* spec-3.22: retention_off_recycle_count */
 #include "cluster/cluster_undo_retention.h"		/* spec-3.22: retention horizon proof */
@@ -1322,6 +1323,36 @@ cluster_cr_count_xmax_scan_unavail_or_no_proof(void)
 		pg_atomic_fetch_add_u64(&CRShared->cr_xmax_scan_unavail_or_no_proof_count, 1);
 }
 
+/*
+ * cluster_cr_accept_resolved_scn -- spec-4.8 D3 acceptance gate for a Source 3
+ *	by-xid RESOLVED match, extracted (spec-5.55 D6) so the fresh-scan path AND a
+ *	shared-resolver-cache memo hit run the PHYSICALLY SAME gate (gate (3),
+ *	verdict-equivalent by construction -- they cannot drift).
+ *
+ *	The durable scan runs WRAP_ANY (a recycled scratch ITL slot carries no
+ *	binding wrap), so a single COMMITTED match cannot tell a genuine commit from a
+ *	2^32-wrapped raw-xid collision.  When retention is unreliable AND the match is
+ *	below the CURRENT horizon it is wrap-suspect -> fail closed (规则 8.A: a wrong
+ *	deleter scn would false-hide a live row); the existing
+ *	wrap_generation_disambiguated observability is bumped.  The reliability proof
+ *	is the EXACT sticky condition (horizon enabled AND no retention-off recycle
+ *	this incarnation), not an abstraction -- losing the sticky leg would re-trust
+ *	a retention-off-window recycle.  Returns true to ACCEPT (RESOLVED).
+ */
+static bool
+cluster_cr_accept_resolved_scn(SCN scn)
+{
+	bool retention_reliable = cluster_undo_retention_horizon_enabled
+							  && cluster_tt_slot_retention_off_recycle_count() == 0;
+
+	if (cluster_tt_recovery_wrap_suspect(CLUSTER_TT_WRAP_ANY, scn, cluster_undo_retention_horizon(),
+										 retention_reliable)) {
+		cluster_tt_recovery_count_wrap_generation_disambiguated();
+		return false; /* suspect -> fail closed */
+	}
+	return true;
+}
+
 /*
  * cluster_cr_resolve_xmax_commit_scn -- resolve the EXACT commit_scn of a
  * committed own-instance deleter (cr_xmax) recorded on a CR image, for the
@@ -1347,6 +1378,11 @@ cluster_cr_resolve_xmax_commit_scn(const char *cr_page, uint8 itl_idx, Transacti
 {
 	Page page = (Page)cr_page; /* read-only ITL access on the scratch image */
 	uint32 expected_wrap = CLUSTER_TT_WRAP_ANY;
+	/* spec-5.55 D1: Source 3 RESOLVED also reports the matched durable slot
+	 * identity, cached as a position hint by the shared resolver cache (D5). */
+	uint16 resolved_seg = 0;
+	uint16 resolved_slot = 0;
+	uint16 resolved_wrap = 0;
 
 	*out_scn = InvalidScn;
 
@@ -1397,33 +1433,61 @@ cluster_cr_resolve_xmax_commit_scn(const char *cr_page, uint8 itl_idx, Transacti
 		}
 	}
 
+	/*
+	 * spec-5.55 D6: shared resolver cache search-shortcut.  In TRUST mode a memo
+	 * hit re-validates the single hint slot in O(1) (gate (1)+(2)+(4)) and runs the
+	 * PHYSICALLY SAME acceptance gate the fresh scan runs (gate (3)), resolving
+	 * WITHOUT the O(segments) scan below -- verdict-equivalent by construction.  In
+	 * MEASURE/off mode the authoritative scan still runs (measure still records the
+	 * would-hit counters).  origin == own node (Source 3 is own-instance, gate (5)).
+	 */
+	{
+		SCN hint_scn = InvalidScn;
+
+		if (cluster_resolver_cache_probe((uint16)cluster_node_id, cr_xmax, &hint_scn)) {
+			bool accepted = cluster_cr_accept_resolved_scn(hint_scn);
+
+			cluster_resolver_cache_count_acceptance(accepted);
+			if (cluster_resolver_cache_trust()) {
+				if (!accepted) {
+					*out_scn = InvalidScn; /* same fail-closed as the fresh-scan branch */
+					return CLUSTER_CR_XMAX_INVALID_OR_AMBIGUOUS;
+				}
+				*out_scn = hint_scn; /* gate (1): durable re-read, verdict-equivalent */
+				return CLUSTER_CR_XMAX_RESOLVED_SCN;
+			}
+			/* MEASURE: never trust the hint -- fall through to the authoritative scan. */
+		}
+	}
+
 	/*
 	 * Source 3: durable TT by exact xid (survives ITL slot recycle).  spec-3.22:
 	 * consume the finer-grained resolve enum so a 0-match (RECYCLED_ZERO_MATCH ->
 	 * provably below horizon, IF the gate's retention proof holds) is no longer
 	 * conflated with a delayed-cleanout / wrap / unreadable miss (all fail closed).
 	 */
-	switch (cluster_tt_slot_durable_resolve_by_xid(cr_xmax, expected_wrap, out_scn)) {
+	switch (cluster_tt_slot_durable_resolve_by_xid(cr_xmax, expected_wrap, out_scn, &resolved_seg,
+												   &resolved_slot, &resolved_wrap)) {
 	case CLUSTER_TT_DURABLE_RESOLVED_SCN:
 		/*
-		 * spec-4.8 D3 (task#90): the durable scan above ran WRAP_ANY (a
-		 * recycled scratch ITL slot carries no binding wrap here), so a single
-		 * COMMITTED match cannot tell a genuine commit from a 2^32-wrapped
-		 * raw-xid collision.  When retention is unreliable AND the match is
-		 * below the horizon it is wrap-suspect -> fail closed (narrowed
-		 * AMBIGUOUS_WRAP), never resolve to its commit_scn (规则 8.A: a wrong
-		 * deleter scn would false-hide a live row).  With retention reliable a
-		 * below-horizon collision's slot is already recycled (0-match), so a
-		 * below-horizon 1-match is a legit recycle-lag commit -> trusted.
+		 * spec-4.8 D3 acceptance (now the shared cluster_cr_accept_resolved_scn
+		 * helper, spec-5.55 D6, gate (3)): the durable scan ran WRAP_ANY so a
+		 * single COMMITTED match below the horizon with unreliable retention is
+		 * wrap-suspect -> fail closed (规则 8.A: a wrong deleter scn would false-
+		 * hide a live row).  A memo hit above ran the SAME helper.
 		 */
-		if (cluster_tt_recovery_wrap_suspect(
-				expected_wrap, *out_scn, cluster_undo_retention_horizon(),
-				cluster_undo_retention_horizon_enabled
-					&& cluster_tt_slot_retention_off_recycle_count() == 0)) {
+		if (!cluster_cr_accept_resolved_scn(*out_scn)) {
 			*out_scn = InvalidScn;
-			cluster_tt_recovery_count_wrap_generation_disambiguated();
 			return CLUSTER_CR_XMAX_INVALID_OR_AMBIGUOUS;
 		}
+		/*
+		 * spec-5.55 D5: cache the matched {seg,slot,wrap} position hint (own-
+		 * instance gate (5) + COMMITTED gate (6) + acceptance-passed) so a peer
+		 * backend can re-validate it in O(1) instead of re-scanning every segment.
+		 * No-op unless the memo region is live.
+		 */
+		cluster_resolver_cache_install((uint16)cluster_node_id, cr_xmax, resolved_seg,
+									   resolved_slot, resolved_wrap, *out_scn);
 		return CLUSTER_CR_XMAX_RESOLVED_SCN; /* *out_scn set by the resolve */
 	case CLUSTER_TT_DURABLE_RECYCLED_ZERO_MATCH:
 		*out_scn = InvalidScn;

src/backend/cluster/cluster_debug.c

@@ -99,6 +99,7 @@ PG_FUNCTION_INFO_V1(cluster_dump_state);
 #include "cluster/cluster_cr_pool.h"		  /* cluster_cr_pool_* counters (spec-5.51 D9) */
 #include "cluster/cluster_cr_admit.h"		  /* cluster_cr_admit_stat_* counters (spec-5.52 D9) */
 #include "cluster/cluster_cr_tuple.h"		  /* cluster_cr_tuple_stat_* counters (spec-5.54 D5) */
+#include "cluster/cluster_resolver_cache.h"	  /* cluster_resolver_cache_* counters (spec-5.55 D8) */
 #include "cluster/cluster_wal_state.h"		  /* wal_state registry dump (spec-4.2 D5) */
 #include "cluster/cluster_wal_thread.h"		  /* wal_thread dump accessors (spec-4.1 D7) */
 #include "cluster/cluster_tt_durable.h"		  /* cluster_tt_durable_* counters (spec-3.11 D8) */
@@ -2436,6 +2437,34 @@ dump_cr(ReturnSetInfo *rsinfo)
 			 fmt_int64((int64)cluster_cr_admit_stat_count(CR_ADMIT_REASON_REJECT_RELCAP)));
 	emit_row(rsinfo, "cr_pool", "admit_reject_pressure",
 			 fmt_int64((int64)cluster_cr_admit_stat_count(CR_ADMIT_REASON_REJECT_PRESSURE)));
+
+	/* spec-5.55 D8: shared resolver cache (CR Source 3 by-xid search-shortcut)
+	 * counters.  All 0 unless resolver_cache_enabled / _measure is on.  These feed
+	 * the §0.6 value gate: redundancy = key_present / lookup, re-probe hit rate =
+	 * hit / key_present, acceptance pass rate = acceptance_pass / hit. */
+	emit_row(rsinfo, "resolver_cache", "lookup",
+			 fmt_int64((int64)cluster_resolver_cache_lookup_count()));
+	emit_row(rsinfo, "resolver_cache", "key_present",
+			 fmt_int64((int64)cluster_resolver_cache_key_present_count()));
+	emit_row(rsinfo, "resolver_cache", "epoch_miss",
+			 fmt_int64((int64)cluster_resolver_cache_epoch_miss_count()));
+	emit_row(rsinfo, "resolver_cache", "hit", fmt_int64((int64)cluster_resolver_cache_hit_count()));
+	emit_row(rsinfo, "resolver_cache", "revalidate_miss",
+			 fmt_int64((int64)cluster_resolver_cache_revalidate_miss_count()));
+	emit_row(rsinfo, "resolver_cache", "acceptance_pass",
+			 fmt_int64((int64)cluster_resolver_cache_acceptance_pass_count()));
+	emit_row(rsinfo, "resolver_cache", "acceptance_failclosed",
+			 fmt_int64((int64)cluster_resolver_cache_acceptance_failclosed_count()));
+	emit_row(rsinfo, "resolver_cache", "install",
+			 fmt_int64((int64)cluster_resolver_cache_install_count()));
+	emit_row(rsinfo, "resolver_cache", "evict",
+			 fmt_int64((int64)cluster_resolver_cache_evict_count()));
+	emit_row(rsinfo, "resolver_cache", "nonown_skip",
+			 fmt_int64((int64)cluster_resolver_cache_nonown_skip_count()));
+	emit_row(rsinfo, "resolver_cache", "nonterminal_skip",
+			 fmt_int64((int64)cluster_resolver_cache_nonterminal_skip_count()));
+	emit_row(rsinfo, "resolver_cache", "live_entries",
+			 fmt_int64((int64)cluster_resolver_cache_live_entries()));
 }
 
 

src/backend/cluster/cluster_guc.c

@@ -46,6 +46,7 @@
 #include "cluster/cluster_cr_cache.h"		 /* cluster_cr_cache_max_blocks (spec-3.10 D4) */
 #include "cluster/cluster_grd.h"			 /* spec-5.10 starvation-protection shared flag */
 #include "cluster/cluster_cr_pool.h"		 /* cluster_shared_cr_pool_* (spec-5.51 D8) */
+#include "cluster/cluster_resolver_cache.h"	 /* cluster_shared_resolver_cache_* (spec-5.55 D7) */
 #include "cluster/cluster_guc.h"
 #include "cluster/cluster_hang.h"			  /* CLUSTER_HANG_MAX_SAMPLES (spec-5.11 D7) */
 #include "cluster/cluster_hang_resolve.h"	  /* HANG_RESOLVE_* + disposition GUCs (spec-5.12 D6) */
@@ -2591,6 +2592,46 @@ cluster_init_guc(void)
 					 "affects hit/miss. The threshold is pending spec-5.58 calibration."),
 		&cluster_cr_pool_admit_pressure_ratio, 0, 0, 100000, PGC_SIGHUP, 0, NULL, NULL, NULL);
 
+	/* spec-5.55 D7: shared resolver cache (CR Source 3 by-xid search-shortcut
+	 * memo).  Both PGC_POSTMASTER: the entry count + measure switch are final at
+	 * shmem reservation.  Default entries 0 / measure off = true zero memory (the
+	 * region is registered but reserves 0 bytes), so the spec-3.22 by-xid path is
+	 * byte-identical.  v1 ships in MEASURE mode only (the value gate, §0.6): it
+	 * always re-runs the authoritative scan and never trusts the hint -- the
+	 * trust path (flip-on) is gated on measured redundancy + re-probe hit rate. */
+	DefineCustomBoolVariable(
+		"cluster.resolver_cache_enabled",
+		gettext_noop("Enable spec-5.55 shared resolver cache TRUST mode (skip the by-xid scan on a "
+					 "re-validated + accepted hint)."),
+		gettext_noop("Spec-5.55. Default off. When on (with resolver_cache_entries > 0), a CR "
+					 "Source 3 by-xid resolution that hits the shared memo re-validates the hint "
+					 "slot in O(1) and re-runs the SAME wrap_suspect acceptance as a fresh scan, "
+					 "resolving WITHOUT the O(segments) scan (verdict-equivalent by construction). "
+					 "The recommended non-zero default is bound to the §0.6 value gate evidence "
+					 "(spec-5.58). PGC_POSTMASTER: requires a restart."),
+		&cluster_resolver_cache_enabled, false, PGC_POSTMASTER, 0, NULL, NULL, NULL);
+
+	DefineCustomBoolVariable(
+		"cluster.resolver_cache_measure",
+		gettext_noop("Enable spec-5.55 shared resolver cache MEASURE mode (value gate, no trust)."),
+		gettext_noop("Spec-5.55 §0.6. Default off. When on (with resolver_cache_entries > 0), CR "
+					 "Source 3 records whether its own-instance by-xid scan result was already "
+					 "memoized by a peer backend and whether an O(1) re-validation + acceptance "
+					 "would have passed -- the cross-backend redundancy + re-probe hit rate that "
+					 "gate the trust path.  Never changes a visibility verdict (the authoritative "
+					 "scan always runs).  Orthogonal to resolver_cache_enabled.  PGC_POSTMASTER."),
+		&cluster_resolver_cache_measure, false, PGC_POSTMASTER, 0, NULL, NULL, NULL);
+
+	DefineCustomIntVariable(
+		"cluster.resolver_cache_entries",
+		gettext_noop("Shared resolver cache hint-slot count (0 = disabled / zero memory)."),
+		gettext_noop("Spec-5.55 D3/D7. Default 0 (true zero memory; the region is registered but "
+					 "reserves 0 bytes).  PGC_POSTMASTER: requires a restart.  The recommended "
+					 "non-zero default + sizing are bound to the §0.6 measure-leg value gate "
+					 "evidence (spec-5.58); resolver_cache_measure must also be on to allocate. "
+					 "Each hint slot costs a few dozen bytes of shared memory."),
+		&cluster_shared_resolver_cache_entries, 0, 0, 1048576, PGC_POSTMASTER, 0, NULL, NULL, NULL);
+
 	DefineCustomIntVariable(
 		"cluster.boc_sweep_interval_ms",
 		gettext_noop("walwriter BOC sweep staleness target in milliseconds."),

src/backend/cluster/cluster_remote_xact.c

@@ -292,7 +292,7 @@ cluster_remote_outcome_durable_checked(int origin_node, TransactionId xid, SCN *
 	 */
 	if (!outcome_wrap_valid
 		|| cluster_tt_slot_durable_resolve_by_xid_origin(origin_node, xid, (uint32)outcome_wrap,
-														 &durable_scn)
+														 &durable_scn, NULL, NULL, NULL)
 			   != CLUSTER_TT_DURABLE_RESOLVED_SCN
 		|| durable_scn != outcome_scn) {
 		if (RemoteXactShared != NULL)