Stage 7: land P0 cluster-formation substrate + spec-7.2 IC data-plane

.github/workflows/nightly.yml

@@ -176,12 +176,20 @@ jobs:
           # the release-cut 4-node evidence is HG#2a-CI or HG#2a-EXT (external).
           - { name: stage5-beta-chaos-soak, ranges: "344-345", unit: false, regress: false }
           # spec-6.12/6.15 cross-node perf + correctness family (t/346-350:
-          # aged-seed verdict / ledger / 3-node nudge / PI rebuild + crash) and
-          # the renumbered t/351-356 family + t/357 multi-xmax alias floor.
+          # aged-seed verdict / ledger / 3-node nudge / PI rebuild + crash),
+          # the renumbered t/351-356 family, t/357 multi-xmax alias floor, and
+          # t/361 XID authority native-era adoption.
           # Closes the 346+ shard hole (every new t/ file must land in a shard
           # the same commit; see docs/code-review-checklist.md).
           - { name: stage6-crossnode-a, ranges: "346-350", unit: false, regress: false }
-          - { name: stage6-crossnode-b, ranges: "351-357", unit: false, regress: false }
+          - { name: stage6-crossnode-b, ranges: "351-357 361", unit: false, regress: false }
+          # t/362 spec-4.6a 4-node shared_catalog kill self-heal (t/358-360
+          # reserved by the parallel spec-7.2 lane; L464 occupancy verified
+          # against origin branches 2026-07-08).  Own shard: 4-node formation
+          # + kill + convergence needs the wall clock.
+          - { name: stage7-reconfig-liveness, ranges: "362-362", unit: false, regress: false }
+          # t/363 spec-2.29a marker-async LMON liveness.
+          - { name: stage7-marker-async, ranges: "363-363", unit: false, regress: false }
     steps:
       - name: Checkout
         uses: actions/checkout@v4

docs/reference/system-views.md

@@ -210,6 +210,9 @@ must not be read as evidence that early transfer is active.
 | `smart_fusion` | `origin_suspect_count` | Pending dependencies associated with an origin suspected dead or unavailable. |
 | `smart_fusion` | `dep_lost_failclosed_count` | Missing or malformed dependency evidence rejected fail-closed. |
 | `smart_fusion` | `retry_failclosed_count` | Retryable Smart Fusion fail-closed outcomes, primarily commit-brake timeout. |
+| `catalog` | `xid_authority_native_hw` | Sealed native-era xid high-water for shared-catalog formation; `0` when the authority is inactive or unreadable. |
+| `catalog` | `xid_authority_sealed` | `t` when the seed completed a clean native-era shutdown and published adoptable XID prehistory. |
+| `catalog` | `xid_prehistory_adopted` | Process-local marker showing whether this postmaster boot adopted native-era pg_xact prehistory. |
 
 Example:
 

docs/user-guide/configuration.md

@@ -776,6 +776,9 @@ Requirements and behaviour:
 * `cluster.node_id` must be between 0 and 15; startup is refused
   otherwise.  Striped clusters are therefore limited to **16 nodes**.
 * `cluster.online_join` must be `on`; startup is refused otherwise.
+* `cluster.shared_catalog = on` with more than one declared node requires
+  `cluster.xid_striping = on`; startup fails closed with SQLSTATE `53RB5`
+  if a multi-node shared-catalog cluster is formed without striping.
 * All nodes must run with the same `cluster.xid_striping` setting.
   The cluster records its striping state durably on the voting disk;
   a node whose configuration disagrees with that recorded state (or
@@ -791,6 +794,50 @@ cluster.xid_striping = on
 cluster.online_join = on
 ```
 
+### Shared-catalog native-era XID authority
+
+A shared-catalog cluster that is formed from a single seed node has a
+short native era: the seed runs with `cluster.enabled = off` while it
+creates initial catalog rows, roles, schemas, and seed data.  Those
+transactions consume the seed node's local xids before other nodes have
+joined.  During the seed node's clean shutdown, pgrac publishes two
+formation files under `cluster.shared_data_dir/global`:
+`pgrac_xid_authority` (the sealed native xid high-water) and
+`pgrac_xid_prehistory` (the seed node's pg_xact truth for those xids).
+
+Provisioning sequence:
+
+1. Create or clone joiner data directories before the seed load if they
+   must share the seed node's system identifier.
+2. Start the seed with `cluster.shared_catalog = on`,
+   `cluster.controlfile_shared_authority = on`, `cluster.enabled = off`,
+   and a fixed `cluster.node_id`; perform the seed load.
+3. Stop the seed cleanly.  Do not use immediate shutdown for the final
+   native-era stop; joiners refuse an unsealed authority with SQLSTATE
+   `53RB5`.
+4. Start all nodes with `cluster.enabled = on`, `cluster.online_join = on`,
+   and `cluster.xid_striping = on`.  Joiners adopt the seed's transaction
+   history at startup, so seed tables, roles, and data are visible on
+   every node.
+
+Do not delete or re-create the authority files to recover a failed join.
+A missing, unsealed, or corrupt authority/prehistory is intentionally
+fail-closed (`53RB5`); restore the shared tree files from backup or
+re-provision the cluster.  After the first `cluster.enabled = on` boot,
+the native era is permanently closed and a later `cluster.enabled = off`
+boot against the same shared tree is refused.
+
+Observe formation state with:
+
+```sql
+SELECT key, value
+  FROM pg_cluster_state
+ WHERE category = 'catalog'
+   AND key IN ('xid_authority_native_hw',
+               'xid_authority_sealed',
+               'xid_prehistory_adopted');
+```
+
 ### `cluster.xid_herding_slack`
 
 | | |

src/backend/access/transam/xlog.c

@@ -201,6 +201,7 @@
 #include "cluster/cluster_guc.h" /* PGRAC: spec-5.6 cluster_controlfile_shared_authority */
 #include "cluster/cluster_hw_snapshot.h" /* PGRAC: spec-5.7 D3 HW authority checkpoint snapshot */
 #include "cluster/cluster_xid_stripe_xlog.h" /* PGRAC: spec-6.15 D5d checkpoint re-emit */
+#include "cluster/cluster_xid_authority.h" /* PGRAC: spec-6.15b native-era XID authority */
 #include "cluster/cluster_recovery_anchor.h" /* PGRAC: spec-5.6a per-node recovery anchor */
 #include "cluster/cluster_lms.h" /* PGRAC: spec-5.6 GES-ready boundary for CF X */
 #endif
@@ -5593,6 +5594,42 @@ StartupXLOG(void)
 	 */
 	if (cluster_recovery_anchor_active() && !InRecovery)
 		checkPoint = cluster_recovery_anchor_get()->checkPointCopy;
+
+	/*
+	 * PGRAC (spec-6.15b D5): shared_catalog nodes must reconcile their
+	 * transaction horizon with the sealed native-era XID authority before
+	 * ShmemVariableCache is seeded and before StartupCLOG computes its latest
+	 * page.  This deliberately consumes a dedicated never-lowered authority,
+	 * not the shared pg_control CheckPoint copy (spec-5.6a keeps that
+	 * per-writer).
+	 */
+	if (cluster_shared_catalog && cluster_enabled)
+	{
+		ClusterXidAuthorityHeader auth;
+		bool		auth_from_bak = false;
+		bool		auth_ok;
+
+		auth_ok = cluster_xid_authority_read_checked(&auth, &auth_from_bak);
+		if (auth_ok && auth_from_bak)
+			elog(LOG, "cluster shared_catalog: XID authority served from .bak fallback; "
+				 "the primary copy failed validation");
+
+		if (!auth_ok ||
+			(auth.flags & CLUSTER_XID_AUTHORITY_FLAG_SEALED) == 0)
+			ereport(FATAL, (errcode(ERRCODE_CLUSTER_XID_AUTHORITY_UNAVAILABLE),
+							errmsg("shared XID authority is unavailable during WAL startup"),
+							errdetail("StartupXLOG cannot seed nextXid without a sealed native-era high-water."),
+							errhint("Complete a clean native-era seed shutdown before starting shared_catalog nodes.")));
+
+		if (U64FromFullTransactionId(checkPoint.nextXid) < auth.native_hw_full)
+		{
+			uint64 own_next = U64FromFullTransactionId(checkPoint.nextXid);
+
+			checkPoint.nextXid = FullTransactionIdFromU64(auth.native_hw_full);
+			elog(LOG, "cluster shared_catalog: merged nextXid with XID authority native high-water %llu (own was %llu)",
+				 (unsigned long long)auth.native_hw_full, (unsigned long long)own_next);
+		}
+	}
 #endif
 
 	/* initialize shared memory variables from the checkpoint record */
@@ -7549,6 +7586,59 @@ CreateCheckPoint(int flags)
 	 */
 	END_CRIT_SECTION();
 
+#ifdef USE_PGRAC_CLUSTER
+	/*
+	 * PGRAC (spec-6.15b D3): after the shutdown checkpoint record,
+	 * control-file update, CLOG flush, and per-node recovery anchor publish
+	 * are complete, publish the native-era pg_xact prehistory and seal the
+	 * shared XID authority.  This does durable file I/O and may fail closed,
+	 * so it must stay outside the checkpoint critical section.
+	 *
+	 * Two deliberate exclusions (review P2-1):
+	 *
+	 * - END_OF_RECOVERY checkpoints carry `shutdown` but are NOT a clean
+	 *   close of the native run: the seed keeps consuming xids afterwards,
+	 *   so sealing here would let a joiner adopt a mid-run stale high-water
+	 *   (the same 8.A window the begin_native_run unseal closes for the
+	 *   multi-pass case).  Only a true shutdown checkpoint seals.
+	 *
+	 * - An unsupported native era (MultiXacts created, or past the
+	 *   prehistory cap) SKIPS the seal with a WARNING instead of FATALing:
+	 *   the refusal still lands fail-closed on every joiner (53RB5,
+	 *   authority unsealed), but the seed itself can shut down cleanly
+	 *   instead of wedging every later shutdown/boot in a FATAL loop.
+	 */
+	if (shutdown && !(flags & CHECKPOINT_END_OF_RECOVERY)
+		&& cluster_shared_catalog && !cluster_enabled)
+	{
+		uint64 native_hw = U64FromFullTransactionId(checkPoint.nextXid);
+
+		if (checkPoint.nextMulti > FirstMultiXactId)
+			ereport(WARNING,
+					(errmsg("native-era seed loads that create MultiXacts are not supported; "
+							"leaving the shared XID authority unsealed"),
+					 errdetail("Shutdown checkpoint nextMulti is %u, but only %u is supported.",
+							   checkPoint.nextMulti, FirstMultiXactId),
+					 errhint("Joiners will fail closed (53RB5); recreate the seed without "
+							 "MultiXact-producing operations, or move the load in-protocol.")));
+		else if (cluster_xid_prehistory_payload_bytes(native_hw) == 0)
+			ereport(WARNING,
+					(errmsg("native-era xid high-water %llu is outside the prehistory publish "
+							"range; leaving the shared XID authority unsealed",
+							(unsigned long long) native_hw),
+					 errhint("Joiners will fail closed (53RB5); split the seed load or move "
+							 "it in-protocol.")));
+		else
+		{
+			cluster_xid_prehistory_publish(DataDir, native_hw);
+			cluster_xid_authority_publish_native(native_hw, checkPoint.nextMulti, true);
+			elog(LOG, "cluster shared_catalog: published and sealed native-era XID authority high-water %llu",
+				 (unsigned long long) native_hw);
+		}
+	}
+
+#endif
+
 	/*
 	 * Let smgr do post-checkpoint cleanup (eg, deleting old files).
 	 */

src/backend/access/transam/xlogrecovery.c

@@ -3273,8 +3273,16 @@ ApplyWalRecord(XLogReaderState *xlogreader, XLogRecord *record, TimeLineID *repl
 
 	/*
 	 * ShmemVariableCache->nextXid must be beyond record's xid.
+	 *
+	 * PGRAC: a merged-recovery FOREIGN record belongs to a peer's xid
+	 * authority, not this node's allocator.  Advancing the local nextXid here
+	 * would make StartupCLOG/TrimCLOG expect local pg_xact pages for peer
+	 * striped xids, while the peer outcome truth lives in pg_xact_remote.
 	 */
-	AdvanceNextFullTransactionIdPastXid(record->xl_xid);
+#ifdef USE_PGRAC_CLUSTER
+	if (!(cluster_recmerge_window_active && cluster_recmerge_apply_foreign))
+#endif
+		AdvanceNextFullTransactionIdPastXid(record->xl_xid);
 
 	/*
 	 * Before replaying this record, check if this record causes the current

src/backend/cluster/Makefile

@@ -143,6 +143,8 @@ OBJS = \
 	cluster_lmd_wait_state.o \
 	cluster_lmon.o \
 	cluster_lms.o \
+	cluster_lms_data_plane.o \
+	cluster_lms_outbound.o \
 	cluster_lns.o \
 	cluster_membership.o \
 	cluster_mrp.o \
@@ -220,6 +222,8 @@ OBJS = \
 	cluster_views.o \
 	cluster_wal_state.o \
 	cluster_wal_thread.o \
+	cluster_xid_authority.o \
+	cluster_xid_prehistory.o \
 	cluster_xid_stripe.o \
 	cluster_xid_stripe_boot.o \
 	cluster_xid_stripe_xlog.o \

src/backend/cluster/cluster_backup.c

@@ -1099,6 +1099,7 @@ cluster_backup_coord_request(ClusterBackupWireOp op, const char *backup_id,
 	}
 	cluster_backup_state->coordinator_send_pending = true;
 	LWLockRelease(&cluster_backup_state->lock.lock);
+	cluster_lmon_duty_mark_dirty(CLUSTER_LMON_DUTY_BACKUP); /* spec-7.2 D1 */
 	cluster_lmon_wakeup();
 
 	started_at = GetCurrentTimestamp();
@@ -1278,6 +1279,7 @@ cluster_backup_lmon_queue_peer_reply(const ClusterBackupWireAck *reply, int32 de
 	cluster_backup_state->peer_reply_dest = dest;
 	cluster_backup_state->peer_reply_pending = true;
 	LWLockRelease(&cluster_backup_state->lock.lock);
+	cluster_lmon_duty_mark_dirty(CLUSTER_LMON_DUTY_BACKUP); /* spec-7.2 D1 */
 }
 
 static bool
@@ -1301,6 +1303,7 @@ cluster_backup_lmon_start_restore_point_prepare(const ClusterBackupWireRequest *
 		cluster_backup_lmon_prepare_started_at = cluster_backup_restore_point_fence_start();
 		cluster_backup_lmon_restore_point_prepare_pending = true;
 		cluster_backup_lmon_set_prepare_pending(true);
+		cluster_lmon_duty_mark_dirty(CLUSTER_LMON_DUTY_BACKUP); /* spec-7.2 D1 */
 		return false;
 	}
 
@@ -1712,6 +1715,7 @@ cluster_backup_request_handler(const ClusterICEnvelope *env, const void *payload
 		cluster_backup_state->peer_command_pending = true;
 	}
 	LWLockRelease(&cluster_backup_state->lock.lock);
+	cluster_lmon_duty_mark_dirty(CLUSTER_LMON_DUTY_BACKUP); /* spec-7.2 D1 */
 	cluster_lmon_wakeup();
 }
 
@@ -1896,6 +1900,8 @@ cluster_backup_lmon_process_peer_command(void)
 void
 cluster_backup_lmon_tick(void)
 {
+	bool in_flight;
+
 	if (cluster_backup_state == NULL || !cluster_enabled)
 		return;
 
@@ -1906,6 +1912,26 @@ cluster_backup_lmon_tick(void)
 	cluster_backup_lmon_advance_restore_point_prepare();
 	cluster_backup_lmon_send_peer_reply();
 	cluster_backup_maybe_auto_restore_point();
+
+	/*
+	 * PGRAC: spec-7.2 D1 -- the backup protocol is multi-phase and its
+	 * advance steps are time-driven (fence quiesce), not producer-driven.
+	 * While any operation is in flight, self-re-mark the duty so the
+	 * lazy gate keeps the legacy every-iteration cadence until the
+	 * protocol settles; steady state (no backup) reaps the lazy skip.
+	 */
+	if (cluster_backup_lmon_restore_point_prepare_pending)
+		in_flight = true;
+	else {
+		LWLockAcquire(&cluster_backup_state->lock.lock, LW_SHARED);
+		in_flight = cluster_backup_state->peer_reply_pending
+					|| cluster_backup_state->coordinator_send_pending
+					|| cluster_backup_state->peer_command_pending
+					|| cluster_backup_state->peer_restore_point_prepare_pending;
+		LWLockRelease(&cluster_backup_state->lock.lock);
+	}
+	if (in_flight)
+		cluster_lmon_duty_mark_dirty(CLUSTER_LMON_DUTY_BACKUP);
 }
 
 static void