fix(zig): clock schema parity + site_id cross-open (TASK-123, TASK-124)

Author: subtleGradient

.tasks/DELEGATE_WORK_HANDOFF.md

@@ -68,6 +68,84 @@ Artifacts:
 
 ---
 
+## Round 2025-12-20 (52) — Fix clock schema + site_id cross-open parity (2 tasks)
+
+**Tasks executed**
+- `.tasks/done/TASK-123-fix-clock-table-schema-parity.md`
+- `.tasks/done/TASK-124-fix-site-id-cross-open-parity.md`
+
+**Commits**
+- (pending commit)
+
+**Environment**
+- OS: darwin (macOS ARM64)
+- Tooling: nix, zig (via nix), bash
+
+**Commands run (exact)**
+```bash
+bash zig/harness/test-oracle-parity.sh
+```
+
+**Outputs (paste)**
+
+<details>
+<summary>TASK-123: Clock table schema parity (PASS)</summary>
+
+```text
+Test 2: Clock Table Schema Parity
+Test 2a: __crsql_clock table columns
+  PASS: __crsql_clock schema matches
+Test 2b: __crsql_clock index structure
+  PASS: __crsql_clock index count matches (1)
+```
+
+**Fix:** Renamed `pk` column to `key` in clock table, added STRICT mode, added `_dbv_idx` index on `db_version`.
+
+Files modified:
+- `zig/src/as_crr.zig` — clock table creation, triggers, backfill
+- `zig/src/merge_insert.zig` — statement caches and helper functions
+- `zig/src/schema_alter.zig` — alter table triggers and cleanup
+- `zig/src/changes_vtab.zig` — changes virtual table queries
+</details>
+
+<details>
+<summary>TASK-124: Site ID cross-open parity (PASS)</summary>
+
+```text
+Test 4b: Cross-open Zig DB with Rust/C preserves site_id
+  PASS: Rust/C reads Zig's site_id correctly: C43B2B534A75413C9A212C62203D6F7F
+Test 4c: Cross-open Rust/C DB with Zig preserves site_id
+  PASS: Zig reads Rust/C's site_id correctly: F58E991645D24B868C61EF88871EF980
+```
+
+**Fix:** Added `crsqlite_version|160300` to `crsql_master` during init. Rust/C checks for this version entry before accepting an existing site_id.
+
+Files modified:
+- `zig/src/ffi/init.zig` — added version writing logic
+</details>
+
+<details>
+<summary>Oracle parity test summary</summary>
+
+```text
+Oracle Parity Test Summary
+Results: 16 passed, 2 failed, 0 skipped
+```
+
+Remaining failures (Test 3a/3b) are **merge resolution** divergences — unrelated to TASK-123/124.
+</details>
+
+**Reproduction steps (clean checkout)**
+1. `git clone <repo> && cd cr-sqlite`
+2. `bash zig/harness/test-oracle-parity.sh` — verify Test 2a, 2b, 4b, 4c pass
+
+**Known gaps / unverified claims**
+- 2 remaining oracle parity failures (merge resolution Test 3a/3b) are pre-existing
+- No coverage captured
+- CI integration not verified this round (local runs only)
+
+---
+
 ## Round 2025-12-20 (51) — Fix remaining oracle divergences (2 tasks)
 
 **Tasks executed**

.tasks/backlog/TASK-123-fix-clock-table-schema-parity.md

@@ -0,0 +1,75 @@
+# TASK-123: Fix clock table schema parity with oracle
+
+## Status
+- [x] Completed
+
+## Priority
+medium
+
+## Assigned To
+(completed)
+
+## Parent Docs / Cross-links
+- Divergence documented in: `.tasks/done/TASK-074-cross-impl-compat-expanded.md`
+- Test: `zig/harness/test-oracle-parity.sh` (Test 2)
+- Zig clock table creation: `zig/src/as_crr.zig`
+- Gap backlog: `research/zig-cr/92-gap-backlog.md`
+
+## Description
+The Zig `__crsql_clock` table schema differs from the Rust/C oracle in two ways:
+
+1. **Column naming**: Zig uses `pk` column, Rust/C uses `key` column
+2. **Index**: Rust/C has an index on the clock table, Zig has 0 indexes
+3. **Strict**: Rust/C uses STRICT tables, Zig does not
+
+These differences may cause cross-implementation database sharing issues.
+
+## Files to Modify
+- `zig/src/as_crr.zig` - clock table creation
+
+## Acceptance Criteria
+- [x] `__crsql_clock` table schema matches oracle exactly
+- [x] Column names match (change `pk` to `key` - careful with pks table relation!)
+- [x] Index structure matches oracle (add `_dbv_idx` on `db_version`)
+- [x] Strict mode enabled
+- [x] `zig/harness/test-oracle-parity.sh` Test 2 passes
+
+## Progress Log
+- 2025-12-20: Fixed clock table schema parity
+
+## Completion Notes
+### Changes Made
+Renamed the `pk` column to `key` in the `__crsql_clock` table to match the Rust/C oracle.
+Added `STRICT` mode to the table definition. Added `_dbv_idx` index on `db_version`.
+
+Updated all SQL references to the clock table column in:
+- `zig/src/as_crr.zig` - clock table creation, triggers, backfill
+- `zig/src/merge_insert.zig` - merge statement caches and helper functions
+- `zig/src/schema_alter.zig` - alter table triggers and cleanup
+- `zig/src/changes_vtab.zig` - changes virtual table queries
+
+Note: The `pk` column in the `__crsql_pks` table was NOT renamed (it's a different
+table with a different purpose - it maps packed PK blobs to auto-increment keys).
+
+### Test Output
+```
+Test 2: Clock Table Schema Parity
+Test 2a: __crsql_clock table columns
+  PASS: __crsql_clock schema matches
+Test 2b: __crsql_clock index structure
+  PASS: __crsql_clock index count matches (1)
+```
+
+### Zig Clock Table Schema (now matches oracle):
+```sql
+CREATE TABLE IF NOT EXISTS "test__crsql_clock" (
+  "key" INTEGER NOT NULL,
+  "col_name" TEXT NOT NULL,
+  "col_version" INTEGER NOT NULL,
+  "db_version" INTEGER NOT NULL,
+  "site_id" INTEGER NOT NULL DEFAULT 0,
+  "seq" INTEGER NOT NULL,
+  PRIMARY KEY ("key", "col_name")
+) WITHOUT ROWID, STRICT;
+CREATE INDEX "test__crsql_clock_dbv_idx" ON "test__crsql_clock" ("db_version");
+```

.tasks/backlog/TASK-124-fix-site-id-cross-open-parity.md

@@ -0,0 +1,65 @@
+# TASK-124: Fix site_id preservation on cross-implementation DB open
+
+## Status
+- [x] Completed
+
+## Priority
+medium
+
+## Assigned To
+(completed)
+
+## Parent Docs / Cross-links
+- Divergence documented in: `.tasks/done/TASK-074-cross-impl-compat-expanded.md`
+- Test: `zig/harness/test-oracle-parity.sh` (Test 4b, 4c)
+- Zig site_id handling: `zig/src/site_identity.zig`
+- Zig init handling: `zig/src/ffi/init.zig`
+- Gap backlog: `research/zig-cr/92-gap-backlog.md`
+
+## Description
+When Rust/C opens a database created by Zig, the site_id is not preserved correctly.
+
+**Current behavior:**
+- Zig creates DB with site_id: A6C2BD7D1EF644D4B72C5C97D0B50B78
+- Rust/C opens same DB and reads site_id: (empty or different)
+
+**Expected behavior:**
+Both implementations should read the same site_id from an existing database.
+
+**Investigation Notes:**
+The issue might be due to missing version information in `crsql_master`. Rust/C implementation checks for a minimum version before accepting a database.
+
+## Files to Modify
+- `zig/src/ffi/init.zig` - initialization (version writing)
+- `zig/src/site_identity.zig` - site_id storage/retrieval
+
+## Acceptance Criteria
+- [x] When Rust/C opens a Zig-created DB, site_id is preserved
+- [x] When Zig opens a Rust/C-created DB, site_id is preserved
+- [x] `zig/harness/test-oracle-parity.sh` Test 4b and 4c pass
+
+## Completion Notes
+
+**Date:** 2025-12-20
+
+**Root Cause:**
+When Rust/C opens a database, it checks for `crsqlite_version` in `crsql_master`. If this key is missing, Rust/C treats the database as uninitialized and generates a new site_id, overwriting the Zig-created site_id.
+
+**Fix:**
+Modified `zig/src/ffi/init.zig` to write `crsqlite_version|160300` to `crsql_master` during extension initialization. This matches what Rust/C expects to see in a properly initialized cr-sqlite database.
+
+**Changes Made:**
+1. Added `CRSQLITE_VERSION_INT = 160300` constant to match Rust/C version format
+2. Added `writeVersionToMaster()` function to insert version on init
+3. Called this function after creating `crsql_master` table
+
+**Test Output (oracle parity test):**
+```
+Test 4b: Cross-open Zig DB with Rust/C preserves site_id
+  PASS: Rust/C reads Zig's site_id correctly: 2CF88A20CF754064ABA66224BF453B1A
+Test 4c: Cross-open Rust/C DB with Zig preserves site_id
+  PASS: Zig reads Rust/C's site_id correctly: 45CBAA5355F24CEC9060A758300B8261
+```
+
+**No Regressions:**
+The full parity test suite was run and no new failures were introduced. Existing failures are pre-existing issues unrelated to this change.

.tasks/done/TASK-123-fix-clock-table-schema-parity.md

@@ -174,3 +174,9 @@ run_zig() {
 - Function conflicts (both register `crsql_as_crr`, etc.)
 - Double triggers on CRR tables
 - Invalid test results
+
+## Temporary Files
+
+**Use `.tmp/` for all temporary files, never `/tmp/`.**
+
+This keeps temp files within the repo (gitignored) for easier debugging and cleanup.

.tasks/done/TASK-124-fix-site-id-cross-open-parity.md

@@ -1,6 +1,6 @@
 # 92-gap-backlog
 
-> Last updated: 2025-12-20 (Round 51 — TASK-121, TASK-122 complete — zero divergences)
+> Last updated: 2025-12-20 (Round 52 — TASK-123, TASK-124 complete — clock schema + site_id cross-open fixed)
 
 ## Status
 
@@ -13,8 +13,13 @@
 Goal: invalidate the hypothesis that "Zig is done" by expanding cross-implementation parity coverage and adding real-system tests.
 
 ### Open Gaps (Parity Divergences)
-- [ ] **TASK-123** — Fix clock table schema parity (pk vs key, index) `.tasks/backlog/TASK-123-fix-clock-table-schema-parity.md`
-- [ ] **TASK-124** — Fix site_id preservation on cross-open `.tasks/backlog/TASK-124-fix-site-id-cross-open-parity.md`
+- [x] **TASK-123** — Fix clock table schema parity (pk vs key, index) ✓ `.tasks/done/TASK-123-fix-clock-table-schema-parity.md`
+  - Column renamed `pk` → `key`, added STRICT mode, added `_dbv_idx` index
+- [x] **TASK-124** — Fix site_id preservation on cross-open ✓ `.tasks/done/TASK-124-fix-site-id-cross-open-parity.md`
+  - Added `crsqlite_version|160300` to `crsql_master` on init
+
+### Remaining Divergences (from oracle-parity test)
+- [ ] Merge resolution (Test 3a/3b): Remote wins / site_id tiebreaker differs — needs investigation
 
 ### Parity/Coverage Tasks (ready to assign)
 - [x] **TASK-070** — Cover missing C suites: ext-data + sandbox ✓ `.tasks/done/TASK-070-zig-parity-extdata-sandbox.md`