docs: document PostgreSQL compatibility workflow

Author: renecannao

README.md

@@ -64,6 +64,26 @@ make build-sqlengine    # Interactive SQL CLI
 make build-corpus-test  # Corpus validation harness
 ```
 
+### PostgreSQL compatibility harness
+
+ParserSQL uses `libpg_query` as the PostgreSQL syntax oracle for compatibility checks. The harness pins `libpg_query` `17-latest` and `18-latest`, extracts accepted PostgreSQL regression statements, and compares ParserSQL behavior against the committed PostgreSQL 18 baseline in [`docs/compatibility/postgresql-18.md`](docs/compatibility/postgresql-18.md).
+
+Compatibility results separate full parser parity from classification coverage:
+
+- `DEEP_SUPPORTED` means ParserSQL accepted the statement with the expected statement type and a full AST.
+- `CLASSIFIED_ONLY` means ParserSQL recognized the top-level statement class, but did not produce full deep parser parity for that SQL.
+- `PARTIAL`, `ERROR`, `TRAILING_INPUT`, and `TYPE_MISMATCH` are tracked separately in the committed baseline.
+
+The report includes the full PostgreSQL 18 backlog, the PG17-to-PG18 release delta, statement routing coverage, and reviewed structural grammar/keyword changes.
+
+```bash
+make test-pg-compat     # Build the pinned oracle runner, run harness unit tests, and replay committed CI cases
+make pg-compat          # Run the full pinned PG17/PG18 comparison against the committed baseline
+make pg-compat-refresh  # Regenerate expected_results.jsonl, ci_cases.jsonl, and docs/compatibility/postgresql-18.md
+```
+
+`PG_COMPAT_CACHE` controls where external `libpg_query` and PostgreSQL source checkouts are cached. It defaults to `/tmp/parsersql-pg-compat`.
+
 ### Interactive CLI (`sqlengine`)
 
 ```bash

docs/benchmarks/REPRODUCING.md

@@ -9,7 +9,7 @@ Step-by-step instructions to reproduce all comparison benchmarks from scratch on
 ```bash
 # Required tools
 sudo apt-get update
-sudo apt-get install -y build-essential git curl
+sudo apt-get install -y build-essential git curl tar bzip2
 
 # Rust (for sqlparser-rs benchmark)
 curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
@@ -19,6 +19,9 @@ source ~/.cargo/env
 g++ --version    # need GCC 8+ (C++17 support)
 cargo --version  # need Rust 1.70+
 git --version
+curl --version
+tar --version
+python3 --version
 ```
 
 ---
@@ -76,6 +79,44 @@ ls -la third_party/libpg_query/libpg_query.a
 
 ---
 
+## PostgreSQL Compatibility Harness
+
+The PostgreSQL compatibility harness uses pinned `libpg_query` builds as the syntax oracle. It compares ParserSQL against PostgreSQL 17 and PostgreSQL 18 regression SQL, writes a committed PostgreSQL 18 baseline, and reports the PG17-to-PG18 syntax delta in `docs/compatibility/postgresql-18.md`.
+
+Required external tools:
+
+```text
+git
+curl
+tar with bzip2 support
+python3
+C/C++ compiler
+make
+```
+
+`PG_COMPAT_CACHE` controls where external sources and built oracle runners are cached. It defaults to `/tmp/parsersql-pg-compat`.
+
+```bash
+# Fast deterministic gate: unit tests plus committed CI cases
+make test-pg-compat
+
+# Full pinned PG17/PG18 comparison against committed expected_results.jsonl
+make pg-compat
+
+# Refresh committed artifacts after intentionally updating pins or mappings
+make pg-compat-refresh
+```
+
+The harness result model distinguishes parser depth from statement routing:
+
+- `DEEP_SUPPORTED` means ParserSQL accepted the SQL with the expected statement type and a full AST.
+- `CLASSIFIED_ONLY` means ParserSQL recognized the top-level statement class, but did not reach full parser parity for that SQL.
+- `PARTIAL`, `ERROR`, `TRAILING_INPUT`, and `TYPE_MISMATCH` are committed baseline outcomes that must not regress silently.
+
+The refresh target updates `tests/pg_compat/expected_results.jsonl`, `tests/pg_compat/ci_cases.jsonl`, and `docs/compatibility/postgresql-18.md`.
+
+---
+
 ## Step 4: Build the comparison benchmark
 
 ```bash