fix(cluster): stabilize MVP transaction and read completion

PGRAC_VERSION

@@ -1 +1 @@
-0.130.0
+0.130.1

README.md

@@ -6,9 +6,9 @@ PostgreSQL has never had a shared-disk, multi-active cluster (its HA is
 shared-nothing replication). pgrac brings the Oracle RAC model — many nodes,
 one shared database, Cache Fusion / SCN / GES — to PostgreSQL 16.13.
 
-> **First stable MVP: [v0.130.0](docs/release-notes/v0.130.0.md).**
+> **Current stable MVP: [v0.130.1](docs/release-notes/v0.130.1.md).**
 >
-> The CI-qualified MVP now has four valid four-node point-update samples with
+> This correctness maintenance release has four valid four-node point-update samples with
 > 32 clients per node, complete million-row data comparisons, health and
 > outstanding-work checks, and normal shutdown. It also retains the earlier
 > 8/16-client, soak, block-transfer and same-data normal-restart acceptance.
@@ -63,8 +63,8 @@ More diagrams and deep-dives at **[pgrac.dev](https://pgrac.dev)**.
 
 ## Documentation
 
-Start with the [stable MVP guide](docs/mvp/v0.130.0/README.md) and
-[single-host Linux Quick Start](docs/mvp/v0.130.0/quickstart-linux-single-host.md).
+Start with the [stable MVP guide](docs/mvp/v0.130.1/README.md) and
+[single-host Linux Quick Start](docs/mvp/v0.130.1/quickstart-linux-single-host.md).
 The guide links the parameter, system-view and capability references, and
 distinguishes tested single-host operation from unqualified multi-host/failover
 deployment. The historical prerelease manual remains available unchanged.
@@ -87,11 +87,11 @@ from the upstream tree.
 ## Quick start
 
 For the stable MVP, follow the
-[single-host Linux guide](docs/mvp/v0.130.0/quickstart-linux-single-host.md).
+[single-host Linux guide](docs/mvp/v0.130.1/quickstart-linux-single-host.md).
 This is a source release, not a turnkey production installer.
 
 ```bash
-git clone --branch v0.130.0 --single-branch \
+git clone --branch v0.130.1 --single-branch \
   https://github.com/sqlrush/pgrac.git pgrac-mvp1
 cd pgrac-mvp1
 git rev-parse HEAD

docs/mvp/v0.130.1/README.md

@@ -0,0 +1,32 @@
+# PGRAC MVP 维护稳定版使用入口
+
+Author: SqlRush <sqlrush@gmail.com>
+
+版本：`v0.130.1`；PostgreSQL 基线：16.13；发布日期：2026-09-18。
+
+本版修复既有 MVP 范围内的事务等待、一致读及缓冲区清理缺陷；不是性能优化版。
+本候选重新通过四实例正确性 PRE、原数据正常启动及全体正常关闭，发布须通过精确提交的完整 MVP CI。
+不代表生产 HA、崩溃恢复、四台独立主机共享 LUN 或性能目标已认证。
+完整结果与限制见[发布说明](../../release-notes/v0.130.1.md)。
+
+## 从这里开始
+
+按[单机四实例 Quick Start（Linux）](quickstart-linux-single-host.md)拉取标签、编译、初始化及连接。
+使用本机文件系统上的四个独立 PGDATA，共享业务数据；不是四台主机，不需要容器或 GFS2。
+安装步骤沿用已演练示例，本轮没有重新运行 Quick Start 演练。
+
+## 参考手册
+
+详细接口参考保留原发布目录；旧版固定提交及验收声明只属于旧版，获取命令和本版范围以本目录为准。
+
+| 内容 | 文档 |
+|---|---|
+| 共享存储准备、检查与四机边界 | [存储准备](../v0.130.0-mvp.1/storage-preparation.md)、[部署参考](../v0.130.0-mvp.1/01-linux-four-node-deployment.md) |
+| 参数、默认值与配置组合 | [参数手册](../v0.130.0-mvp.1/02-parameters.md) |
+| 系统视图与字段 | [系统视图](../v0.130.0-mvp.1/03-system-views.md) |
+| 核心能力 | [功能与运行机制](../v0.130.0-mvp.1/04-core-capabilities.md) |
+| 当前源码安装选项 | [安装指南](../../user-guide/install.md) |
+
+发布为源码版本，不提供生产认证二进制。保留标签、完整 commit、编译参数、配置与二进制 SHA-256；
+不要仅用旧的 `pgrac_version()` 字符串识别版本。原稳定标签 `v0.130.0` 不变。
+使用独立安装目录评估新版本；本版没有认证滚动/混版本升级、通用数据迁移或降级。

docs/mvp/v0.130.1/quickstart-linux-single-host.md

@@ -0,0 +1,147 @@
+# 单机四实例 Quick Start（Linux，MVP 稳定版）
+
+Author: SqlRush <sqlrush@gmail.com>
+
+目标：一台 Linux 主机、四个 PGRAC 实例、同一份共享业务数据。版本固定为 `v0.130.1`。这是隔离环境中的源码安装示例，不是四机共享 LUN 或生产 HA 安装器。
+
+沿用已演练的 Rocky Linux 9 / Btrfs 单机步骤与初始化示例；本次仅更新维护版标签及文档链接，不声称重新运行了 Quick Start 演练。稳定版 CI 与 PRE 范围见[发布说明](../../release-notes/v0.130.1.md)。
+
+## 1. 准备主机
+
+使用有 `sudo` 权限的普通账号，预留充足内存和至少 20 GiB 磁盘空间。在同一个 Bash 终端执行，不要用 root 运行数据库。
+
+```bash
+bash
+set -euo pipefail
+test "$(id -u)" -ne 0
+umask 077
+
+sudo dnf install -y dnf-plugins-core
+sudo dnf config-manager --set-enabled crb
+sudo dnf install -y gcc make git pkgconf-pkg-config bison flex \
+  perl perl-IPC-Run perl-Test-Simple perl-Time-HiRes \
+  readline-devel zlib-devel libicu-devel lz4-devel libzstd-devel \
+  util-linux procps-ng tar kmod
+test -c /dev/loop-control || sudo modprobe loop
+sudo losetup --find
+
+export PGRAC_QS_ROOT="$(mktemp -d /var/tmp/pgrac-quickstart.XXXXXX)"
+findmnt -T "$PGRAC_QS_ROOT"
+df -h "$PGRAC_QS_ROOT"
+printf '本次安装目录：%s\n' "$PGRAC_QS_ROOT"
+```
+
+目录必须位于本机磁盘，不能使用 NFS 或主机共享映射目录。本机 ext4/XFS 不涉及跨主机挂载，但既有演练使用 Btrfs。示例仅创建自己的三个投票文件及对应 loop 设备，不格式化现有盘。
+
+## 2. 拉取稳定版源码
+
+```bash
+git clone --depth 1 --branch v0.130.1 --single-branch \
+  https://github.com/sqlrush/pgrac.git "$PGRAC_QS_ROOT/source"
+git -C "$PGRAC_QS_ROOT/source" describe --exact-match --tags
+git -C "$PGRAC_QS_ROOT/source" rev-parse HEAD
+test "$(cat "$PGRAC_QS_ROOT/source/PGRAC_VERSION")" = 0.130.1
+```
+
+## 3. 编译安装
+
+示例继续使用不启用 OpenSSL 的本机构建；SQL 只使用 Unix socket，不开放外部 SQL 端口。这不是稳定版的 OpenSSL 构建限制。
+
+```bash
+mkdir "$PGRAC_QS_ROOT/build"
+cd "$PGRAC_QS_ROOT/build"
+../source/configure --prefix="$PGRAC_QS_ROOT/install" \
+  --enable-cluster --enable-cassert --enable-debug --enable-tap-tests \
+  --with-icu --with-lz4 --with-zstd
+make -j4
+make install
+make -C src/test/cluster_tap all
+make -C src/test/regress pg_regress
+
+export PATH="$PGRAC_QS_ROOT/install/bin:$PATH"
+pg_config --configure
+```
+
+## 4. 准备初始化示例
+
+`run-quad.pl` 来自刚拉取的稳定标签中的文档示例，不是额外下载的未知脚本。目录名保留其首次发布版本；示例字节未修改。
+
+```bash
+cp "$PGRAC_QS_ROOT/source/docs/mvp/v0.130.0-mvp.1/quickstart-single-host.pl" \
+  "$PGRAC_QS_ROOT/run-quad.pl"
+printf '%s  %s\n' \
+  0e5fe8670349c33485474f4757744507c9939a4149d2adef06a23f538ae9f4c9 \
+  "$PGRAC_QS_ROOT/run-quad.pl" | sha256sum -c -
+
+mkdir "$PGRAC_QS_ROOT/data" "$PGRAC_QS_ROOT/log"
+cat > "$PGRAC_QS_ROOT/seed.conf" <<'CONF'
+fsync = on
+full_page_writes = on
+synchronous_commit = on
+CONF
+
+export LC_ALL=C
+export PERL5LIB="$PGRAC_QS_ROOT/source/src/test/perl"
+export PG_REGRESS="$PGRAC_QS_ROOT/build/src/test/regress/pg_regress"
+export PGRAC_DIRECT_IO_PROBE="$PGRAC_QS_ROOT/build/src/test/cluster_tap/pgrac_direct_io_probe"
+export top_builddir="$PGRAC_QS_ROOT/build"
+export TEMP_CONFIG="$PGRAC_QS_ROOT/seed.conf"
+export TESTDATADIR="$PGRAC_QS_ROOT/data"
+export TESTLOGDIR="$PGRAC_QS_ROOT/log"
+export PG_TEST_NOCLEAN=1 PG_TEST_TIMEOUT_DEFAULT=180
+export PGRAC_STAGE8_HAPPY_PATH_ONLY=1
+unset PGRAC_TEST_TWO_STAGE_VOTING_LOOP
+```
+
+## 5. 初始化并启动四实例
+
+脚本建立一个数据库身份及四个独立 PGDATA，共享业务数据，自动配置端口、互联与投票设备。`postgres` 数据库中的 `quickstart_demo` 表在 seed 阶段创建后克隆。本示例不启用共享系统目录，运行后不要单独建表、改表或执行 `CREATE DATABASE`。
+
+```bash
+sudo -v
+perl "$PGRAC_QS_ROOT/run-quad.pl" > "$PGRAC_QS_ROOT/launcher.out" 2>&1 &
+export PGRAC_QS_PID=$!
+
+for attempt in $(seq 1 360); do
+  test ! -f "$PGRAC_QS_ROOT/READY" || break
+  if ! kill -0 "$PGRAC_QS_PID" 2>/dev/null; then
+    tail -n 60 "$PGRAC_QS_ROOT/launcher.out"
+    tail -n 60 "$PGRAC_QS_ROOT/log/regress_log_run-quad"
+    exit 1
+  fi
+  sleep 1
+done
+test -f "$PGRAC_QS_ROOT/READY"
+source "$PGRAC_QS_ROOT/connect.env"
+```
+
+`READY` 表示四实例已依次更新同一行并都读到 `value=4`。连接端口和四份 PGDATA 路径见 `connect.env`。
+
+## 6. 验证共享读写
+
+```bash
+for port in "$PGPORT_0" "$PGPORT_1" "$PGPORT_2" "$PGPORT_3"; do
+  psql -X -v ON_ERROR_STOP=1 -p "$port" -c 'TABLE quickstart_demo'
+done
+
+psql -X -v ON_ERROR_STOP=1 -p "$PGPORT_3" \
+  -c 'UPDATE quickstart_demo SET value=value+10 WHERE id=1 RETURNING *'
+psql -X -v ON_ERROR_STOP=1 -p "$PGPORT_0" -c 'TABLE quickstart_demo'
+```
+
+第一次四次查询均应为 `id=1, value=4`；最后 node0 应读到 `value=14`。
+
+## 7. 全体正常关机
+
+```bash
+sudo -v
+touch "$PGRAC_QS_ROOT/STOP"
+wait "$PGRAC_QS_PID"
+test -f "$PGRAC_QS_ROOT/STOPPED"
+
+for datadir in "$PGDATA_0" "$PGDATA_1" "$PGDATA_2" "$PGDATA_3"; do
+  pg_controldata "$datadir" | grep 'Database cluster state'
+done
+```
+
+预期四行均为 `shut down`。脚本完成正常关机验证后仅释放自己创建的 loop 设备，不删除数据。不要强杀、执行 `losetup -D` 或在原目录重复初始化。该脚本只用于新建示例，不是原数据重启工具；失败时保留目录与日志，不能把失败现场当作干净关机数据。

docs/release-notes/README.md

@@ -4,10 +4,11 @@ Author: SqlRush <sqlrush@gmail.com>
 
 ## Current release
 
-[v0.130.0 — first stable MVP](v0.130.0.md) is the current release. It combines
-the MVP release CI gate with four valid four-node correctness samples on the
-CI-fixed kernel. Stable means the documented MVP scope, not production HA,
-independent-host shared-storage certification or a performance guarantee.
+[v0.130.1 — correctness maintenance release](v0.130.1.md) is the current release.
+It repairs transaction-wait, consistent-read and buffer-cleanup defects and has
+four new valid four-node correctness samples. Stable means the documented MVP
+scope, not production HA, independent-host shared-storage certification or a
+performance guarantee. [v0.130.0 — first stable MVP](v0.130.0.md) is unchanged.
 
 [v0.130.0-mvp.1](v0.130.0-mvp.1.md) remains the immutable first evaluation
 snapshot. Its original CI limitation is retained in its historical notes;
@@ -34,6 +35,7 @@ Versions use `MAJOR.MINOR.PATCH`, optionally followed by a prerelease label:
 |---|---|
 | `v0.130.0-mvp.1` | First frozen MVP baseline |
 | `v0.130.0` | First stable release within the documented MVP scope |
+| `v0.130.1` | Correctness maintenance release within the same MVP scope |
 | `-mvp.N`, `-alpha.N`, `-beta.N` | Numbered evaluation prereleases |
 | `-rc.N` | Release candidates with their own published qualification scope |
 | No suffix | Stable release; only after its acceptance criteria pass |
@@ -52,8 +54,8 @@ the superseded release's evidence and limitations.
 ## Selecting a version
 
 ```sh
-git fetch origin tag v0.130.0
-git switch --detach v0.130.0
+git fetch origin tag v0.130.1
+git switch --detach v0.130.1
 git rev-parse HEAD
 cat PGRAC_VERSION
 ```

docs/release-notes/v0.130.1.md

@@ -0,0 +1,93 @@
+# PGRAC v0.130.1 — MVP correctness maintenance
+
+Author: SqlRush <sqlrush@gmail.com>
+
+Release date: 2026-09-18. PostgreSQL base: 16.13. Distribution: source.
+
+This maintenance release follows `v0.130.0` and repairs defects within the same
+qualified MVP scope. It is not a performance-optimization release or a broader
+production-HA certification. The previous tag and its evidence remain unchanged.
+
+## Fixes
+
+- Deliver valid consistent-read refusal replies through the outbound validator,
+  and account for queue non-admission without reporting it as successful delivery.
+- Retire abandoned remote-undo read builds through the existing retry path;
+  preserve identity checks and reject late replies to reused slots.
+- Consume matching deadlock-victim cancellation in exact transaction waits.
+- Preserve prepared update receipts across eligible waits and nested update
+  preparation; prevent an internal temporary-lock/transaction-slot dependency cycle.
+- Honor the original lock-wait budget and complete exact cancellation bookkeeping.
+- Correct statement visibility for local successor versions of foreign transactions.
+- Wait for valid shared-read reservation contention, retry ordinary outbound
+  backpressure, and release only provably quiescent unpublished reservations on error.
+- Reduce ordinary-path log noise while retaining error and refusal diagnostics.
+
+No disk format, protocol format, benchmark workload or configured timeout changes
+are included. Experimental CR scheduling and worker-isolation optimizations are
+not included. Malformed, stale or unauthenticated frames remain rejected.
+
+## Qualification
+
+The new correctness PRE used kernel commit
+[`24e752cc0f619f56f2022e219848a437f0c47789`](https://github.com/sqlrush/pgrac/commit/24e752cc0f619f56f2022e219848a437f0c47789).
+Release preparation changes only version metadata and user documentation from
+that commit; kernel, build and test-runner sources are unchanged.
+
+- Four active instances on one Linux host, 32 clients per instance.
+- Four valid point `UPDATE` + `COMMIT` samples; 5-second warmup and 35-second
+  measurement in each sample, with unchanged correctness rules and timeouts.
+- Zero unexpected client/server errors and no forced cancellation. Every client
+  completed naturally. Raw late-completion codes remain in the evidence and are
+  accepted only by the existing natural-completion correctness policy.
+- Complete ordered byte comparisons of all 1,000,000 rows from every node after
+  each sample; health, invariant and outstanding-work checks passed.
+- Normal startup of retained clean data with full-row verification before work;
+  final coordinated normal shutdown, all four control files shut down, no database
+  process remaining and only the scene's own loop mappings released. Data retained.
+
+| PRE sample | Committed measurement transactions | Cluster TPS |
+|---|---:|---:|
+| 1 | 19,899 | 568.54 |
+| 2 | 18,336 | 523.88 |
+| 3 | 8,355 | 238.71 |
+| 4 | 9,971 | 284.89 |
+
+Median TPS was **404.385**, peak **568.54**. Throughput varied substantially and
+the median is below the previous release's recorded laboratory median. This is
+not a controlled performance comparison or evidence of a speedup. Performance
+analysis and optimization are separate follow-up work, not waived correctness gates.
+
+The assertion-enabled tested PostgreSQL binary SHA-256 is
+`0a5bcbd8143ec8cf9af84331ce3d97e295b6dd5d224f89d3e7d1953cf8cc49d4`.
+The full registered C unit suite contained 311 binaries. The release requires
+successful **Fast CI and MVP Nightly CI on the exact tagged commit**, with every
+required job executed; the GitHub Release carries that exact-commit CI evidence.
+
+Earlier C8/soak/micro/D7 acceptances keep their original candidate identities.
+They were not rerun or relabeled as new executions on this maintenance candidate.
+Historical out-of-MVP tests and their failure records remain available.
+
+## Limits and installation
+
+The [v0.130.0 scope limitations](v0.130.0.md#limits-and-upgrade-guidance) remain:
+no certification of independent-host shared-LUN/GFS2 deployment, crash recovery,
+automatic failover, production external fencing, backup restore, mixed-version
+or rolling upgrades, general data migration/downgrade, or full SQL/2PC compatibility.
+Clean shutdown/restart evidence must not be used as crash-recovery evidence.
+
+Use an independent installation for evaluation and preserve existing data.
+This is a source release, not a signed portable binary package. Identify builds
+by the immutable tag, commit, build flags and binary hash, not the legacy compiled
+`pgrac_version()` string.
+
+```sh
+git clone --branch v0.130.1 --single-branch \
+  https://github.com/sqlrush/pgrac.git pgrac-mvp1
+cd pgrac-mvp1
+git rev-parse HEAD
+cat PGRAC_VERSION
+```
+
+Follow the [maintenance MVP guide](../mvp/v0.130.1/README.md) and
+[Linux single-host four-instance Quick Start](../mvp/v0.130.1/quickstart-linux-single-host.md).