fix(ci): add diagnostics for Linux parity test failures (TASK-156)

- Add debug logging to init.zig (enable via CRSQL_DEBUG=1)
- Add API initialization checks in site_identity UDF functions
- Add diagnostic step to CI workflow to surface extension load issues
- Update task card with investigation findings

Root cause suspected: global sqlite3_api variable visibility in shared
library on Linux differs from Darwin. Diagnostics will confirm if API
pointer is null when UDFs are called.

Author: subtleGradient

.github/workflows/zig-tests.yaml

@@ -146,6 +146,25 @@ jobs:
         working-directory: zig
         run: nix run nixpkgs#zig -- build
 
+      - name: Diagnose extension loading
+        working-directory: zig
+        run: |
+          echo "=== Extension file info ==="
+          ls -la zig-out/lib/
+          file zig-out/lib/libcrsqlite.so
+          echo ""
+          echo "=== SQLite version ==="
+          nix run nixpkgs#sqlite -- --version
+          echo ""
+          echo "=== Test extension load ==="
+          CRSQL_DEBUG=1 nix run nixpkgs#sqlite -- :memory: -cmd ".load zig-out/lib/libcrsqlite.so" "SELECT crsql_version();" 2>&1 || true
+          echo ""
+          echo "=== Test crsql_db_version ==="
+          nix run nixpkgs#sqlite -- :memory: -cmd ".load zig-out/lib/libcrsqlite.so" "SELECT crsql_db_version();" 2>&1 || true
+          echo ""
+          echo "=== Test crsql_site_id ==="
+          nix run nixpkgs#sqlite -- :memory: -cmd ".load zig-out/lib/libcrsqlite.so" "SELECT hex(crsql_site_id());" 2>&1 || true
+
       - name: Run parity tests
         working-directory: zig
         run: make test-parity

.tasks/active/TASK-156-linux-ci-test-parity.md

@@ -54,6 +54,15 @@ This task adds/strengthens Linux execution for the same “canonical” test ent
   - Version mismatch causes extension to load but functions return empty
   - Also 2 failing unit tests in `clset_vtab.zig` (edge case: "_schema" alone)
   - WASM build fails due to Zig 0.14 incompatibility
+- 2025-12-25: Deep investigation of Linux parity test failures:
+  - CI run 20506960231 shows parity tests returning empty values on Linux
+  - Unit tests PASS (same process), parity tests FAIL (cross-process via shell)
+  - Extension loads successfully (no "no such function" errors)
+  - Functions return empty instead of expected values
+  - Root cause investigation: global variable visibility in shared library
+  - Added diagnostic logging to `zig/src/ffi/init.zig` (via CRSQL_DEBUG=1)
+  - Added API initialization checks in `site_identity.zig` functions
+  - Added diagnostic step to CI workflow to surface errors
 
 ## Fixes Applied
 1. **CI Workflow**: Updated `.github/workflows/zig-tests.yaml` to use nix for zig consistently
@@ -65,5 +74,26 @@ This task adds/strengthens Linux execution for the same “canonical” test ent
    - Changed `name.len < suffix.len` to `name.len <= suffix.len`
    - Prevents "_schema" alone from being considered valid (empty base name)
 
+3. **Diagnostic Logging**: Added debug output to init.zig (2025-12-25)
+   - Enable with `CRSQL_DEBUG=1` environment variable
+   - Logs each initialization step and any failures
+   - Added API initialization checks in UDF implementations
+
+4. **CI Diagnostics**: Added "Diagnose extension loading" step
+   - Runs before parity tests to surface extension load issues
+   - Shows file info, sqlite version, and basic function tests
+
+## Investigation Status (2025-12-25)
+**Root cause suspected:** Global variable `sqlite3_api` in `sqlite_c.zig` may not be
+properly shared across shared library boundaries on Linux. The symptom is:
+- Extension init completes successfully (unit tests pass)
+- But when SQLite calls the UDF, the global `sqlite3_api` may be uninitialized
+- This causes `result_int64()` to silently do nothing (null API pointer check)
+
+**Next steps:**
+1. Run CI to capture diagnostic output
+2. If API is null in UDF context, need to investigate Zig's shared library symbol visibility
+3. May need to change global variable to use `export` or different storage class
+
 ## Completion Notes
-(Pending CI verification)
+(Pending CI verification - diagnostics added)

zig/src/ffi/init.zig

@@ -6,7 +6,25 @@
 //! Reference: `core/src/crsqlite.c` (C implementation)
 
 const std = @import("std");
+const builtin = @import("builtin");
 const api = @import("api.zig");
+
+/// Debug logging for extension initialization.
+/// Enabled via CRSQL_DEBUG=1 environment variable.
+/// Uses std.debug.print which writes to stderr on native platforms.
+fn debugLog(comptime fmt: []const u8, args: anytype) void {
+    // Skip debug logging on freestanding/WASM targets
+    if (comptime (builtin.os.tag == .freestanding or builtin.cpu.arch == .wasm32 or builtin.cpu.arch == .wasm64)) {
+        return;
+    }
+
+    // On native platforms, check CRSQL_DEBUG environment variable
+    const debug_env = std.posix.getenv("CRSQL_DEBUG");
+    if (debug_env == null) return;
+    if (!std.mem.eql(u8, debug_env.?, "1")) return;
+
+    std.debug.print("[crsql-init] " ++ fmt ++ "\n", args);
+}
 const after_write = @import("../local_writes/after_write.zig");
 const as_crr = @import("../as_crr.zig");
 const automigrate = @import("../automigrate.zig");
@@ -189,11 +207,15 @@ pub export fn sqlite3_crsqlite_init(
 ) callconv(.c) c_int {
     _ = pzErrMsg; // TODO: use for detailed error messages
 
+    debugLog("sqlite3_crsqlite_init called", .{});
+
     // Initialize the global API pointer (SQLITE_EXTENSION_INIT2 equivalent)
     const init_rc = api.initApi(pApi);
     if (init_rc != api.SQLITE_OK) {
+        debugLog("initApi failed with rc={d}", .{init_rc});
         return init_rc;
     }
+    debugLog("initApi succeeded", .{});
 
     // Enable trusted_schema so our INNOCUOUS functions can be called from triggers.
     // Without this, SQLite 3.31.0+ rejects functions in triggers by default.
@@ -210,8 +232,10 @@ pub export fn sqlite3_crsqlite_init(
         null,
     );
     if (create_master_rc != api.SQLITE_OK) {
+        debugLog("create crsql_master failed with rc={d}", .{create_master_rc});
         return create_master_rc;
     }
+    debugLog("crsql_master table created", .{});
 
     // Write the crsqlite_version to crsql_master for cross-implementation compatibility.
     // This is critical: when Rust/C opens a Zig-created database, it checks this version
@@ -221,8 +245,10 @@ pub export fn sqlite3_crsqlite_init(
     // Using INSERT OR IGNORE so we don't overwrite an existing version on re-open.
     const write_version_rc = writeVersionToMaster(db);
     if (write_version_rc != api.SQLITE_OK) {
+        debugLog("writeVersionToMaster failed with rc={d}", .{write_version_rc});
         return write_version_rc;
     }
+    debugLog("version written to crsql_master", .{});
 
     // Create crsql_tracked_peers table for tracking peer sync state.
     // Reference: core/rs/core/src/bootstrap.rs
@@ -248,23 +274,31 @@ pub export fn sqlite3_crsqlite_init(
         null,
     );
     if (create_tracked_peers_rc != api.SQLITE_OK) {
+        debugLog("create crsql_tracked_peers failed with rc={d}", .{create_tracked_peers_rc});
         return create_tracked_peers_rc;
     }
+    debugLog("crsql_tracked_peers table created", .{});
 
     // Initialize site_id (creates table if needed, loads or generates site_id)
     if (!site_identity.initSiteId(db)) {
+        debugLog("initSiteId failed", .{});
         return api.SQLITE_ERROR;
     }
+    debugLog("site_id initialized", .{});
 
     // Initialize db_version from existing clock tables
     site_identity.initDbVersionFromDb(db);
+    debugLog("db_version initialized to {d}", .{site_identity.getDbVersion()});
 
     // Register functions
     const func_rc = registerFunctions(db);
     if (func_rc != api.SQLITE_OK) {
+        debugLog("registerFunctions failed with rc={d}", .{func_rc});
         return func_rc;
     }
+    debugLog("functions registered successfully", .{});
 
+    debugLog("sqlite3_crsqlite_init completed successfully", .{});
     return api.SQLITE_OK;
 }
 

zig/src/site_identity.zig

@@ -329,6 +329,12 @@ fn crsqlSiteIdFunc(
         return;
     }
 
+    // Check if API is properly initialized
+    if (!api.isInitialized()) {
+        api.result_error(pCtx, "crsql: API not initialized in site_id", -1);
+        return;
+    }
+
     // Get the database handle for THIS connection
     const db = api.context_db_handle(pCtx);
     if (db == null) {
@@ -371,6 +377,13 @@ fn crsqlDbVersionFunc(
         return;
     }
 
+    // Check if API is properly initialized
+    if (!api.isInitialized()) {
+        // API not initialized - this would explain empty results
+        api.result_error(pCtx, "crsql: API not initialized in db_version", -1);
+        return;
+    }
+
     // Return the current db_version from global state
     // Note: We skip checking pre_compact_dbversion here because:
     // 1. It requires a nested SQL query which can cause issues