draft: spec-6.0a production shared-storage backend matrix

[sqlrush]

Status

Spec-6.0a early implementation / draft PR. This branch is PR-ready for review and CI exposure, but remains merge-blocked: do not merge until spec-5.19 + 5.21 beta close-out, Stage 6 entry, and a final D0 re-ground against current origin/main are complete.

Not shipped. Not a release candidate. No tag or release flow is part of this PR.

Before merge: rebase to then-current origin/main, redo final D0 re-ground, rerun required local/CI gates, and refresh this evidence.

Completed

• Added provider capability framework via ClusterSharedFsCaps, durability/fence capability hooks, barrier_sync, and fence-key registration dispatch.
• Added production block_device shared-storage backend with raw layout superblock, bitmap, directory, extent slots, logical EOF, O_DIRECT validation, and fail-closed startup when required config is absent.
• Added raw extent allocator serialization using GES X when clustered and local flock() when no cluster owner is available.
• Added per-handle in-memory extent cache to avoid per-block metadata walks on normal I/O.
• Added startup raw-layout invariant verification for relation/fork extent ownership overlap defense.
• Fixed the extend crash window by syncing zero-fill before publishing logical EOF.
• Added crash-safe RM_CLUSTER_RAW_LAYOUT metadata WAL records, pg_waldump descriptor wiring, and XLOG magic bump for the new rmgr.
• Wired SYNC_HANDLER_CLUSTER_SHARED and cluster_smgr fsync registration/barrier fallback paths.
• Added SCSI-3 PR fence-driver interface with Linux SG_IO probe/register helpers; unsupported or unavailable PR capability fails closed when scsi3_pr is forced.
• Wired storage advisory callbacks for prefetch/writeback/zeroextend and provider-level hooks.
• Added block-device wait events and updated view/test snapshots to 110 cluster wait events.
• Added raw block-device conformance unit coverage, two-relation raw-layout coverage, and CI-portable TAP coverage in t/332_block_device_backend.pl.
• Added scripts/perf/run-storage-io-matrix.sh, fast/nightly/perf workflow coverage, and report-only perf evidence behavior.
• Completed CLAUDE.md rule 11 style pass: full pgrac banners for new C/H files and PGRAC MODIFICATIONS/local markers for modified PG-original files.
• Removed the off-scope recovery/torn-tail net diff from this storage PR; latest diff against origin/main has no changes to the prior recovery files.

D0 Re-ground After PR #14 / spec-6.5

• Fetched origin/main on 2026-07-01 and confirmed it contains spec-6.5 via merge commit 955d12651b308bd1cc90d33b0202661a325683cf (Merge pull request #14 from sqlrush/spec-6.5-cluster-backup-restore-pitr).
• Rebased spec-6.0a-production-storage onto that origin/main.
• Current PR base: 955d12651b308bd1cc90d33b0202661a325683cf.
• Current PR head: 217e6cb01998bd97bcc89f962698ad955000e31c.
• PR spec-6.5: cluster-aware backup / restore / PITR substrate #14 / 6.5 fail-closed backup/PITR substrate is treated as main fact. This PR preserves that fail-closed substrate and only replays 6.0a production shared-storage backend changes on top.

D0 Notes

• Spec requested SQLSTATE slots 58R02/58R03, but origin/main already allocated class 58 through 58R13; this branch uses 58R14 for cluster_storage_io_alignment and 58R15 for cluster_storage_fence_unavailable to preserve the existing dense roster.
• CI-portable validation uses raw-image block_device coverage. Hardware O_DIRECT block-device and SCSI-3 PR hardware legs remain external/manual before any release decision.
• src/bin/pg_waldump/clusterrawdesc.c is a generated symlink produced by the pg_waldump Makefile from src/backend/access/rmgrdesc/clusterrawdesc.c; it is intentionally not tracked.

Local Validation

Post-6.5-rebase local validation:

• make -s -j4 passed.
• git diff --check origin/main...HEAD passed.
• scripts/ci/check-comment-headers.sh passed.
• scripts/ci/check-scn-cmp-gate.sh passed.
• scripts/ci/check-ges-mode-gate.sh passed.
• scripts/ci/check-no-clog-overlay.sh passed.
• scripts/ci/check-tidy.sh skipped locally because clang-tidy is not installed; GitHub validate installs and runs it.
• make -C src/test/cluster_unit check passed: 137 cluster unit binaries.
• make -C src/test/cluster_tap check PROVE_TESTS="t/018_shared_fs.pl t/332_block_device_backend.pl" passed: 23 TAP tests.
• make -C src/test/cluster_tap check PROVE_TESTS="t/010_views.pl t/030_acceptance.pl t/050_shared_storage_initdb.pl t/200_stage2_acceptance_capability.pl t/226_stage3_mvcc_acceptance_capability.pl t/273_stage4_recovery_acceptance_capability.pl t/332_block_device_backend.pl" passed: 189 TAP tests.
• make -C src/test/cluster_regress check passed: 12 SQL smoke tests.
• Clean archive-copy --disable-cluster build passed in /private/tmp/linkdb-disable-src-60a-d6b70e.
• scripts/perf/run-storage-io-matrix.sh returned unavailable evidence and exit 0 when the default install prefix was absent.

Local note:

• On this macOS workstation, scripts/ci/check-format.sh with clang-format 22 reports existing full-tree formatting differences in non-6.0a cluster files. git diff --check origin/main...HEAD is clean; GitHub fast-gate validate is the authoritative clang-format check for the PR toolchain.

PR CI

• Fast-gate run for head 217e6cb01998bd97bcc89f962698ad955000e31c is running: https://github.com/sqlrush/pgrac/actions/runs/28493851171
• Nightly will be run after fast-gate is green on this rebased head.

Remaining Merge Gate

• Blocked from merge by spec-5.19 + 5.21 beta close-out.
• Final D0 re-ground against then-current origin/main required before merge.
• Rebase to current origin/main and rerun local required gates, fast PR CI, and nightly CI after final re-ground.