feat(pg/parser): pg-paren-dispatch starmap — oracle harness + audit + CI fence (#106)

Stacked on #105. Adds PG 17 testcontainer oracle harness, 188 hand-curated probes, fuzz harness, PAREN_AUDIT (94 sites), CI workflow, audit lint. See PR for full description.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Author: rebelice

.github/workflows/ci.yml

@@ -31,3 +31,44 @@ jobs:
 
       - name: Test
         run: go test -short ./...
+
+      # SCENARIOS-pg-paren-dispatch.md §5.3 — PAREN_AUDIT lint gate.
+      # Runs on every PR/push; fails CI when a new `(` / `)` dispatch
+      # site is added without a matching row in PAREN_AUDIT.json or
+      # when an aligned=yes row loses its proof_notes.
+      - name: PAREN_AUDIT lint
+        run: go test -run TestPARENAuditLint ./pg/parser/... -count=1 -v
+
+  paren-fuzz:
+    # SCENARIOS-pg-paren-dispatch.md §5.2 — property-based fuzz corpus
+    # run against a PG 17 testcontainer. PAREN_FUZZ_DEFER keeps the job
+    # non-blocking: new mismatches are persisted to
+    # testdata/paren-fuzz-defer/<timestamp>.txt for human triage rather
+    # than auto-failing the pipeline. The strict set-equality gate
+    # (without PAREN_FUZZ_DEFER) remains the developer-side promote
+    # check.
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    strategy:
+      matrix:
+        go-version: ['1.25']
+    env:
+      PAREN_FUZZ_SIZE: '1000'
+      PAREN_FUZZ_DEFER: '1'
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version: ${{ matrix.go-version }}
+
+      - name: Paren fuzz (N=1000, defer mode)
+        run: go test -tags=oracle -timeout 15m -run TestParenOracleFuzz ./pg/parser/... -count=1 -v
+
+      - name: Upload deferred-mismatch artifacts
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: paren-fuzz-defer
+          path: pg/parser/testdata/paren-fuzz-defer/*.txt
+          if-no-files-found: ignore

.github/workflows/container-tests.yml

@@ -25,3 +25,36 @@ jobs:
 
       - name: Container tests (MySQL catalog)
         run: go test -timeout 15m ./mysql/catalog/ -run TestContainer -count=1 -v
+
+  paren-fuzz-nightly:
+    # SCENARIOS-pg-paren-dispatch.md §5.2 — wide-N nightly fuzz run.
+    # N=10000 catches low-frequency paren-dispatch drift that the
+    # PR-gate N=1000 misses. Still uses PAREN_FUZZ_DEFER so a single
+    # fresh mismatch doesn't auto-fail the nightly build; the
+    # timestamped artefact under testdata/paren-fuzz-defer/ is the
+    # triage signal.
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    strategy:
+      matrix:
+        go-version: ['1.25']
+    env:
+      PAREN_FUZZ_SIZE: '10000'
+      PAREN_FUZZ_DEFER: '1'
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version: ${{ matrix.go-version }}
+
+      - name: Paren fuzz nightly (N=10000, defer mode)
+        run: go test -tags=oracle -timeout 55m -run TestParenOracleFuzz ./pg/parser/... -count=1 -v
+
+      - name: Upload deferred-mismatch artifacts
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: paren-fuzz-defer-nightly
+          path: pg/parser/testdata/paren-fuzz-defer/*.txt
+          if-no-files-found: ignore

.github/workflows/paren-oracle.yml

@@ -0,0 +1,47 @@
+name: Paren Oracle
+
+# Dedicated workflow for the pg-paren-dispatch PG 17 testcontainer oracle
+# (SCENARIOS-pg-paren-dispatch.md §5.1). Triggers narrowly on pg/parser/**
+# so the Docker-backed oracle only boots when it would catch drift — the
+# default CI pipeline in ci.yml remains fast for unrelated changes.
+#
+# Timing budget: ≤ 10 min total run. The PG 17 container boots once
+# (sync.Once in paren_oracle_test.go) and all oracle corpus tests plus
+# the fuzz test share it. If the run exceeds 10 min in practice, trim
+# fuzzCorpusSize or shard the oracle corpus.
+#
+# Baseline diff policy: pg/parser/testdata/paren-oracle-baseline.json
+# starts as the empty array; known-diff entries can be tracked like
+# pg/pgregress/known_failures.json. New mismatches fail the build with
+# side-by-side diff (SQL / omni-AST / PG-accept) — the individual
+# oracle test functions (paren_oracle_*_test.go, paren_oracle_fuzz_test.go)
+# already emit this on failure.
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'pg/parser/**'
+      - '.github/workflows/paren-oracle.yml'
+  pull_request:
+    branches: [main]
+    paths:
+      - 'pg/parser/**'
+      - '.github/workflows/paren-oracle.yml'
+
+jobs:
+  paren-oracle:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    strategy:
+      matrix:
+        go-version: ['1.25']
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version: ${{ matrix.go-version }}
+
+      - name: Paren oracle (PG 17 testcontainer)
+        run: go test -tags=oracle -timeout 10m ./pg/parser/... -count=1 -v

docs/plans/2026-04-21-pg-paren-dispatch.md

@@ -164,7 +164,7 @@ A cluster is one PG nonterminal family whose `(` / `)` dispatches are coupled (s
 
 Per cluster, one worker:
 1. **Audit sub-step (C-specific rows):** populate PAREN_AUDIT.md with rows only for sites in this cluster.
-2. **Fix sub-step:** implement section(s) in SCENARIOS-paren-dispatch.md for that cluster.
+2. **Fix sub-step:** implement section(s) in SCENARIOS-pg-paren-dispatch.md for that cluster.
 3. **Close sub-step:** regenerate `pgregress -update`, report `fixed=K, new=0`, update `PAREN_PROGRESS.json`.
 
 Cluster ordering: C1 (highest pgregress density, already validated in Phase 0) → C2 → C3 (coordinate with pg-first-sets) → C4 → C5.
@@ -180,6 +180,22 @@ Dedicated hardening pass (runs in parallel with C2+ cluster work):
 2. Fuzz test: random balanced-paren SQL with interleaved SELECT / JOIN / set-op keywords, compare omni vs PG.
 3. If fuzz surfaces a class of mis-routing, either fix `parenBeginsSubquery` or replace it with T5/T6 (the principled preference per §3).
 
+**Delivered scope (post-Phase 2 acknowledgment):** the landed corpus is
+N=188 probes — 100 PRNG-generated via `fuzzCorpusSize=100` in
+`paren_oracle_fuzz_test.go` (`fuzzSeed=0xBADC0DE1`, deterministic) + 3
+active seed entries in `testdata/paren-fuzz-corpus/seed-cases.txt` + 85
+hand-curated across §2.2–§2.7 (simple/subquery/joined/mixed/LATERAL/
+degenerate). The original "200+ targeting `parenBeginsSubquery`
+specifically" was a rough estimate; in practice the oracle harness
+covers the whole FROM-clause `(` dispatch surface: `parenBeginsSubquery`
+plus LATERAL variants (select_with_parens / XMLTABLE / JSON_TABLE /
+func_table / ROWS FROM), VALUES / TABLE / WITH subqueries, set-op
+operand paren-wrapping, column-list aliases, and the obvious-reject
+perimeter. This is broader than strictly needed for
+`parenBeginsSubquery` alone; the extra coverage is kept for
+defense-in-depth — it's the single cheapest regression fence for every
+Phase-1 fix site (1.1–1.4) that routes through a paren in FROM context.
+
 ### 5.3 The "aligned without code change" bar (answers §8 Q3)
 
 A site can be marked `aligned = yes` without changing code only if **both** of these hold:
@@ -209,13 +225,13 @@ docs/plans/
 pg/parser/
   PAREN_AUDIT.md                        ← audit rows (grows per cluster)
   PAREN_AUDIT.json                      ← machine-readable mirror of AUDIT.md
-  SCENARIOS-paren-dispatch.md           ← per-section fix scenarios
+  SCENARIOS-pg-paren-dispatch.md           ← per-section fix scenarios
   PAREN_PROGRESS.json                   ← cluster/section state + history[]
   paren_*_test.go                       ← per-section tests
   paren_oracle_test.go                  ← Phase 2 PG-container oracle (once landed)
 ```
 
-PAREN_AUDIT.json schema (one array of row objects) mirrors the markdown; kept in sync by the worker skill. Fields: `site` (file:line), `function`, `nonterminals` (array), `ambiguity_present` (bool), `current_technique` (T1..T8 or null), `pg_reference` (gram.y:line), `aligned` (enum: yes / no / blocked / unclear), `blocked_by` (nullable — e.g. "pg-nonterminal-alignment", "pg-first-sets"), `priority` (high/med/low), `section` (nullable scenario id), `proofs` (object: caller_context_argument, empirical_test_file).
+PAREN_AUDIT.json schema (one array of row objects) mirrors the markdown; kept in sync by the worker skill. **Canonical schema doc:** `pg/parser/PAREN_AUDIT_SCHEMA.md` — enforced by `TestPARENAuditLint` on every CI run (SCENARIOS §5.3). Live fields: `site` (file:line, stable audit coordinate), `function` (enclosing Go function), `nonterminals` (array), `ambiguity_present` (bool), `current_technique` (T1..T8 or null), `pg_reference` (gram.y:line), `aligned` (enum: yes / no / blocked / unclear), `blocked_by` (nullable — e.g. "pg-nonterminal-alignment", "pg-first-sets"), `cluster` (C1..C5 with optional subcluster suffix), `priority` (high/med/low), `proof_notes` (free-form caller-context + empirical test citations; required non-empty when aligned=yes), `suspicion_notes` (nullable).
 
 ### 6.2 Skills (to be created after plan approval)