++

Author: subtleGradient

.gitignore

@@ -23,3 +23,4 @@ zig/*.o
 # WASM build artifacts
 zig/wasm-build/build/
 zig/wasm-build/dist/
+.tmp/

.tasks/active/TASK-119-fix-realistic-sync-test-failures.md

@@ -0,0 +1,68 @@
+# TASK-119: Fix realistic sync/offline test failures (extra rows after merge)
+
+## Status
+- [ ] Planned
+- [x] Assigned
+- [ ] In Progress
+- [ ] Blocked (reason: ...)
+- [ ] Complete
+
+## Priority
+high
+
+## Assigned To
+(to be assigned during delegation)
+
+## Parent Docs / Cross-links
+- Test scripts:
+  - `zig/harness/test-realistic-sync.sh` (2 failures)
+  - `zig/harness/test-realistic-offline.sh` (2 failures)
+- Gap backlog: `research/zig-cr/92-gap-backlog.md`
+- Related: Backfill tests `zig/harness/test-backfill.sh`
+- Follow-up for TASK-120 (consolidated — same root cause)
+
+## Description
+Both realistic test scripts fail with the same pattern: **extra rows after merge**.
+
+### test-realistic-sync.sh (2 failures)
+**Observed behavior:**
+- After Alice and Bob sync, both have 6 todos instead of 4
+- Data shows extra empty rows (id 101, 102 appear twice — once with data, once empty)
+
+**Expected behavior:**
+- After sync, both should have exactly 4 unique todos:
+  - Alice's: id=1 "Buy groceries", id=2 "Walk the dog"
+  - Bob's: id=101 "Call mom", id=102 "Fix bike"
+
+### test-realistic-offline.sh (2 failures)
+**Observed behavior:**
+- Field worker and server have 6 inspections instead of 5
+- Extra rows created during merge
+
+**Hypothesis (shared root cause):**
+This could be related to:
+1. Merge logic creating duplicate entries when applying changes
+2. Sentinel rows being incorrectly materialized as real rows
+3. `INSERT INTO crsql_changes` creating base table rows it shouldn't
+4. Test script logic issue (query or assertion bug)
+
+## Files to Modify
+- `zig/harness/test-realistic-sync.sh` (if test bug)
+- `zig/harness/test-realistic-offline.sh` (if test bug)
+- `zig/src/merge_insert.zig` (if merge logic bug)
+- `zig/src/changes_vtab.zig` (if changes query bug)
+
+## Acceptance Criteria
+- [ ] `bash zig/harness/test-realistic-sync.sh` passes with 0 failures
+- [ ] `bash zig/harness/test-realistic-offline.sh` passes with 0 failures
+- [ ] After bidirectional sync, both databases contain exactly the same data
+- [ ] No duplicate rows created during merge
+- [ ] Root cause documented in Completion Notes
+
+## Progress Log
+### 2025-12-20
+- Test discovered during Round 49 delegation prep
+- Both tests show same symptom: extra rows after merge (6 instead of expected 4-5)
+- Consolidated with TASK-120 as likely same root cause
+
+## Completion Notes

.tasks/backlog/TASK-102-fix-oracle-crsqlite-dylib-alter.md

@@ -0,0 +1,50 @@
+# TASK-120: Fix realistic offline test failures
+
+## Status
+- [ ] Planned
+- [ ] Assigned
+- [ ] In Progress
+- [x] Blocked (reason: Consolidated into TASK-119 — same root cause)
+- [ ] Complete
+
+## Priority
+high
+
+## Assigned To
+(to be assigned during delegation)
+
+## Parent Docs / Cross-links
+- Test script: `zig/harness/test-realistic-offline.sh`
+- Gap backlog: `research/zig-cr/92-gap-backlog.md`
+- Related: `TASK-119` (similar sync test failures)
+
+## Description
+The realistic offline test (`test-realistic-offline.sh`) currently fails with 2 scenarios.
+
+The test demonstrates offline-first sync patterns:
+1. Offline accumulation (changes accumulate locally)
+2. Sync cursor (incremental sync with db_version)
+3. Bidirectional sync (pull/push)
+4. Concurrent edit merge
+
+**Investigation needed:**
+- Identify which 2 scenarios fail
+- Determine if this is related to TASK-119 (same root cause)
+- Fix either test assertions or implementation
+
+## Files to Modify
+- `zig/harness/test-realistic-offline.sh` (if test bug)
+- `zig/src/merge_insert.zig` (if merge logic bug)
+- `zig/src/changes_vtab.zig` (if changes query bug)
+
+## Acceptance Criteria
+- [ ] `bash zig/harness/test-realistic-offline.sh` passes with 0 failures
+- [ ] All 4 key patterns demonstrated work correctly
+- [ ] Root cause documented in Completion Notes
+
+## Progress Log
+### 2025-12-20
+- Test discovered during Round 49 delegation prep
+- 2 failures observed, details TBD
+
+## Completion Notes

.tasks/backlog/TASK-120-fix-realistic-offline-test-failures.md

@@ -0,0 +1,121 @@
+# TASK-102: Fix/replace local `lib/crsqlite.dylib` oracle for ALTER TABLE tests
+
+## Status
+- [ ] Planned
+- [ ] Assigned
+- [ ] In Progress
+- [ ] Blocked (reason: ...)
+- [x] Complete
+
+## Priority
+medium
+
+## Assigned To
+Zig Implementation Agent
+
+## Parent Docs / Cross-links
+- Oracle parity test: `zig/harness/test-alter-parity.sh`
+- Root repo dylib (broken for ALTER): `lib/crsqlite.dylib`
+- sqlite-cr wrapper (working oracle): `nix run github:subtleGradient/sqlite-cr`
+- Rust alter implementation (reference): `core/rs/core/src/alter.rs`
+- Origin task: `.tasks/active/TASK-094-alter-table-history-preservation.md`
+
+## Description
+TASK-094 uncovered that the repo-local oracle dylib (`lib/crsqlite.dylib`) fails during `crsql_commit_alter` with:
+
+- `Error: stepping, failed compacting tables post alteration`
+- `Error: sqlite3_close() returns 5: unable to close due to unfinalized statements or unfinished backups`
+
+Meanwhile, `sqlite-cr` (nix wrapper) succeeds.
+
+This task makes oracle tests reproducible and stable by either:
+- fixing the local build artifact so it behaves like sqlite-cr, OR
+- removing/renaming the misleading artifact and standardizing all oracle tests on sqlite-cr.
+
+## Files to Modify
+- `Makefile` and/or build scripts that produce `lib/crsqlite.dylib` (root or `core/Makefile`)
+- `zig/harness/test-*-parity.sh` scripts (standardize oracle invocation)
+- `README.md` (only if there is user-facing guidance about which dylib is authoritative)
+
+## Acceptance Criteria
+- [x] Oracle test scripts do not depend on a broken local dylib.
+- [x] One of the following is true:
+  - [ ] `lib/crsqlite.dylib` passes a minimal `crsql_begin_alter`/`crsql_commit_alter` smoke test, OR
+  - [x] All oracle parity tests use `sqlite-cr` and document it explicitly.
+- [x] A clear reproduction snippet exists in Completion Notes.
+
+## Progress Log
+### 2025-12-20
+- Repro (fails):
+  - `timeout 30s nix run nixpkgs#sqlite -- /tmp/test.db -cmd ".load lib/crsqlite.dylib" "... crsql_commit_alter ..."`
+- Repro (works):
+  - `timeout 30s nix run github:subtleGradient/sqlite-cr -- /tmp/test.db "... crsql_commit_alter ..."`
+
+### 2025-12-20 (completion)
+- **Decision**: Standardize all oracle parity tests on `sqlite-cr` instead of fixing local dylib
+- **Rationale**: sqlite-cr is the authoritative, known-working oracle; local dylib has undiagnosed issues
+- **Files modified**:
+  - `zig/harness/test-oracle-parity.sh` - switched from local dylib to sqlite-cr
+  - `zig/harness/test-fract-parity.sh` - switched from local dylib to sqlite-cr  
+  - `zig/harness/test-rows-impacted-parity.sh` - switched from local dylib to sqlite-cr
+  - `zig/harness/test-db-version-parity.sh` - switched from local dylib to sqlite-cr
+  - `zig/harness/test-trigger-parity.sh` - switched from local dylib to sqlite-cr
+  - `zig/harness/test-alter-parity.sh` - already using sqlite-cr (no changes needed)
+
+## Completion Notes
+
+### Root Cause
+The local `lib/crsqlite.dylib` has an issue with the ALTER workflow where `crsql_commit_alter` fails with "stepping, failed compacting tables post alteration" and leaves unfinalized statements. The exact cause is unclear but may be related to a version mismatch or build configuration issue.
+
+### Solution Chosen
+**Standardize on sqlite-cr** - All oracle parity tests now use `nix run github:subtleGradient/sqlite-cr` as the Rust/C oracle instead of local dylib files. This approach:
+1. Ensures reproducible tests across environments
+2. Uses a known-working, well-maintained oracle
+3. Documents the sqlite-cr dependency explicitly in each script
+
+### Reproduction Snippets
+
+**Local dylib (FAILS)**:
+```bash
+rm -f /tmp/test.db && timeout 30s nix run nixpkgs#sqlite -- /tmp/test.db -cmd ".load lib/crsqlite.dylib" "
+SELECT crsql_begin_alter('test');
+CREATE TABLE test(id PRIMARY KEY);
+SELECT crsql_commit_alter('test');
+"
+# Output:
+# Error: stepping, failed compacting tables post alteration
+# Error: sqlite3_close() returns 5: unable to close due to unfinalized statements or unfinished backups
+```
+
+**sqlite-cr (SUCCEEDS)**:
+```bash
+rm -f /tmp/test.db && timeout 30s nix run github:subtleGradient/sqlite-cr -- /tmp/test.db "
+SELECT crsql_begin_alter('test');
+CREATE TABLE test(id PRIMARY KEY);
+SELECT crsql_commit_alter('test');
+"
+# Output: OK
+```
+
+### Scripts Updated
+All parity test scripts now document the sqlite-cr usage with this comment:
+```bash
+# Use sqlite-cr for Rust/C oracle (nix wrapper with cr-sqlite preloaded)
+# NOTE: We use sqlite-cr instead of local dylib because the local dylib
+# has known issues with crsql_commit_alter. sqlite-cr is the authoritative oracle.
+# See: .tasks/active/TASK-102-fix-oracle-crsqlite-dylib-alter.md
+```
+
+### Test Commands
+```bash
+# Verify all scripts have valid syntax:
+bash -n zig/harness/test-*-parity.sh
+
+# Run individual parity tests (requires Zig extension built):
+./zig/harness/test-alter-parity.sh
+./zig/harness/test-oracle-parity.sh
+./zig/harness/test-fract-parity.sh
+./zig/harness/test-trigger-parity.sh
+./zig/harness/test-db-version-parity.sh
+./zig/harness/test-rows-impacted-parity.sh
+```