feat(benchmark): Arango/Postgres matched dataframe benchmark with correctness gates and CH-disclosed publication chain

.github/workflows/tests.yaml

@@ -492,6 +492,124 @@ jobs:
           path: ${{ runner.temp }}/backend-conformance
           if-no-files-found: warn
 
+  paired-driver-benchmark:
+    name: factory/paired-driver-benchmark
+    runs-on: ubuntu-latest
+    # Operator acceptance (2026-11-13): the actual speed comparison between
+    # the two real drivers. Both arms run the SAME matched battery against
+    # actual ArangoDB and PostgreSQL services -- the same images, ports,
+    # and health options the backend-conformance lane adjudicates -- plus
+    # the actual ClickHouse service: authoring publishes through the
+    # ClickHouse-backed materialization chain (a ClickHouse-less
+    # deployment cannot author at all -- the 422 MATERIALIZATION_FAILED
+    # the local rehearsal produced is the proof), so this lane runs the
+    # full chain with --publication=run. Each arm materializes into its
+    # own loom_bench_* database; the timed path itself is the
+    # source-row preview route, identical on both arms.
+    # The gate fails closed if either arm is planned/not_run/excluded, if
+    # the chain did not run, or if either driver produced no real timing
+    # samples; a disclosure artifact can never turn this check green.
+    timeout-minutes: 10
+    services:
+      arangodb:
+        image: arangodb:3.12
+        env:
+          ARANGO_NO_AUTH: '1'
+        ports:
+          - 8529:8529
+        options: >-
+          --health-cmd "wget --quiet --tries=1 --spider http://127.0.0.1:8529/_api/version"
+          --health-interval 3s
+          --health-timeout 5s
+          --health-retries 40
+      postgres18:
+        image: postgres:18
+        env:
+          POSTGRES_USER: loom_bench
+          POSTGRES_PASSWORD: loom_ci_test_only
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -h 127.0.0.1 -U loom_bench"
+          --health-interval 3s
+          --health-timeout 5s
+          --health-retries 40
+      clickhouse:
+        image: clickhouse/clickhouse-server:25.3
+        env:
+          CLICKHOUSE_USER: loom_ci
+          CLICKHOUSE_PASSWORD: loom_ci_password
+          CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT: "1"
+        ports:
+          - 9000:9000
+          - 8123:8123
+        options: >-
+          --health-cmd "wget --no-verbose --tries=1 --spider http://127.0.0.1:8123/ping || exit 1"
+          --health-interval 5s
+          --health-timeout 3s
+          --health-retries 20
+    env:
+      LOOM_TEST_ARANGO_URL: http://127.0.0.1:8529
+      LOOM_TEST_POSTGRES_URL: postgresql://loom_bench:loom_ci_test_only@127.0.0.1:5432/loom_bench_paired?sslmode=disable
+      LOOM_BENCH_ADMIN_DSN: postgresql://loom_bench:loom_ci_test_only@127.0.0.1:5432/postgres?sslmode=disable
+      LOOM_BENCH_CH_USER: loom_ci
+      LOOM_BENCH_CH_PASSWORD: loom_ci_password
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: 1.26.5
+          cache: true
+      - name: Set up Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24.x
+      - name: Build the server binary and benchcli from this SHA
+        run: |
+          mkdir -p "$RUNNER_TEMP/paired-bin"
+          go build -o "$RUNNER_TEMP/paired-bin/loom-server" ./cmd/arango-fhir-server
+          go build -o "$RUNNER_TEMP/paired-bin/benchcli" ./internal/dataframe/benchmark/cmd/benchcli
+      - name: Run the paired benchmark against both services
+        # Five interleaved rounds x two measured iterations per driver: the
+        # post-restart process-cold sample plus one warm sample per round
+        # (claims cite the warm cell), one warmup, tiny matched fixture,
+        # full publication chain through the ClickHouse service (each arm
+        # materializes into its own loom_bench_*
+        # database). The script verifies the artifact through the Go
+        # verifier, classifies realness (both arms ran, the chain ran,
+        # both timed), and writes comparison.md; it exits nonzero on any
+        # shortfall, so the job goes red rather than reporting
+        # scaffolding as a comparison.
+        run: >-
+          node scripts/benchmark-backends.mjs --paired
+          --binary "$RUNNER_TEMP/paired-bin/loom-server"
+          --benchcli "$RUNNER_TEMP/paired-bin/benchcli"
+          --profile tiny
+          --iterations 10
+          --warmup 1
+          --rounds 5
+          --source-commit "$GITHUB_SHA"
+          --clickhouse-url clickhouse://127.0.0.1:9000
+          --window-note "granted by the paired-driver-benchmark CI job (isolated services, $GITHUB_RUN_ID)"
+          --out "$RUNNER_TEMP/paired-benchmark"
+      - name: Show the comparison table in the job log
+        if: always()
+        run: |
+          if [ -f "$RUNNER_TEMP/paired-benchmark/comparison.md" ]; then
+            cat "$RUNNER_TEMP/paired-benchmark/comparison.md"
+          else
+            echo "no comparison table: the paired check did not reach a real both-driver comparison" >&2
+          fi
+      - name: Preserve paired benchmark evidence
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: paired-driver-benchmark
+          path: ${{ runner.temp }}/paired-benchmark
+          if-no-files-found: error
+
   node-unit:
     name: Node unit tests
     runs-on: ubuntu-latest