jettypod 4.1.2 → 4.1.4

package/docs/DECISIONS.md

@@ -4,18 +4,6 @@ This document records key decisions made during project discovery and epic plann
 
 ---
 
-## Project-Level Decisions
-
-### UX Approach & Tech Stack
-
-**Decision:** prototypes/test
-
-**Rationale:** Testing
-
-**Date:** 10/30/2025
-
----
-
 ## Epic-Level Decisions
 
 ### Epic #237: Real-time Collaboration
@@ -66,3 +54,13 @@ This document records key decisions made during project discovery and epic plann
 
 ---
 
+### Epic #1840: Multiple AI Coding Assistant Instances
+
+**Concurrent Merge Architecture:** Database-backed merge queue with rebase-first strategy and smart conflict resolution
+
+*Rationale:* Multiple Claude Code instances need coordinated access to main branch. Using database as coordination point provides simple, reliable serialization without complex distributed locking. Rebase-first strategy ensures linear history and makes conflicts easier to reason about. Smart conflict resolution (auto-resolve trivial, LLM-assist complex) enables autonomous operation while escalating truly ambiguous cases. Graceful degradation ensures system never enters unrecoverable state.
+
+*Date:* 11/14/2025
+
+---
+

package/docs/NODE_VERSION.md

@@ -0,0 +1,83 @@
+# Node.js Version Requirements
+
+## Required Version: Node.js 22.x
+
+This project requires **Node.js 22.x** due to a compatibility issue with the `sqlite3` npm package and Node.js v24.
+
+## The Issue
+
+When running tests with Node.js v24, you'll encounter a FATAL ERROR during Node's cleanup phase:
+
+```
+FATAL ERROR: Error::ThrowAsJavaScriptException napi_throw
+----- Native stack trace -----
+ 1: node::OnFatalError(char const*, char const*)
+ 2: napi_fatal_error
+ 3: Napi::Error::Fatal(char const*, char const*)
+ 4: Napi::Error::ThrowAsJavaScriptException() const
+ 5: node_sqlite3::Statement::CleanQueue()
+ 6: node_sqlite3::Statement::~Statement()
+```
+
+This crash occurs AFTER all tests complete and results are reported. It happens during Node's garbage collection when Statement objects are being finalized.
+
+## Root Cause
+
+Node.js v24 removed several deprecated V8 APIs that sqlite3 v5.1.7 relies on:
+- `v8::CopyablePersistentTraits` (replaced with `NonCopyablePersistentTraits`)
+- `v8::AccessorGetterCallback` (replaced with `v8::AccessorNameGetterCallback`)
+- Changes to `v8::String::Utf8Value` and `v8::Object::Get` signatures
+
+## Why Node 22 Instead of Node 24?
+
+While Node.js v24 includes a built-in `node:sqlite` module that eliminates the need for the `sqlite3` npm package, migrating to it would require:
+1. Significant refactoring of all database code
+2. Rewriting all tests that use sqlite3
+3. Changing the API from callback-based to the new native API
+
+Using Node.js 22 LTS (the current stable LTS version) is the pragmatic solution that:
+- Avoids the sqlite3/Node v24 incompatibility
+- Requires no code changes
+- Provides a stable, well-tested Node.js version
+- Will be supported until April 2027
+
+## Setup
+
+### Using nvm (recommended)
+
+```bash
+# Install the required version
+nvm install
+
+# Use the required version
+nvm use
+```
+
+### Manual Installation
+
+Install Node.js 22.x from [nodejs.org](https://nodejs.org/) or using your package manager:
+
+```bash
+# macOS (Homebrew)
+brew install node@22
+
+# Ubuntu/Debian
+curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
+sudo apt-get install -y nodejs
+```
+
+## Future Migration
+
+When ready to migrate to Node.js v24+, consider switching from `sqlite3` npm package to the built-in `node:sqlite` module:
+
+```javascript
+// Old (sqlite3 npm package)
+const sqlite3 = require('sqlite3');
+const db = new sqlite3.Database(':memory:');
+
+// New (Node.js v24+ built-in)
+const { DatabaseSync } = require('node:sqlite');
+const db = new DatabaseSync(':memory:');
+```
+
+See [Node.js v24 sqlite documentation](https://nodejs.org/api/sqlite.html) for details.