git-sqlite-vfs 0.0.0

package/README.md

@@ -0,0 +1,56 @@
+# git-sqlite-vfs
+
+A Git-Versioned SQLite Database via a Custom Virtual File System (VFS).
+
+This project bridges the mathematical robustness of SQLite's B-Tree engine with the distributed version control capabilities of Git, neutralizing the fundamental friction between binary databases and text-based source control.
+
+## The Architecture
+
+By default, standard monolithic SQLite databases undergo "cascading byte shifts" during standard operations (e.g., page splits, rebalancing). This destroys Git's ability to efficiently delta-compress the binary, causing massive repository bloat.
+
+**The GitVFS Sharding Engine:**
+We solve this by replacing the POSIX I/O layer with a custom SQLite Virtual File System (VFS) written in C. Instead of writing to a single `.db` file, `gitvfs` dynamically shards the database into isolated, deterministic 4KB hexadecimal `.bin` pages (e.g., `.db/pages/0A/1B/0A1B2C.bin`). 
+
+Because changes are mathematically isolated to specific physical files, Git's `xdelta` sliding window algorithm achieves near-perfect binary compression. Operations like `VACUUM` naturally trigger `xTruncate`, unlinking dead pages and shrinking the physical directory footprint.
+
+## The Custom Merge Strategy
+
+Standard Git auto-merges (`ort`) operate on a file-by-file basis. Merging isolated binary pages from divergent branches silently corrupts the mathematical integrity of a B-Tree graph.
+
+This package provides a **Native Git Merge Strategy** (`git-merge-sqlitevfs`) that elevates the merge context from the file level to the database level. When Git encounters a branch merge, it delegates the entire operation to our C executable:
+1. `git-merge-sqlitevfs` uses `git archive` to safely reconstruct `MERGE_HEAD` and the Ancestor database states without index-lock collisions.
+2. It uses `ATTACH DATABASE` to instantly mount all three branches (Local, Remote, Ancestor) into a single unified SQLite VDBE engine.
+3. Using the `EXCEPT` operator, it calculates full-row tuples and structural DDL schema diffs instantly.
+4. It performs a true mathematically sound 3-Way Logical Merge—resolving schema evolutions, propagating insertions/deletions, and mitigating exact row-level conflicts (preferring `HEAD`)—then stages the physically reconciled `.bin` pages back to Git.
+
+## Usage
+
+Install the package via npm (requires `better-sqlite3` and `make`):
+
+```bash
+npm install git-sqlite-vfs
+```
+
+Initialize your version-controlled connection in Node.js:
+
+```javascript
+const GitSQLite = require('git-sqlite-vfs');
+
+// Configure Git optimizations and register the VFS merge driver
+GitSQLite.setupGit();
+
+// Open a connection. Our Node wrapper automatically loads the C extension 
+// and routes the URI query via better-sqlite3.
+const db = GitSQLite.open('.db');
+
+// Execute standard SQL natively
+db.exec("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT);");
+db.exec("INSERT INTO users (name) VALUES ('Alice');");
+
+const row = db.prepare("SELECT * FROM users WHERE name = ?").get('Alice');
+console.log(row.name); // 'Alice'
+
+db.close();
+```
+
+Because the underlying files are flawlessly tracked, you can seamlessly branch, commit, and `git reset --hard HEAD~1` to time travel instantly!

package/c/Makefile

@@ -0,0 +1,30 @@
+CC = gcc
+CFLAGS = -Wall -Wextra -g -O2 -std=c99 -D_POSIX_C_SOURCE=200809L
+LDFLAGS = -lsqlite3
+
+SRC_DIR = .
+OUT_DIR = output
+
+all: $(OUT_DIR)/gitvfs_test $(OUT_DIR)/git-merge-sqlitevfs $(OUT_DIR)/gitvfs.so
+
+$(OUT_DIR)/gitvfs.so: $(SRC_DIR)/gitvfs.c $(SRC_DIR)/gitvfs.h | $(OUT_DIR)
+	$(CC) $(CFLAGS) -fPIC -shared -DCOMPILE_SQLITE_EXTENSION $(SRC_DIR)/gitvfs.c -o $(OUT_DIR)/gitvfs.so $(LDFLAGS)
+
+$(OUT_DIR)/gitvfs.o: $(SRC_DIR)/gitvfs.c $(SRC_DIR)/gitvfs.h | $(OUT_DIR)
+	$(CC) $(CFLAGS) -c $(SRC_DIR)/gitvfs.c -o $(OUT_DIR)/gitvfs.o
+
+$(OUT_DIR)/main.o: $(SRC_DIR)/main.c $(SRC_DIR)/gitvfs.h | $(OUT_DIR)
+	$(CC) $(CFLAGS) -c $(SRC_DIR)/main.c -o $(OUT_DIR)/main.o
+
+$(OUT_DIR)/gitvfs_test: $(OUT_DIR)/main.o $(OUT_DIR)/gitvfs.o | $(OUT_DIR)
+	$(CC) $(CFLAGS) $(OUT_DIR)/main.o $(OUT_DIR)/gitvfs.o -o $(OUT_DIR)/gitvfs_test $(LDFLAGS)
+
+$(OUT_DIR)/git-merge-sqlitevfs: $(SRC_DIR)/git-merge-sqlitevfs.c $(OUT_DIR)/gitvfs.o | $(OUT_DIR)
+	$(CC) $(CFLAGS) $(SRC_DIR)/git-merge-sqlitevfs.c $(OUT_DIR)/gitvfs.o -o $(OUT_DIR)/git-merge-sqlitevfs $(LDFLAGS)
+
+$(OUT_DIR):
+	mkdir -p $(OUT_DIR)
+
+clean:
+	rm -rf $(OUT_DIR)
+	rm -rf .db .git

package/c/git-merge-sqlitevfs.c

@@ -0,0 +1,230 @@
+#include <stdio.h>
+#include <stdlib.h>
+#include <unistd.h>
+#include <string.h>
+#include <sqlite3.h>
+#include "gitvfs.h"
+
+int main(int argc, char *argv[]) {
+    // A Git Strategy receives: <base> -- <head> <remote>
+    if (argc < 5) {
+        fprintf(stderr, "Usage: %s <base> -- <head> <remote>\n", argv[0]);
+        return 1;
+    }
+
+    const char *base = argv[1];
+    const char *other = argv[4];
+
+    printf("VFS Merge Driver Invoked: Whole-DB Logical Merge Initiated...\n");
+
+    // 2. Extract MERGE_HEAD and Ancestor without triggering index-lock failures
+    system("rm -rf /tmp/gitvfs_other_db && mkdir -p /tmp/gitvfs_other_db");
+    
+    char cmd_other[512];
+    snprintf(cmd_other, sizeof(cmd_other), "git archive %s .db/pages/ | tar -x -C /tmp/gitvfs_other_db", other);
+    int ret_other = system(cmd_other);
+    if (ret_other != 0) {
+        fprintf(stderr, "Failed to extract other database. Command: %s\n", cmd_other);
+    }
+
+    system("rm -rf /tmp/gitvfs_ancestor_db && mkdir -p /tmp/gitvfs_ancestor_db");
+    char cmd_ancestor[512];
+    snprintf(cmd_ancestor, sizeof(cmd_ancestor), "git archive %s .db/pages/ | tar -x -C /tmp/gitvfs_ancestor_db", base);
+    int ret_ancestor = system(cmd_ancestor);
+    if (ret_ancestor != 0) {
+        fprintf(stderr, "Failed to extract ancestor database. Command: %s\n", cmd_ancestor);
+    }
+
+    // 3. The Logical Merge via ATTACH
+    sqlite3 *db_local;
+
+    sqlite3_gitvfs_init_impl(NULL);
+    sqlite3_open_v2(".db", &db_local, SQLITE_OPEN_READWRITE, "gitvfs");
+
+    sqlite3_exec(db_local, "ATTACH DATABASE '/tmp/gitvfs_other_db/.db' AS other;", NULL, 0, NULL);
+    sqlite3_exec(db_local, "ATTACH DATABASE '/tmp/gitvfs_ancestor_db/.db' AS ancestor;", NULL, 0, NULL);
+
+    // 3-Way DDL Merge
+    // Phase 1 (Propagate Drops)
+    sqlite3_exec(db_local, "CREATE TEMP TABLE drops AS SELECT type, name FROM main.sqlite_schema WHERE name IN (SELECT name FROM ancestor.sqlite_schema EXCEPT SELECT name FROM other.sqlite_schema) AND name NOT LIKE 'sqlite_%';", NULL, 0, NULL);
+    
+    sqlite3_stmt *drop_stmt;
+    char *drops_to_execute = calloc(1, 1024 * 1024); // 1MB buffer
+    if (sqlite3_prepare_v2(db_local, "SELECT type, name FROM drops;", -1, &drop_stmt, NULL) == SQLITE_OK) {
+        while (sqlite3_step(drop_stmt) == SQLITE_ROW) {
+            const char *type = (const char *)sqlite3_column_text(drop_stmt, 0);
+            const char *name = (const char *)sqlite3_column_text(drop_stmt, 1);
+            if (type && name) {
+                char drop_sql[512];
+                snprintf(drop_sql, sizeof(drop_sql), "DROP %s IF EXISTS \"%s\";\n", type, name);
+                strcat(drops_to_execute, drop_sql);
+            }
+        }
+        sqlite3_finalize(drop_stmt);
+    }
+    if (strlen(drops_to_execute) > 0) {
+        printf("Propagating Drops:\n%s", drops_to_execute);
+        char *err_msg = NULL;
+        if (sqlite3_exec(db_local, drops_to_execute, NULL, 0, &err_msg) != SQLITE_OK) {
+            fprintf(stderr, "Error executing drop: %s\n", err_msg);
+            sqlite3_free(err_msg);
+        }
+    }
+    free(drops_to_execute);
+    sqlite3_exec(db_local, "DROP TABLE drops;", NULL, 0, NULL);
+
+    // Phase 2 (Propagate Additions)
+    sqlite3_exec(db_local, "CREATE TEMP TABLE adds AS SELECT sql FROM other.sqlite_schema WHERE sql IS NOT NULL AND name IN (SELECT name FROM other.sqlite_schema EXCEPT SELECT name FROM ancestor.sqlite_schema) AND name NOT IN (SELECT name FROM main.sqlite_schema) ORDER BY CASE WHEN type='table' THEN 1 ELSE 2 END;", NULL, 0, NULL);
+    
+    sqlite3_stmt *add_stmt;
+    char *adds_to_execute = calloc(1, 1024 * 1024); // 1MB buffer
+    if (sqlite3_prepare_v2(db_local, "SELECT sql FROM adds;", -1, &add_stmt, NULL) == SQLITE_OK) {
+        while (sqlite3_step(add_stmt) == SQLITE_ROW) {
+            const char *sql = (const char *)sqlite3_column_text(add_stmt, 0);
+            if (sql) {
+                strcat(adds_to_execute, sql);
+                strcat(adds_to_execute, ";\n");
+            }
+        }
+        sqlite3_finalize(add_stmt);
+    }
+    if (strlen(adds_to_execute) > 0) {
+        printf("Propagating Additions:\n%s", adds_to_execute);
+        char *err_msg = NULL;
+        if (sqlite3_exec(db_local, adds_to_execute, NULL, 0, &err_msg) != SQLITE_OK) {
+            fprintf(stderr, "Error executing addition: %s\n", err_msg);
+            sqlite3_free(err_msg);
+        }
+    }
+    free(adds_to_execute);
+    sqlite3_exec(db_local, "DROP TABLE adds;", NULL, 0, NULL);
+
+    // Dynamically discover and merge tables
+    sqlite3_stmt *stmt;
+    const char *query_schema = "SELECT name FROM main.sqlite_schema WHERE type='table' AND name NOT LIKE 'sqlite_%';";
+    
+    if (sqlite3_prepare_v2(db_local, query_schema, -1, &stmt, NULL) == SQLITE_OK) {
+        while (sqlite3_step(stmt) == SQLITE_ROW) {
+            const char *table_name = (const char *)sqlite3_column_text(stmt, 0);
+            if (table_name) {
+                printf("Merging table: %s\n", table_name);
+
+                char pragma_query[512];
+                snprintf(pragma_query, sizeof(pragma_query), "PRAGMA main.table_info(\"%s\");", table_name);
+                sqlite3_stmt *pragma_stmt;
+                char pk_col[256] = {0};
+                int has_pk = 0;
+
+                if (sqlite3_prepare_v2(db_local, pragma_query, -1, &pragma_stmt, NULL) == SQLITE_OK) {
+                    while (sqlite3_step(pragma_stmt) == SQLITE_ROW) {
+                        int pk = sqlite3_column_int(pragma_stmt, 5); 
+                        if (pk > 0) {
+                            const char *col_name = (const char *)sqlite3_column_text(pragma_stmt, 1);
+                            if (col_name) {
+                                strncpy(pk_col, col_name, sizeof(pk_col) - 1);
+                                has_pk = 1;
+                                break; 
+                            }
+                        }
+                    }
+                    sqlite3_finalize(pragma_stmt);
+                } else {
+                    fprintf(stderr, "Failed to prepare PRAGMA query for table %s: %s\n", table_name, sqlite3_errmsg(db_local));
+                }
+
+                if (has_pk) {
+                    int exists_in_ancestor = 0;
+                    char check_anc[256];
+                    snprintf(check_anc, sizeof(check_anc), "SELECT 1 FROM ancestor.sqlite_schema WHERE type='table' AND name='%s';", table_name);
+                    sqlite3_stmt *anc_stmt;
+                    if (sqlite3_prepare_v2(db_local, check_anc, -1, &anc_stmt, NULL) == SQLITE_OK) {
+                        if (sqlite3_step(anc_stmt) == SQLITE_ROW) exists_in_ancestor = 1;
+                        sqlite3_finalize(anc_stmt);
+                    }
+
+                    if (exists_in_ancestor) {
+                        char drop_conflict[256];
+                        snprintf(drop_conflict, sizeof(drop_conflict), "DROP TABLE IF EXISTS temp.\"conflicted_pks_%s\";", table_name);
+                        sqlite3_exec(db_local, drop_conflict, NULL, 0, NULL);
+                        
+                        char conflict_query[1024];
+                        snprintf(conflict_query, sizeof(conflict_query), 
+                            "CREATE TEMP TABLE \"conflicted_pks_%s\" AS "
+                            "SELECT \"%s\" FROM (SELECT * FROM main.\"%s\" EXCEPT SELECT * FROM ancestor.\"%s\") "
+                            "INTERSECT "
+                            "SELECT \"%s\" FROM (SELECT * FROM other.\"%s\" EXCEPT SELECT * FROM ancestor.\"%s\");",
+                            table_name,
+                            pk_col, table_name, table_name,
+                            pk_col, table_name, table_name);
+                        
+                        char *err_msg = NULL;
+                        if (sqlite3_exec(db_local, conflict_query, NULL, 0, &err_msg) != SQLITE_OK) {
+                            fprintf(stderr, "Error executing conflict query: %s\n", err_msg);
+                            sqlite3_free(err_msg);
+                        }
+
+                        // Identify Row-Level Clashes
+                        sqlite3_stmt *conflict_stmt;
+                        char select_conflict[256];
+                        snprintf(select_conflict, sizeof(select_conflict), "SELECT * FROM \"conflicted_pks_%s\";", table_name);
+                        if (sqlite3_prepare_v2(db_local, select_conflict, -1, &conflict_stmt, NULL) == SQLITE_OK) {
+                            while (sqlite3_step(conflict_stmt) == SQLITE_ROW) {
+                                const char *conflicted_pk_val = (const char *)sqlite3_column_text(conflict_stmt, 0);
+                                printf("WARNING: True Row Conflict detected on table '%s', PK '%s'. Preserving HEAD state.\n", table_name, conflicted_pk_val ? conflicted_pk_val : "NULL");
+                            }
+                            sqlite3_finalize(conflict_stmt);
+                        }
+
+                        char q1[1024];
+                        char q2[1024];
+
+                        // Query 1: Propagate Deletions from MERGE_HEAD
+                        snprintf(q1, sizeof(q1), 
+                            "DELETE FROM main.\"%s\" WHERE \"%s\" IN (SELECT \"%s\" FROM ancestor.\"%s\" EXCEPT SELECT \"%s\" FROM other.\"%s\");", 
+                            table_name, pk_col, pk_col, table_name, pk_col, table_name);
+                        if (sqlite3_exec(db_local, q1, NULL, 0, &err_msg) != SQLITE_OK) {
+                            fprintf(stderr, "Error executing deletion merge query: %s\n", err_msg);
+                            sqlite3_free(err_msg);
+                        }
+
+                        // Query 2: Propagate Inserts & Updates from MERGE_HEAD, omitting row conflicts
+                        snprintf(q2, sizeof(q2), 
+                            "REPLACE INTO main.\"%s\" SELECT * FROM other.\"%s\" WHERE \"%s\" IN (SELECT \"%s\" FROM (SELECT * FROM other.\"%s\" EXCEPT SELECT * FROM ancestor.\"%s\")) "
+                            "AND \"%s\" NOT IN (SELECT \"%s\" FROM \"conflicted_pks_%s\");", 
+                            table_name, table_name, pk_col, pk_col, table_name, table_name, pk_col, pk_col, table_name);
+                        if (sqlite3_exec(db_local, q2, NULL, 0, &err_msg) != SQLITE_OK) {
+                            fprintf(stderr, "Error executing insert/update merge query: %s\n", err_msg);
+                            sqlite3_free(err_msg);
+                        }
+                        
+                        sqlite3_exec(db_local, drop_conflict, NULL, 0, NULL);
+                    } else {
+                        // Fallback to naive 2-way append (table is new)
+                        char merge_query[512];
+                        snprintf(merge_query, sizeof(merge_query), 
+                                 "INSERT OR IGNORE INTO main.\"%s\" SELECT * FROM other.\"%s\";", 
+                                 table_name, table_name);
+                        sqlite3_exec(db_local, merge_query, NULL, 0, NULL);
+                    }
+                } else {
+                    char merge_query[512];
+                    snprintf(merge_query, sizeof(merge_query), 
+                             "INSERT OR IGNORE INTO main.\"%s\" SELECT * FROM other.\"%s\";", 
+                             table_name, table_name);
+                    sqlite3_exec(db_local, merge_query, NULL, 0, NULL);
+                }
+            }
+        }
+        sqlite3_finalize(stmt);
+    } else {
+        fprintf(stderr, "Failed to prepare schema query: %s\n", sqlite3_errmsg(db_local));
+    }
+
+    sqlite3_close(db_local);
+
+    if (system("git add -A -f .db/pages/") != 0) {}
+    if (system("rm -rf /tmp/gitvfs_other_db /tmp/gitvfs_ancestor_db") != 0) {}
+
+    printf("Logical Merge Complete! VFS physical pages reconciled.\n");
+    return 0;
+}

package/c/gitvfs.c

@@ -0,0 +1,526 @@
+#include "gitvfs.h"
+#ifdef COMPILE_SQLITE_EXTENSION
+#include <sqlite3ext.h>
+SQLITE_EXTENSION_INIT1
+#else
+#include <sqlite3.h>
+#endif
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/stat.h>
+#include <fcntl.h>
+#include <unistd.h>
+#include <errno.h>
+
+#define GITVFS_PAGE_SIZE 4096
+#define GITVFS_MAX_PATH 512
+
+/* 
+ * Custom sqlite3_file subclass to hold our internal state.
+ * This structure tracks the file descriptor equivalents and the state
+ * of the highest page written for bounds checking.
+ */
+typedef struct gitvfs_file {
+    sqlite3_file base;              /* Base class. Must be first. */
+    char base_dir[GITVFS_MAX_PATH]; /* The base directory for this database (e.g., ".db") */
+    sqlite3_int64 max_page_number;  /* Highest page number written, used for xFileSize */
+    int is_main_db;                 /* 1 if main DB (sharded), 0 if temp/journal (flat) */
+    int flat_fd;                    /* POSIX file descriptor for temp/journal files */
+} gitvfs_file;
+
+/*
+ * Utility: Recursively create directories (mkdir -p behavior)
+ * Helps ensure our nested sharded directory structure exists before writing.
+ */
+static int mkdir_p(const char *path, mode_t mode) {
+    char tmp[GITVFS_MAX_PATH];
+    char *p = NULL;
+    size_t len;
+
+    snprintf(tmp, sizeof(tmp), "%s", path);
+    len = strlen(tmp);
+    if (len > 0 && tmp[len - 1] == '/') {
+        tmp[len - 1] = 0;
+    }
+
+    for (p = tmp + 1; *p; p++) {
+        if (*p == '/') {
+            *p = 0;
+            if (mkdir(tmp, mode) != 0 && errno != EEXIST) {
+                return -1;
+            }
+            *p = '/';
+        }
+    }
+    if (mkdir(tmp, mode) != 0 && errno != EEXIST) {
+        return -1;
+    }
+    return 0;
+}
+
+/*
+ * Utility: Calculate the file path for a specific page number.
+ * 
+ * Sharding logic:
+ * We map a page number to a hex string to create a deterministic path.
+ * 1. Convert page number to a zero-padded, uppercase 6-character hex string.
+ * 2. Extract the first two characters for the 1st level directory.
+ * 3. Extract the next two characters for the 2nd level directory.
+ * 
+ * Example: Page 1048575 -> Hex "0FFFFF"
+ * Path: <base_dir>/pages/0F/FF/0FFFFF.bin
+ */
+static void get_page_filepath(const char *base_dir, sqlite3_int64 page_number, char *path_buffer, size_t buffer_size) {
+    char hex_str[32];
+    
+    // Format page number as a zero-padded, 6-character hexadecimal string
+    snprintf(hex_str, sizeof(hex_str), "%06llX", (unsigned long long)page_number);
+    
+    // Extract sharding prefixes
+    char dir1[3] = { hex_str[0], hex_str[1], '\0' };
+    char dir2[3] = { hex_str[2], hex_str[3], '\0' };
+
+    // Construct the full path
+    snprintf(path_buffer, buffer_size, "%s/pages/%s/%s/%s.bin", base_dir, dir1, dir2, hex_str);
+}
+
+/*
+ * Utility: Generate the .gitattributes file in the pages directory.
+ * Explicitly declares all .bin files as binary to optimize Git delta-compression
+ * and suppress meaningless text-based diff operations.
+ */
+static void generate_gitattributes(const char *base_dir) {
+    char pages_dir[GITVFS_MAX_PATH];
+    snprintf(pages_dir, sizeof(pages_dir), "%s/pages", base_dir);
+    
+    // Ensure the root pages directory exists
+    if (mkdir_p(pages_dir, 0755) != 0) return;
+    
+    char attr_path[GITVFS_MAX_PATH];
+    snprintf(attr_path, sizeof(attr_path), "%s/.gitattributes", pages_dir);
+    
+    // Check if the file already exists to avoid unnecessary disk writes
+    if (access(attr_path, F_OK) != -1) {
+        return; 
+    }
+    
+    // Create the .gitattributes file
+    FILE *f = fopen(attr_path, "w");
+    if (f) {
+        fprintf(f, "*.bin binary\nsize.meta binary\n");
+        fclose(f);
+    }
+}
+
+static void generate_gitignore(const char *base_dir) {
+    char attr_path[GITVFS_MAX_PATH];
+    snprintf(attr_path, sizeof(attr_path), "%s/.gitignore", base_dir);
+    
+    if (access(attr_path, F_OK) != -1) {
+        return; 
+    }
+    
+    FILE *f = fopen(attr_path, "w");
+    if (f) {
+        fprintf(f, "*-journal\n*-wal\n*-shm\n");
+        fclose(f);
+    }
+}
+
+/* =====================================================================
+ * VFS I/O Methods (sqlite3_io_methods)
+ * Part 2 - Core I/O Logic
+ * ===================================================================== */
+
+static int gitvfs_Close(sqlite3_file *pFile) {
+    gitvfs_file *p = (gitvfs_file*)pFile;
+    
+    // If it's a temporary or journal file, close the POSIX file descriptor
+    if (!p->is_main_db && p->flat_fd >= 0) {
+        close(p->flat_fd);
+        p->flat_fd = -1;
+    }
+    return SQLITE_OK;
+}
+
+static int gitvfs_Read(sqlite3_file *pFile, void *zBuf, int iAmt, sqlite3_int64 iOfst) {
+    gitvfs_file *p = (gitvfs_file*)pFile;
+    
+    // Route to monolithic file read for temp/journal files
+    if (!p->is_main_db) {
+        ssize_t n = pread(p->flat_fd, zBuf, iAmt, iOfst);
+        if (n == iAmt) {
+            return SQLITE_OK;
+        } else if (n >= 0) {
+            memset((char*)zBuf + n, 0, iAmt - n);
+            return SQLITE_IOERR_SHORT_READ;
+        }
+        return SQLITE_IOERR_READ;
+    }
+
+    // Sharded DB read logic
+    sqlite3_int64 page_number = iOfst / GITVFS_PAGE_SIZE;
+    sqlite3_int64 local_offset = iOfst % GITVFS_PAGE_SIZE;
+    
+    char path[GITVFS_MAX_PATH];
+    get_page_filepath(p->base_dir, page_number, path, sizeof(path));
+    
+    int fd = open(path, O_RDONLY);
+    if (fd < 0) {
+        // Unwritten page requested: Zero-fill the buffer entirely
+        memset(zBuf, 0, iAmt);
+        return SQLITE_IOERR_SHORT_READ;
+    }
+    
+    // Read exact intra-page payload using pread
+    ssize_t bytes_read = pread(fd, zBuf, iAmt, local_offset);
+    close(fd);
+    
+    if (bytes_read == iAmt) {
+        return SQLITE_OK;
+    } else if (bytes_read >= 0) {
+        // Short read: file exists but has fewer bytes than requested. Zero-fill the remainder.
+        memset((char*)zBuf + bytes_read, 0, iAmt - bytes_read);
+        return SQLITE_IOERR_SHORT_READ;
+    }
+    
+    return SQLITE_IOERR_READ;
+}
+
+static int gitvfs_Write(sqlite3_file *pFile, const void *zBuf, int iAmt, sqlite3_int64 iOfst) {
+    gitvfs_file *p = (gitvfs_file*)pFile;
+    
+    // Route to monolithic file write for temp/journal files
+    if (!p->is_main_db) {
+        ssize_t n = pwrite(p->flat_fd, zBuf, iAmt, iOfst);
+        return (n == iAmt) ? SQLITE_OK : SQLITE_IOERR_WRITE;
+    }
+
+    // Sharded DB write logic
+    sqlite3_int64 page_number = iOfst / GITVFS_PAGE_SIZE;
+    sqlite3_int64 local_offset = iOfst % GITVFS_PAGE_SIZE;
+    
+    char path[GITVFS_MAX_PATH];
+    get_page_filepath(p->base_dir, page_number, path, sizeof(path));
+    
+    // Ensure parent directories exist
+    char dir_path[GITVFS_MAX_PATH];
+    snprintf(dir_path, sizeof(dir_path), "%s", path);
+    char *last_slash = strrchr(dir_path, '/');
+    if (last_slash) {
+        *last_slash = '\0';
+        if (mkdir_p(dir_path, 0755) != 0) {
+            return SQLITE_IOERR_WRITE;
+        }
+    }
+    
+    // CRITICAL: Open with O_RDWR | O_CREAT to modify existing page data without truncating
+    int fd = open(path, O_RDWR | O_CREAT, 0644);
+    if (fd < 0) {
+        return SQLITE_IOERR_WRITE;
+    }
+    
+    // Write exact intra-page payload using pwrite
+    ssize_t bytes_written = pwrite(fd, zBuf, iAmt, local_offset);
+    close(fd);
+    
+    if (bytes_written != iAmt) {
+        return SQLITE_IOERR_WRITE;
+    }
+    
+    // State Persistence: Update max_page_number and size.meta if this is a new high page
+    if (page_number > p->max_page_number) {
+        p->max_page_number = page_number;
+        
+        char meta_path[GITVFS_MAX_PATH];
+        snprintf(meta_path, sizeof(meta_path), "%s/pages/size.meta", p->base_dir);
+        FILE *f = fopen(meta_path, "w");
+        if (f) {
+            fprintf(f, "%lld\n", (long long)p->max_page_number);
+            fclose(f);
+        }
+    }
+    
+    return SQLITE_OK;
+}
+
+static int gitvfs_Truncate(sqlite3_file *pFile, sqlite3_int64 size) {
+    gitvfs_file *p = (gitvfs_file*)pFile;
+    
+    // Route to ftruncate for temp/journal files
+    if (!p->is_main_db) {
+        return (ftruncate(p->flat_fd, size) == 0) ? SQLITE_OK : SQLITE_IOERR_TRUNCATE;
+    }
+
+    // Sharded DB truncate logic
+    sqlite3_int64 new_max_page = (size == 0) ? -1 : (size - 1) / GITVFS_PAGE_SIZE;
+    
+    // Clean up abandoned page files
+    for (sqlite3_int64 i = new_max_page + 1; i <= p->max_page_number; i++) {
+        char path[GITVFS_MAX_PATH];
+        get_page_filepath(p->base_dir, i, path, sizeof(path));
+        unlink(path);
+    }
+    
+    // Update max_page_number and size.meta
+    if (new_max_page != p->max_page_number) {
+        p->max_page_number = new_max_page;
+        
+        char meta_path[GITVFS_MAX_PATH];
+        snprintf(meta_path, sizeof(meta_path), "%s/pages/size.meta", p->base_dir);
+        
+        if (new_max_page == -1) {
+            unlink(meta_path); // DB is completely empty
+        } else {
+            FILE *f = fopen(meta_path, "w");
+            if (f) {
+                fprintf(f, "%lld\n", (long long)p->max_page_number);
+                fclose(f);
+            }
+        }
+    }
+    
+    return SQLITE_OK;
+}
+
+static int gitvfs_Sync(sqlite3_file *pFile, int flags) {
+    // Single-writer MVP relying on standard POSIX disk flushes.
+    // For temp files we could call fsync(p->flat_fd). 
+    // Returning SQLITE_OK satisfies SQLite's expectation.
+    return SQLITE_OK; 
+}
+
+static int gitvfs_FileSize(sqlite3_file *pFile, sqlite3_int64 *pSize) {
+    gitvfs_file *p = (gitvfs_file*)pFile;
+    
+    if (!p->is_main_db) {
+        struct stat st;
+        if (fstat(p->flat_fd, &st) == 0) {
+            *pSize = st.st_size;
+            return SQLITE_OK;
+        }
+        return SQLITE_IOERR_FSTAT;
+    }
+
+    // O(1) state lookup for the sharded DB size
+    *pSize = (p->max_page_number + 1) * GITVFS_PAGE_SIZE;
+    return SQLITE_OK;
+}
+
+static int gitvfs_Lock(sqlite3_file *pFile, int eLock) {
+    return SQLITE_OK; // SQLite requires lock functions to succeed
+}
+
+static int gitvfs_Unlock(sqlite3_file *pFile, int eLock) {
+    (void)pFile; (void)eLock;
+    return SQLITE_OK;
+}
+
+static int gitvfs_CheckReservedLock(sqlite3_file *pFile, int *pResOut) {
+    *pResOut = 0;
+    return SQLITE_OK;
+}
+
+static int gitvfs_FileControl(sqlite3_file *pFile, int op, void *pArg) {
+    return SQLITE_NOTFOUND;
+}
+
+static int gitvfs_SectorSize(sqlite3_file *pFile) {
+    return GITVFS_PAGE_SIZE;
+}
+
+static int gitvfs_DeviceCharacteristics(sqlite3_file *pFile) {
+    return 0; // Standard characteristics
+}
+
+static const sqlite3_io_methods gitvfs_io_methods = {
+    1,                              /* iVersion */
+    gitvfs_Close,                   /* xClose */
+    gitvfs_Read,                    /* xRead */
+    gitvfs_Write,                   /* xWrite */
+    gitvfs_Truncate,                /* xTruncate */
+    gitvfs_Sync,                    /* xSync */
+    gitvfs_FileSize,                /* xFileSize */
+    gitvfs_Lock,                    /* xLock */
+    gitvfs_Unlock,                  /* xUnlock */
+    gitvfs_CheckReservedLock,       /* xCheckReservedLock */
+    gitvfs_FileControl,             /* xFileControl */
+    gitvfs_SectorSize,              /* xSectorSize */
+    gitvfs_DeviceCharacteristics,   /* xDeviceCharacteristics */
+    NULL,                           /* xShmMap */
+    NULL,                           /* xShmLock */
+    NULL,                           /* xShmBarrier */
+    NULL,                           /* xShmUnmap */
+    NULL,                           /* xFetch */
+    NULL                            /* xUnfetch */
+};
+
+/* =====================================================================
+ * VFS Registration Methods (sqlite3_vfs)
+ * ===================================================================== */
+
+static sqlite3_vfs *orig_vfs = NULL;
+
+static int gitvfs_Open(sqlite3_vfs *pVfs, const char *zName, sqlite3_file *pFile, int flags, int *pOutFlags) {
+    if (!orig_vfs) orig_vfs = sqlite3_vfs_find(NULL);
+    if (!zName || strstr(zName, ".db") == NULL) {
+        return orig_vfs->xOpen(orig_vfs, zName, pFile, flags, pOutFlags);
+    }
+    gitvfs_file *p = (gitvfs_file*)pFile;
+    p->base.pMethods = &gitvfs_io_methods;
+    p->max_page_number = -1;
+    p->flat_fd = -1;
+    
+    // Identify if opening the main database or a temporary/journal file
+    if (flags & SQLITE_OPEN_MAIN_DB) {
+        p->is_main_db = 1;
+        
+        const char *base = (zName != NULL) ? zName : ".db";
+        
+        // Strip URI parameters if they exist
+        char clean_base[GITVFS_MAX_PATH];
+        snprintf(clean_base, sizeof(clean_base), "%s", base);
+        char *qmark = strchr(clean_base, '?');
+        if (qmark) {
+            *qmark = '\0';
+        }
+        
+        // Also strip "file:" prefix if Python passes it raw
+        const char *actual_base = clean_base;
+        if (strncmp(actual_base, "file:", 5) == 0) {
+            actual_base += 5;
+        }
+
+        snprintf(p->base_dir, sizeof(p->base_dir), "%s", actual_base);
+        
+        // Initialize standard repository constraints
+        generate_gitattributes(p->base_dir);
+        generate_gitignore(p->base_dir);
+        
+        // State Persistence: Load max_page_number from size.meta
+        char meta_path[GITVFS_MAX_PATH];
+        snprintf(meta_path, sizeof(meta_path), "%s/pages/size.meta", p->base_dir);
+        FILE *f = fopen(meta_path, "r");
+        if (f) {
+            long long max_page;
+            if (fscanf(f, "%lld", &max_page) == 1) {
+                p->max_page_number = (sqlite3_int64)max_page;
+            }
+            fclose(f);
+        }
+    } else {
+        // Handle temp/journal file natively as a monolithic file
+        p->is_main_db = 0;
+        
+        int openFlags = 0;
+        if (flags & SQLITE_OPEN_READONLY)  openFlags |= O_RDONLY;
+        if (flags & SQLITE_OPEN_READWRITE) openFlags |= O_RDWR;
+        if (flags & SQLITE_OPEN_CREATE)    openFlags |= O_CREAT;
+        
+        // Anonymous temp file handling
+        if (zName == NULL) {
+            char temp_name[GITVFS_MAX_PATH];
+            snprintf(temp_name, sizeof(temp_name), "/tmp/gitvfs_temp_%d_%p", getpid(), p);
+            p->flat_fd = open(temp_name, O_RDWR | O_CREAT | O_EXCL, 0644);
+            if (p->flat_fd >= 0) unlink(temp_name); // Clean up immediately on close
+        } else {
+            p->flat_fd = open(zName, openFlags, 0644);
+        }
+        
+        if (p->flat_fd < 0) {
+            return SQLITE_CANTOPEN;
+        }
+    }
+    
+    if (pOutFlags) {
+        *pOutFlags = flags;
+    }
+    
+    return SQLITE_OK;
+}
+
+static int gitvfs_Delete(sqlite3_vfs *pVfs, const char *zName, int syncDir) {
+    // Standard file deletion, primarily used for clearing out old journals
+    unlink(zName);
+    return SQLITE_OK;
+}
+
+static int gitvfs_Access(sqlite3_vfs *pVfs, const char *zName, int flags, int *pResOut) {
+    // Check if the directory or file is accessible
+    *pResOut = (access(zName, F_OK) == 0) ? 1 : 0;
+    return SQLITE_OK;
+}
+
+static int gitvfs_FullPathname(sqlite3_vfs *pVfs, const char *zName, int nOut, char *zOut) {
+    snprintf(zOut, nOut, "%s", zName);
+    return SQLITE_OK;
+}
+
+/* System calls to load extensions (stubbed) */
+static void *gitvfs_DlOpen(sqlite3_vfs *pVfs, const char *zFilename) { return orig_vfs->xDlOpen(orig_vfs, zFilename); }
+static void gitvfs_DlError(sqlite3_vfs *pVfs, int nByte, char *zErrMsg) { orig_vfs->xDlError(orig_vfs, nByte, zErrMsg); }
+static void (*gitvfs_DlSym(sqlite3_vfs *pVfs, void *p, const char*zSymbol))(void) { return orig_vfs->xDlSym(orig_vfs, p, zSymbol); }
+static void gitvfs_DlClose(sqlite3_vfs *pVfs, void *pHandle) { orig_vfs->xDlClose(orig_vfs, pHandle); }
+static int gitvfs_Randomness(sqlite3_vfs *pVfs, int nByte, char *zOut) { return orig_vfs->xRandomness(orig_vfs, nByte, zOut); }
+static int gitvfs_Sleep(sqlite3_vfs *pVfs, int microseconds) { return orig_vfs->xSleep(orig_vfs, microseconds); }
+static int gitvfs_CurrentTime(sqlite3_vfs *pVfs, double *prNow) { return orig_vfs->xCurrentTime(orig_vfs, prNow); }
+
+static int gitvfs_GetLastError(sqlite3_vfs *pVfs, int a, char *b) { return orig_vfs->xGetLastError ? orig_vfs->xGetLastError(orig_vfs, a, b) : 0; }
+static int gitvfs_CurrentTimeInt64(sqlite3_vfs *pVfs, sqlite3_int64 *p) { return orig_vfs->xCurrentTimeInt64 ? orig_vfs->xCurrentTimeInt64(orig_vfs, p) : 0; }
+static int gitvfs_SetSystemCall(sqlite3_vfs *pVfs, const char *zName, sqlite3_syscall_ptr pNew) { return orig_vfs->xSetSystemCall ? orig_vfs->xSetSystemCall(orig_vfs, zName, pNew) : SQLITE_ERROR; }
+static sqlite3_syscall_ptr gitvfs_GetSystemCall(sqlite3_vfs *pVfs, const char *zName) { return orig_vfs->xGetSystemCall ? orig_vfs->xGetSystemCall(orig_vfs, zName) : NULL; }
+static const char *gitvfs_NextSystemCall(sqlite3_vfs *pVfs, const char *zName) { return orig_vfs->xNextSystemCall ? orig_vfs->xNextSystemCall(orig_vfs, zName) : NULL; }
+
+/*
+ * Entry point to register our Git VFS.
+ */
+int sqlite3_gitvfs_init_impl(const char *base_dir) {
+    (void)base_dir;
+    if (sqlite3_vfs_find("gitvfs") != NULL) {
+        return SQLITE_OK;
+    }
+    
+    if (!orig_vfs) orig_vfs = sqlite3_vfs_find(NULL);
+
+    static sqlite3_vfs git_vfs = {
+        3,                                /* iVersion */
+        0,                                /* szOsFile */
+        GITVFS_MAX_PATH,                  /* mxPathname */
+        NULL,                             /* pNext */
+        "gitvfs",                         /* zName */
+        NULL,                             /* pAppData */
+        gitvfs_Open,                      /* xOpen */
+        gitvfs_Delete,                    /* xDelete */
+        gitvfs_Access,                    /* xAccess */
+        gitvfs_FullPathname,              /* xFullPathname */
+        gitvfs_DlOpen,                    /* xDlOpen */
+        gitvfs_DlError,                   /* xDlError */
+        gitvfs_DlSym,                     /* xDlSym */
+        gitvfs_DlClose,                   /* xDlClose */
+        gitvfs_Randomness,                /* xRandomness */
+        gitvfs_Sleep,                     /* xSleep */
+        gitvfs_CurrentTime,               /* xCurrentTime */
+        gitvfs_GetLastError,              /* xGetLastError */
+        gitvfs_CurrentTimeInt64,          /* xCurrentTimeInt64 */
+        gitvfs_SetSystemCall,             /* xSetSystemCall */
+        gitvfs_GetSystemCall,             /* xGetSystemCall */
+        gitvfs_NextSystemCall             /* xNextSystemCall */
+    };
+
+    git_vfs.szOsFile = sizeof(gitvfs_file) > (size_t)orig_vfs->szOsFile ? (int)sizeof(gitvfs_file) : orig_vfs->szOsFile;
+    return sqlite3_vfs_register(&git_vfs, 1);
+}
+
+#ifdef COMPILE_SQLITE_EXTENSION
+#ifdef _WIN32
+__declspec(dllexport)
+#endif
+int sqlite3_gitvfs_init(sqlite3 *db, char **pzErrMsg, const sqlite3_api_routines *pApi) {
+    (void)db; (void)pzErrMsg;
+    SQLITE_EXTENSION_INIT2(pApi);
+    int rc = sqlite3_gitvfs_init_impl(".db");
+    return (rc == SQLITE_OK) ? SQLITE_OK_LOAD_PERMANENTLY : rc;
+}
+#endif
+

package/c/gitvfs.h

@@ -0,0 +1,15 @@
+#ifndef GITVFS_H
+#define GITVFS_H
+
+#include <sqlite3.h>
+
+/**
+ * Initializes and registers the Git VFS with SQLite.
+ *
+ * @param base_dir Optional. The base directory for the database. 
+ *                 Can be passed in context or managed per connection.
+ * @return SQLITE_OK on success, or an SQLite error code.
+ */
+int sqlite3_gitvfs_init_impl(const char *base_dir);
+
+#endif // GITVFS_H

package/c/main.c

@@ -0,0 +1,111 @@
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sqlite3.h>
+#include "gitvfs.h"
+
+// Callback to print SELECT results
+static int select_callback(void *NotUsed, int argc, char **argv, char **azColName) {
+    (void)NotUsed;
+    for (int i = 0; i < argc; i++) {
+        printf("%s = %s  ", azColName[i], argv[i] ? argv[i] : "NULL");
+    }
+    printf("\n");
+    return 0;
+}
+
+int main(int argc, char *argv[]) {
+    sqlite3 *db;
+    char *err_msg = 0;
+    int rc;
+
+    if (argc < 2) {
+        fprintf(stderr, "Usage: %s [init | <sql_statement>]\n", argv[0]);
+        return 1;
+    }
+
+    // 1. Initialize our custom Git VFS
+    // We pass ".db" as our base directory. This will map to .db/pages/...
+    rc = sqlite3_gitvfs_init_impl(".db");
+    if (rc != SQLITE_OK) {
+        fprintf(stderr, "Failed to initialize gitvfs: %d\n", rc);
+        return 1;
+    }
+
+    // 2. Open the database using our custom VFS
+    // Note the "gitvfs" parameter at the end
+    rc = sqlite3_open_v2(".db", &db, SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE, "gitvfs");
+    if (rc != SQLITE_OK) {
+        fprintf(stderr, "Cannot open database: %s\n", sqlite3_errmsg(db));
+        sqlite3_close(db);
+        return 1;
+    }
+
+    // 3. Set page size to 4096 to match our VFS assumptions
+    rc = sqlite3_exec(db, "PRAGMA page_size = 4096;", 0, 0, &err_msg);
+    if (rc != SQLITE_OK) {
+        fprintf(stderr, "PRAGMA error: %s\n", err_msg);
+        sqlite3_free(err_msg);
+    }
+
+    if (strcmp(argv[1], "init") == 0) {
+        // 4. Create test tables
+        const char *sql_create = "CREATE TABLE IF NOT EXISTS test_data (id INTEGER PRIMARY KEY, name TEXT, value BLOB);";
+        rc = sqlite3_exec(db, sql_create, 0, 0, &err_msg);
+        if (rc != SQLITE_OK) {
+            fprintf(stderr, "SQL error (CREATE test_data): %s\n", err_msg);
+            sqlite3_free(err_msg);
+        } else {
+            printf("Table 'test_data' ensured.\n");
+        }
+        
+        const char *sql_create_settings = "CREATE TABLE IF NOT EXISTS test_settings (config_key TEXT PRIMARY KEY, config_val TEXT);";
+        rc = sqlite3_exec(db, sql_create_settings, 0, 0, &err_msg);
+        if (rc != SQLITE_OK) {
+            fprintf(stderr, "SQL error (CREATE test_settings): %s\n", err_msg);
+            sqlite3_free(err_msg);
+        } else {
+            printf("Table 'test_settings' ensured.\n");
+        }
+
+        // 5. Insert test data
+        sqlite3_exec(db, "BEGIN TRANSACTION;", 0, 0, &err_msg);
+        const char *sql_insert = "INSERT INTO test_data (name, value) VALUES ('Hello GitVFS', randomblob(100));";
+        
+        // Let's insert a few rows to force some data across pages eventually
+        for (int i = 0; i < 10000; i++) {
+            rc = sqlite3_exec(db, sql_insert, 0, 0, &err_msg);
+            if (rc != SQLITE_OK) {
+                fprintf(stderr, "SQL error (INSERT test_data): %s\n", err_msg);
+                sqlite3_free(err_msg);
+                break;
+            }
+        }
+        sqlite3_exec(db, "COMMIT;", 0, 0, &err_msg);
+        printf("Inserted 10000 rows of test_data.\n");
+        
+        const char *sql_insert_settings = "INSERT INTO test_settings (config_key, config_val) VALUES ('theme', 'dark');";
+        rc = sqlite3_exec(db, sql_insert_settings, 0, 0, &err_msg);
+        if (rc != SQLITE_OK) {
+            fprintf(stderr, "SQL error (INSERT test_settings): %s\n", err_msg);
+            sqlite3_free(err_msg);
+        } else {
+            printf("Inserted baseline row into test_settings.\n");
+        }
+    } else {
+        // Execute the provided SQL
+        // Include the select_callback to print output for queries
+        rc = sqlite3_exec(db, argv[1], select_callback, 0, &err_msg);
+        if (rc != SQLITE_OK) {
+            fprintf(stderr, "SQL error: %s\n", err_msg);
+            sqlite3_free(err_msg);
+        } else {
+            printf("Executed SQL: %s\n", argv[1]);
+        }
+    }
+
+    // 6. Close the connection
+    sqlite3_close(db);
+
+    return 0;
+}

package/index.js

@@ -0,0 +1,55 @@
+const Database = require('better-sqlite3');
+const { execSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+class GitSQLite {
+    /**
+     * Opens a SQLite database utilizing the custom Git Virtual File System (VFS).
+     * By sharding the SQLite B-Tree into 4KB binary pages, it neutralizes cascading
+     * byte shifts, allowing native Git xdelta to achieve near-perfect compression.
+     * 
+     * @param {string} dbPath - The path to the sharded database directory (e.g., '.db')
+     * @returns {Database} - A native better-sqlite3 database connection
+     */
+    static open(dbPath) {
+        // 1. Open a temporary in-memory database to act as an extension loader
+        // better-sqlite3 requires an active connection to load an extension.
+        const tempDb = new Database(':memory:');
+        
+        // 2. Enable extensions and load our compiled C VFS extension (.so)
+        tempDb.loadExtension(path.resolve(__dirname, '../c/output/gitvfs'));
+        
+        // 3. Close tempDb. The SQLite runtime inside the Node process 
+        // will permanently retain the global 'gitvfs' registration!
+        tempDb.close();
+
+        // 4. Instantiate and return the actual database connection.
+        // Because our compiled extension registers itself as the default VFS, 
+        // better-sqlite3 will automatically route all physical I/O for this DB
+        // through our Git-sharded C engine!
+        return new Database(dbPath);
+    }
+
+    /**
+     * Configures the local Git repository with optimized binary thresholds 
+     * and strictly wires up our custom C engine as a Git Merge Strategy.
+     */
+    static setupGit() {
+        try {
+            // Optimize Git for 4KB binary pages to guarantee xdelta works nicely
+            // without prematurely terminating delta compression loops
+            execSync('git config core.bigFileThreshold 10m', { stdio: 'ignore' });
+            
+            // Wire up the custom merge strategy driver with absolute paths
+            // This natively binds our C executable to Git's conflict resolution pipeline
+            const driverPath = path.resolve(__dirname, 'c/output/git-merge-sqlitevfs');
+            execSync(`git config merge.sqlite_logical.name "SQLite Logical Merge Driver"`, { stdio: 'ignore' });
+            execSync(`git config merge.sqlite_logical.driver "${driverPath} %O %A %B %P"`, { stdio: 'ignore' });
+        } catch (err) {
+            console.warn("Warning: Could not configure git attributes automatically.", err.message);
+        }
+    }
+}
+
+module.exports = GitSQLite;

package/install.js

@@ -0,0 +1,53 @@
+const os = require('os');
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+const pkg = require('./package.json');
+
+const REPO = 'fur-tea-laser/git-sqlite-vfs'; 
+const VERSION = `v${pkg.version}`;
+const PLATFORM = os.platform();
+const ARCH = os.arch();
+
+// Target filename from GitHub Release: e.g., git-sqlite-vfs-v1.0.0-linux-x64.tar.gz
+const ASSET_NAME = `git-sqlite-vfs-${VERSION}-${PLATFORM}-${ARCH}.tar.gz`;
+const DOWNLOAD_URL = `https://github.com/${REPO}/releases/download/${VERSION}/${ASSET_NAME}`;
+
+const OUT_DIR = path.join(__dirname, 'c', 'output');
+
+function buildFromSource() {
+    console.log('Building from source as fallback...');
+    try {
+        execSync('npm run build', { stdio: 'inherit', cwd: __dirname });
+        console.log('Successfully built from source.');
+    } catch (e) {
+        console.error('Failed to build from source.', e.message);
+        process.exit(1);
+    }
+}
+
+function downloadAndExtract() {
+    // If the SKIP_DOWNLOAD env var is set, or if we are building locally from the repo root
+    // we should just build from source.
+    if (process.env.SKIP_DOWNLOAD || !fs.existsSync(path.join(__dirname, 'node_modules'))) {
+        return buildFromSource();
+    }
+
+    console.log(`Attempting to download prebuilt binary: ${DOWNLOAD_URL}`);
+    
+    try {
+        if (!fs.existsSync(OUT_DIR)) {
+            fs.mkdirSync(OUT_DIR, { recursive: true });
+        }
+        
+        // Use native curl and tar to download and extract without requiring NPM dependencies.
+        // This is supported out-of-the-box on modern Linux, macOS, and Windows 10+
+        execSync(`curl -sLf ${DOWNLOAD_URL} | tar -xz -C "${OUT_DIR}"`, { stdio: 'inherit' });
+        console.log('Prebuilt binary successfully downloaded and extracted!');
+    } catch (err) {
+        console.log('Prebuilt binary not found or download failed. Falling back to source compilation...');
+        buildFromSource();
+    }
+}
+
+downloadAndExtract();

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "git-sqlite-vfs",
+  "version": "0.0.0",
+  "description": "A Git-Versioned SQLite Database via a Custom Virtual File System (VFS)",
+  "main": "index.js",
+  "scripts": {
+    "build": "cd c && make",
+    "postinstall": "node install.js",
+    "pretest": "npm run build && rm -rf .db .git && git init --initial-branch=master",
+    "test": "node --test test.js"
+  },
+  "dependencies": {
+    "better-sqlite3": "^9.4.3"
+  },
+  "author": "",
+  "license": "ISC"
+}

package/test.js

@@ -0,0 +1,209 @@
+const { describe, it, before } = require('node:test');
+const assert = require('node:assert');
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const GitSQLite = require('./index.js');
+
+// Helper to run git commands synchronously
+const runGit = (cmd) => execSync(cmd, { stdio: 'pipe' }).toString().trim();
+
+// Helper to recursively calculate total directory size
+const getDirSize = (dirPath) => {
+    let total = 0;
+    if (!fs.existsSync(dirPath)) return 0;
+    
+    const files = fs.readdirSync(dirPath, { withFileTypes: true });
+    for (const file of files) {
+        const fullPath = path.join(dirPath, file.name);
+        if (file.isDirectory()) {
+            total += getDirSize(fullPath);
+        } else {
+            total += fs.statSync(fullPath).size;
+        }
+    }
+    return total;
+};
+
+describe('GitSQLite Architecture Validation', () => {
+    let db;
+
+    before(() => {
+        // Initialize Git repo optimizations and register driver configurations
+        GitSQLite.setupGit();
+    });
+
+    it('Test 1: Initialization & VFS Sharding', () => {
+        db = GitSQLite.open('.db');
+
+        // Create initial schema
+        db.exec(`
+            CREATE TABLE test_data (id INTEGER PRIMARY KEY, name TEXT, value BLOB);
+            CREATE TABLE test_settings (config_key TEXT PRIMARY KEY, config_val TEXT);
+        `);
+
+        // Insert initial baseline data using parameterized transactions
+        const insertData = db.prepare("INSERT INTO test_data (name, value) VALUES (?, randomblob(100))");
+        const insertSettings = db.prepare("INSERT INTO test_settings (config_key, config_val) VALUES (?, ?)");
+
+        db.exec('BEGIN TRANSACTION;');
+        for (let i = 1; i <= 50; i++) {
+            insertData.run(`Initial ${i}`);
+        }
+        insertSettings.run('theme', 'dark');
+        db.exec('COMMIT;');
+
+        // Close to flush SQLite connections (VFS sync)
+        db.close(); 
+
+        // Assert our C VFS dynamically intercepted physical I/O and sharded the B-Tree!
+        assert.ok(fs.existsSync('.db/pages'), 'Pages directory should exist');
+        assert.ok(fs.existsSync('.db/pages/size.meta'), 'size.meta persistence state should exist');
+
+        // Verify git tracking structure
+        assert.ok(fs.existsSync('.db/.gitignore'), '.gitignore should be generated');
+        assert.ok(fs.existsSync('.db/pages/.gitattributes'), '.gitattributes should be generated');
+
+        // Stage and Commit Snapshot 1
+        runGit('git add -A -f .db/');
+        runGit('git commit -m "Snapshot 1: Initial DB state"');
+    });
+
+    it('Test 2: VACUUM and Physical B-Tree Shrinkage', () => {
+        db = GitSQLite.open('.db');
+
+        // Insert a massive amount of rows to forcibly expand the B-Tree footprint
+        db.exec('BEGIN TRANSACTION;');
+        const insertData = db.prepare("INSERT INTO test_data (name, value) VALUES ('Bulk', randomblob(100))");
+        for (let i = 0; i < 10000; i++) {
+            insertData.run();
+        }
+        db.exec('COMMIT;');
+        db.close();
+
+        // Capture total file system footprint of the expanded sharded VFS
+        const sizeBefore = getDirSize('.db/pages');
+
+        // Reopen, execute a massive deletion, and trigger a vacuum
+        db = GitSQLite.open('.db');
+        db.exec("DELETE FROM test_data WHERE id > 50;");
+        db.exec("VACUUM;");
+        db.close();
+
+        // Capture total file system footprint post-vacuum
+        const sizeAfter = getDirSize('.db/pages');
+
+        // Assert mathematical shrinkage: our xTruncate implementation successfully unlinked dead pages!
+        assert.ok(sizeAfter < sizeBefore, `Directory size must shrink after VACUUM. Before: ${sizeBefore}, After: ${sizeAfter}`);
+
+        // Stage and Commit Snapshot 2 (Unlinked files must be natively staged as Git deletions)
+        runGit('git add -A -f .db/');
+        runGit('git commit -m "Snapshot 2: Vacuumed database"');
+    });
+
+    it('Test 3: Git Branching & True 3-Way Merge (DDL + Row Conflicts)', () => {
+        // --- CONFLICT BRANCH MUTATIONS ---
+        runGit('git checkout -b conflict_branch');
+        db = GitSQLite.open('.db');
+        db.exec(`
+            INSERT INTO test_data (id, name, value) VALUES (10001, 'conflict_branch', randomblob(100));
+            INSERT INTO test_settings (config_key, config_val) VALUES ('plugin', 'enabled');
+            UPDATE test_data SET name = 'branch_update' WHERE id = 10;
+            DELETE FROM test_data WHERE id = 15;
+            UPDATE test_data SET name = 'branch_wins' WHERE id = 50;
+            CREATE TABLE new_feature (id INTEGER PRIMARY KEY, feature_name TEXT);
+            INSERT INTO new_feature (id, feature_name) VALUES (1, 'version_control');
+            CREATE INDEX idx_test_name ON test_data(name);
+            DROP TABLE test_settings;
+        `);
+        db.close();
+        runGit('git add -A -f .db/');
+        runGit('git commit -m "conflict_branch: Schema evolution and row updates"');
+
+        // --- MASTER BRANCH MUTATIONS ---
+        runGit('git checkout master');
+        db = GitSQLite.open('.db');
+        db.exec(`
+            INSERT INTO test_data (id, name, value) VALUES (10002, 'master', randomblob(100));
+            CREATE TABLE unrelated_table (id INTEGER);
+            UPDATE test_data SET name = 'master_update' WHERE id = 20;
+            UPDATE test_data SET name = 'master_wins' WHERE id = 50;
+        `);
+        db.close();
+        runGit('git add -A -f .db/');
+        runGit('git commit -m "master: Insertions and row updates"');
+
+        // --- THE CUSTOM GIT MERGE STRATEGY ---
+        const binPath = path.resolve(__dirname, 'c/output');
+        try {
+            // By utilizing the -s sqlitevfs strategy and augmenting our PATH, Git natively
+            // delegates the entire branch resolution to our SQLite C engine!
+            execSync(`PATH=$PATH:${binPath} git merge -s sqlitevfs conflict_branch -m "Merge conflict_branch into master"`, { stdio: 'pipe' });
+        } catch (e) {
+            console.error("Merge failed:\n", e.stdout?.toString(), e.stderr?.toString());
+            throw e;
+        }
+
+        // --- ASSERTIONS (Mathematical verification of 3-Way Logical Merge) ---
+        db = GitSQLite.open('.db');
+        
+        // Assert True Row Conflict Resolution (Master Wins)
+        const row50 = db.prepare("SELECT name FROM test_data WHERE id = 50").get();
+        assert.strictEqual(row50.name, 'master_wins', 'Master must win true row-level collisions by Custom Merge Strategy logic');
+
+        // Assert standard branch updates
+        const row10 = db.prepare("SELECT name FROM test_data WHERE id = 10").get();
+        assert.strictEqual(row10.name, 'branch_update');
+
+        const row20 = db.prepare("SELECT name FROM test_data WHERE id = 20").get();
+        assert.strictEqual(row20.name, 'master_update');
+
+        // Assert branch deletions
+        const row15 = db.prepare("SELECT name FROM test_data WHERE id = 15").get();
+        assert.strictEqual(row15, undefined, 'Row 15 must have been deleted by conflict_branch');
+
+        // Assert 3-Way Schema Evolution (DDL Merge)
+        const settingsTable = db.prepare("SELECT count(*) as cnt FROM sqlite_schema WHERE name='test_settings'").get();
+        assert.strictEqual(settingsTable.cnt, 0, 'test_settings table must be mathematically DROPPED');
+
+        const newFeatureRow = db.prepare("SELECT feature_name FROM new_feature WHERE id = 1").get();
+        assert.strictEqual(newFeatureRow.feature_name, 'version_control', 'new_feature table and its row data must exist');
+
+        const idx = db.prepare("SELECT name FROM sqlite_schema WHERE type='index' AND name='idx_test_name'").get();
+        assert.ok(idx, 'idx_test_name index must have been created');
+
+        db.close();
+    });
+
+    it('Test 4: Time Travel (Disaster Recovery via Git)', () => {
+        db = GitSQLite.open('.db');
+        
+        // Assert initial baseline existence
+        let featureTable = db.prepare("SELECT count(*) as cnt FROM sqlite_schema WHERE name='new_feature'").get();
+        assert.strictEqual(featureTable.cnt, 1);
+
+        // Execute a catastrophic, destructive operation
+        db.exec("DROP TABLE new_feature;");
+        featureTable = db.prepare("SELECT count(*) as cnt FROM sqlite_schema WHERE name='new_feature'").get();
+        assert.strictEqual(featureTable.cnt, 0, 'Table must be completely dropped from SQLite');
+        db.close();
+
+        // Commit the disaster
+        runGit('git add -A -f .db/');
+        runGit('git commit -m "Oops, accidentally dropped new_feature"');
+
+        // Initiate Time Travel (Git Reset)
+        // Because the database is perfectly versioned, Git instantly restores the .bin files
+        runGit('git reset --hard HEAD~1');
+
+        // Reopen DB and Verify absolute recovery
+        db = GitSQLite.open('.db');
+        featureTable = db.prepare("SELECT count(*) as cnt FROM sqlite_schema WHERE name='new_feature'").get();
+        assert.strictEqual(featureTable.cnt, 1, 'Table schema must be fully resurrected natively by Git!');
+        
+        const row = db.prepare("SELECT feature_name FROM new_feature WHERE id = 1").get();
+        assert.strictEqual(row.feature_name, 'version_control', 'Physical row data must be fully intact after time travel!');
+
+        db.close();
+    });
+});