Add PG extension build, server-auth, and infra updates

Add end-to-end support for building and publishing the pg_kalam PostgreSQL extension: two GitHub Actions jobs to build extension artifacts for x86_64 and aarch64, package/install scripts, and a docker_pg job to build/push multi-arch PG images. Introduce the pg/ workspace files, tests, Dockerfiles and packaging helpers. Add a new backend crate (kalamdb-server-auth) and make auth crate HTTP integration opt-in; update workspace members and dependencies (including tokio-postgres) and add a compact release profile (release-pg) for smaller extension .so builds. Update backend defaults to enable jemalloc and tweak auth features. Also improve docs/instructions (AGENTS.md and .github/copilot-instructions.md) with performance reminders and workflow tweaks, and apply various repo-wide code/dependency adjustments.

Author: jamals86

.github/copilot-instructions.md

@@ -13,6 +13,12 @@ This file references the main `AGENTS.md` which contains:
 
 Always refer to `AGENTS.md` for the most up-to-date guidelines and best practices.
 
+Priority reminders from `AGENTS.md`:
+- Keep performance as a primary constraint, including compile-time and hot-path costs.
+- Batch related edits before running `cargo check` or `cargo build`.
+- For performance tests, report per-test runtime in seconds.
+- When adding dependencies, enable only the minimal required features.
+
 ## Active Technologies
 - Rust 1.90 (edition 2021) + DataFusion 40, Apache Arrow 52, Apache Parquet 52, Actix-Web 4, `kalamdb-store` EntityStore traits, `kalamdb-commons` system models (007-user-auth)
 - RocksDB 0.24 for buffered writes, Parquet files for flushed segments via StorageBackend abstraction (007-user-auth)

.github/workflows/release.yml

@@ -936,6 +936,178 @@ jobs:
           path: dist/${{ needs.read_version.outputs.version }}/*
           if-no-files-found: error
 
+  # ═══════════════════════════════════════════════════════════════════════════
+  # PG EXTENSION - Build pg_kalam PostgreSQL extension for Linux
+  # ═══════════════════════════════════════════════════════════════════════════
+  build_pg_extension_x86_64:
+    name: Build PG Extension Linux x86_64
+    runs-on: ubuntu-latest
+    needs: read_version
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Build extension in Docker (x86_64 Bookworm)
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          # Build the builder image (Debian Bookworm — matches postgres:16-bookworm)
+          docker build \
+            -f pg/docker/Dockerfile.builder-base \
+            -t pg-kalam-builder-x86 \
+            .
+
+          # Compile extension inside the Bookworm container
+          mkdir -p artifacts
+          docker run --rm \
+            -v "$PWD:/src:ro" \
+            -v "$PWD/artifacts:/artifacts" \
+            -e CARGO_INCREMENTAL=0 \
+            -e RUSTFLAGS="-Cdebuginfo=0" \
+            pg-kalam-builder-x86 \
+            bash -c '
+              cd /src && \
+              cargo pgrx install \
+                -p kalam-pg-extension \
+                -c /usr/bin/pg_config \
+                --no-default-features \
+                --profile release-pg \
+                -F pg16 && \
+              cp /usr/lib/postgresql/16/lib/pg_kalam.so          /artifacts/ && \
+              cp /usr/share/postgresql/16/extension/pg_kalam.control /artifacts/ && \
+              cp /usr/share/postgresql/16/extension/pg_kalam--*.sql  /artifacts/
+            '
+
+      - name: Package extension artifacts
+        shell: bash
+        run: |
+          set -euo pipefail
+          VERSION="${{ needs.read_version.outputs.version }}"
+          PKG="pg_kalam-${VERSION}-pg16-linux-x86_64"
+          mkdir -p "dist/${VERSION}/${PKG}"
+
+          cp artifacts/pg_kalam.so           "dist/${VERSION}/${PKG}/"
+          cp artifacts/pg_kalam.control      "dist/${VERSION}/${PKG}/"
+          cp artifacts/pg_kalam--*.sql       "dist/${VERSION}/${PKG}/"
+
+          cat > "dist/${VERSION}/${PKG}/install.sh" << 'INSTALL_EOF'
+#!/usr/bin/env bash
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PG_CONFIG="${1:-pg_config}"
+LIBDIR="$("$PG_CONFIG" --pkglibdir)"
+SHAREDIR="$("$PG_CONFIG" --sharedir)/extension"
+echo "Installing pg_kalam to $LIBDIR and $SHAREDIR ..."
+install -m 755 "$SCRIPT_DIR/pg_kalam.so" "$LIBDIR/"
+install -m 644 "$SCRIPT_DIR/pg_kalam.control" "$SHAREDIR/"
+install -m 644 "$SCRIPT_DIR"/pg_kalam--*.sql "$SHAREDIR/"
+echo "Done. Run: CREATE EXTENSION pg_kalam;"
+INSTALL_EOF
+          chmod +x "dist/${VERSION}/${PKG}/install.sh"
+
+          (cd "dist/${VERSION}" && tar -czf "${PKG}.tar.gz" "${PKG}")
+          rm -rf "dist/${VERSION}/${PKG}"
+
+          ls -lh "dist/${VERSION}/"
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v6
+        with:
+          name: dist-pg-extension-linux-x86_64
+          path: dist/${{ needs.read_version.outputs.version }}/*
+          if-no-files-found: error
+
+  build_pg_extension_aarch64:
+    name: Build PG Extension Linux ARM64
+    runs-on: ubuntu-latest
+    needs: read_version
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup QEMU
+        uses: docker/setup-qemu-action@v3
+
+      - name: Setup Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Build extension in Docker (ARM64)
+        shell: bash
+        run: |
+          set -euo pipefail
+          VERSION="${{ needs.read_version.outputs.version }}"
+
+          # Build the builder image for ARM64 using QEMU emulation
+          docker buildx build \
+            --platform linux/arm64 \
+            --load \
+            -f pg/docker/Dockerfile.builder-base \
+            -t pg-kalam-builder-arm64 \
+            .
+
+          # Compile extension inside the ARM64 container
+          mkdir -p artifacts
+          docker run --rm --platform linux/arm64 \
+            -v "$PWD:/src:ro" \
+            -v "$PWD/artifacts:/artifacts" \
+            -e CARGO_INCREMENTAL=0 \
+            -e RUSTFLAGS="-Cdebuginfo=0" \
+            pg-kalam-builder-arm64 \
+            bash -c '
+              cd /src && \
+              cargo pgrx install \
+                -p kalam-pg-extension \
+                -c /usr/bin/pg_config \
+                --no-default-features \
+                --profile release-pg \
+                -F pg16 && \
+              cp /usr/lib/postgresql/16/lib/pg_kalam.so          /artifacts/ && \
+              cp /usr/share/postgresql/16/extension/pg_kalam.control /artifacts/ && \
+              cp /usr/share/postgresql/16/extension/pg_kalam--*.sql  /artifacts/
+            '
+
+      - name: Package extension artifacts
+        shell: bash
+        run: |
+          set -euo pipefail
+          VERSION="${{ needs.read_version.outputs.version }}"
+          PKG="pg_kalam-${VERSION}-pg16-linux-aarch64"
+          mkdir -p "dist/${VERSION}/${PKG}"
+
+          cp artifacts/pg_kalam.so           "dist/${VERSION}/${PKG}/"
+          cp artifacts/pg_kalam.control      "dist/${VERSION}/${PKG}/"
+          cp artifacts/pg_kalam--*.sql       "dist/${VERSION}/${PKG}/"
+
+          cat > "dist/${VERSION}/${PKG}/install.sh" << 'INSTALL_EOF'
+#!/usr/bin/env bash
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PG_CONFIG="${1:-pg_config}"
+LIBDIR="$("$PG_CONFIG" --pkglibdir)"
+SHAREDIR="$("$PG_CONFIG" --sharedir)/extension"
+echo "Installing pg_kalam to $LIBDIR and $SHAREDIR ..."
+install -m 755 "$SCRIPT_DIR/pg_kalam.so" "$LIBDIR/"
+install -m 644 "$SCRIPT_DIR/pg_kalam.control" "$SHAREDIR/"
+install -m 644 "$SCRIPT_DIR"/pg_kalam--*.sql "$SHAREDIR/"
+echo "Done. Run: CREATE EXTENSION pg_kalam;"
+INSTALL_EOF
+          chmod +x "dist/${VERSION}/${PKG}/install.sh"
+
+          (cd "dist/${VERSION}" && tar -czf "${PKG}.tar.gz" "${PKG}")
+          rm -rf "dist/${VERSION}/${PKG}"
+
+          ls -lh "dist/${VERSION}/"
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v6
+        with:
+          name: dist-pg-extension-linux-aarch64
+          path: dist/${{ needs.read_version.outputs.version }}/*
+          if-no-files-found: error
+
   # ═══════════════════════════════════════════════════════════════════════════
   # SMOKE TESTS - Run against the pre-built Linux x86_64 binary
   # ═══════════════════════════════════════════════════════════════════════════
@@ -1091,11 +1263,14 @@ jobs:
       - build_linux_aarch64
       - build_windows_x86_64
       - build_macos_arm
+      - build_pg_extension_x86_64
+      - build_pg_extension_aarch64
       - read_version
       - smoke_tests
       - sdk_tests_typescript
       - sdk_tests_dart
       - docker
+      - docker_pg
 
     if: ${{ github.event_name == 'push' || github.event.inputs.github_release == 'true' }}
 
@@ -1396,6 +1571,103 @@ jobs:
         run: |
           echo "::warning::Docker image publish succeeded, but Docker Hub README update failed. Ensure DOCKERHUB_USERNAME is a repo admin and DOCKERHUB_TOKEN has read/write/delete scope."
 
+  # ═══════════════════════════════════════════════════════════════════════════
+  # DOCKER PG - Push PostgreSQL + pg_kalam extension image to Docker Hub
+  # ═══════════════════════════════════════════════════════════════════════════
+  docker_pg:
+    name: Push PG Extension Docker image
+    runs-on: ubuntu-latest
+    needs:
+      - build_pg_extension_x86_64
+      - build_pg_extension_aarch64
+      - read_version
+
+    if: ${{ github.event_name == 'push' || github.event.inputs.docker_push == 'true' }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Download PG extension artifact (x86_64)
+        uses: actions/download-artifact@v4
+        with:
+          name: dist-pg-extension-linux-x86_64
+          path: pg-artifacts-amd64/
+
+      - name: Download PG extension artifact (aarch64)
+        uses: actions/download-artifact@v4
+        with:
+          name: dist-pg-extension-linux-aarch64
+          path: pg-artifacts-arm64/
+
+      - name: Prepare extension files
+        shell: bash
+        run: |
+          set -euo pipefail
+          VERSION="${{ needs.read_version.outputs.version }}"
+
+          # Extract x86_64 tarball
+          mkdir -p pg-ext-amd64
+          tar -xzf "pg-artifacts-amd64/pg_kalam-${VERSION}-pg16-linux-x86_64.tar.gz" -C pg-ext-amd64 --strip-components=1
+
+          # Extract aarch64 tarball
+          mkdir -p pg-ext-arm64
+          tar -xzf "pg-artifacts-arm64/pg_kalam-${VERSION}-pg16-linux-aarch64.tar.gz" -C pg-ext-arm64 --strip-components=1
+
+          echo "=== x86_64 ==="
+          ls -lh pg-ext-amd64/
+          echo "=== aarch64 ==="
+          ls -lh pg-ext-arm64/
+
+      - name: Setup QEMU
+        uses: docker/setup-qemu-action@v3
+
+      - name: Setup Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Login to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Build and push PG image (amd64)
+        uses: docker/build-push-action@v6
+        with:
+          context: pg-ext-amd64
+          file: pg/docker/Dockerfile.release-pg
+          push: true
+          platforms: linux/amd64
+          tags: |
+            jamals86/kalamdb-pg:${{ needs.read_version.outputs.version }}-amd64
+
+      - name: Build and push PG image (arm64)
+        uses: docker/build-push-action@v6
+        with:
+          context: pg-ext-arm64
+          file: pg/docker/Dockerfile.release-pg
+          push: true
+          platforms: linux/arm64
+          tags: |
+            jamals86/kalamdb-pg:${{ needs.read_version.outputs.version }}-arm64
+
+      - name: Create and push multi-arch PG manifest
+        shell: bash
+        run: |
+          set -euo pipefail
+          REPO="jamals86/kalamdb-pg"
+          VERSION="${{ needs.read_version.outputs.version }}"
+
+          docker buildx imagetools create -t "${REPO}:${VERSION}" \
+            "${REPO}:${VERSION}-amd64" \
+            "${REPO}:${VERSION}-arm64"
+
+          docker buildx imagetools create -t "${REPO}:latest" \
+            "${REPO}:${VERSION}-amd64" \
+            "${REPO}:${VERSION}-arm64"
+
+          echo "✅ Multi-arch pg_kalam image: ${REPO}:${VERSION} and ${REPO}:latest"
+
   # ═══════════════════════════════════════════════════════════════════════════
   # INTEGRATION TESTS - Smoke + TypeScript SDK + Dart SDK against Docker image
   # ═══════════════════════════════════════════════════════════════════════════
@@ -1682,7 +1954,7 @@ jobs:
                       continue
 
                   try:
-                  parsed = json.loads(line)
+                      parsed = json.loads(line)
                   except json.JSONDecodeError:
                       continue
 

AGENTS.md

@@ -36,13 +36,16 @@ use kalamdb_commons::models::UserId;
 14. **Tracing Table Field Convention**: In spans/events, log `table_id` (format `namespace.table`) instead of separate `table_namespace` and `table_name` fields.
 15. **No SQL Rewrite in Hot Paths**: Do not add SQL/DML/SELECT rewrite passes in execution hot paths. Prefer type-safe coercion at typed boundaries (parameter binding, scalar coercion, provider write path, DataFusion-native casts/UDFs explicitly invoked by query authors) to avoid extra parse/transform overhead.
 16. **SDK Changes Must Update Docs**: Any change under `link/sdks/**` or SDK bridge crates (for example `link/kalam-link-dart/**`) must also update the corresponding SDK docs in the `KalamSite` repo (typically `../KalamSite/content/sdk/**`) and include appropriate test coverage.
+17. **Performance-First Execution**: Prefer approaches that reduce runtime, allocations, binary size, and compile time; avoid adding abstractions or dependencies that materially slow hot paths or build/test feedback loops without a clear benefit.
+18. **Performance Test Timing**: Whenever you run performance tests, benchmarks, or perf-focused e2e cases, record and report how long each relevant test took in seconds.
 
 > **⚠️ IMPORTANT**: Smoke tests require a running KalamDB server! Start the server first with `cargo run` in the `backend` directory before running smoke tests. The tests will fail if no server is running.
 
 **When adding a new dependency:**
 1. Add it to `Cargo.toml` (root) under `[workspace.dependencies]` with version
 2. Reference it in individual crates using `{ workspace = true }`
 3. Add crate-specific features if needed: `{ workspace = true, features = ["..."] }`
+4. Enable only the features that are actually required; prefer `default-features = false` when defaults pull in unused code or slow compilation.
 
 **To update a dependency version:**
 - Only edit the version in root `Cargo.toml`
@@ -72,6 +75,22 @@ use kalamdb_commons::models::UserId;
 - **Actix-Web Middleware**: Custom authentication extractors and guards
 - **StorageBackend Abstraction**: `Arc<dyn StorageBackend>` isolates RocksDB dependencies
 
+## Project Navigation
+
+- `backend/`: Main Rust server workspace; most database engine work starts here.
+- `backend/crates/`: Core server crates grouped by responsibility; prefer editing the owning crate instead of cross-cutting changes.
+- `cli/`: Kalam CLI, smoke tests, and CLI-facing integration flows.
+- `link/`: SDK bridge workspace and shared link infrastructure.
+- `link/sdks/typescript/`: TypeScript SDK.
+- `link/sdks/dart/`: Dart/Flutter SDK. `link/sdks/dart/lib/src/generated` is generated; regenerate with `link/sdks/dart/build_native_libs.sh`.
+- `link/kalam-link-dart/`: Rust bridge/native layer used by the Dart SDK.
+- `pg/`: PostgreSQL extension workspace for `pg_kalam`; see `pg/pg_kalam.control`, `pg/src/`, `pg/crates/`, and `pg/tests/`.
+- `benchv2/`: Benchmark harness, scenarios, templates, and results for performance work.
+- `ui/`: Frontend/admin UI.
+- `docs/`: Architecture, API, security, and operational documentation.
+- `specs/`: Historical and active design specs by feature/phase.
+- `docker/`: Container builds and local deployment layouts.
+
 ## Project Structure
 backend/crates/
 - kalamdb-api: HTTP/REST + WebSocket server surface, routes, UI asset serving.
@@ -106,13 +125,15 @@ backend/crates/
 - When iterating on multi-file changes, run a single workspace-wide check and capture output to a file, fix all issues, then re-check:
   - Example: `cargo check > batch_compile_output.txt 2>&1`
   - Parse and address all errors/warnings in one pass; avoid running `cargo check` repeatedly after each tiny edit.
+- If a task requires multiple related code changes, finish the full edit batch first and only then run `cargo check` or `cargo build` when validation is actually needed.
 - Re-run `cargo check` only after a meaningful batch of fixes. This keeps feedback fast and focused, and prevents thrashing CI and local builds.
 
 ## Testing (MUST)
 
 - Use `cargo nextest run` for all test executions unless explicitly told otherwise.
 - For CLI e2e tests: run `cargo nextest run --features e2e-tests` **without** `--no-fail-fast`, capture output to a file, then fix failures one-by-one by running only the failing test(s). Re-run the full suite after fixes.
 - For e2e test runs, do NOT pass `--no-fail-fast`. Run normally, fix the first failure, re-run until it passes, then move to the next failing issue.
+- For performance-focused tests, benchmarks, and perf e2e cases, capture and report the runtime for each relevant test in seconds in the final update.
 - Always add `#[ntest::timeout(time)]` to every async test where `time` is the **actual observed runtime** × 1.5 (to cover slower machines).
    - Example: if a test took 40s, set `#[ntest::timeout(60000)]`.
    - Recalculate and update timeouts after significant changes to test behavior or data size.