feat(sync): sync upstream to Node.js v25.8.1 / SQLite 3.52.0

Add db.limits property for runtime get/set of SQLite limits, with constructor option support. Implement iterator invalidation via generation counter. run/get/all/iterate now throw ERR_INVALID_STATE on previously-active iterators.

Update docs to reflect node:sqlite RC status (Stability 1.2 since v25.7.0): rewrite library-comparison.md, migrating-from-node-sqlite.md, and README to remove "experimental" language and add version matrix.

Update deps: node-addon-api 8.6.0, eslint-plugin-security 4.0, typescript-eslint 8.56.1. Rename sqlite-vec dep to @photostructure scope.

Author: mceachen

.claude/settings.local.json

@@ -68,7 +68,18 @@
       "WebFetch(domain:sqlite.org)",
       "WebFetch(domain:stackoverflow.com)",
       "WebFetch(domain:www.sqlite.org)",
-      "WebFetch(domain:docs.anthropic.com)"
+      "WebFetch(domain:docs.anthropic.com)",
+      "WebFetch(domain:eslint.org)",
+      "Bash(git -C /home/mrm/src/node log v25.6.1..HEAD --oneline -- lib/sqlite.js src/node_sqlite.cc src/node_sqlite.h deps/sqlite)",
+      "Bash(git -C /home/mrm/src/node log -1 --oneline)",
+      "Bash(git -C /home/mrm/src/node describe --tags --abbrev=0)",
+      "Bash(git -C /home/mrm/src/node log v25.6.1..HEAD --oneline -- test/parallel/test-sqlite*)",
+      "Bash(git -C /home/mrm/src/node log v25.6.1..HEAD -p -- lib/sqlite.js src/node_sqlite.cc src/node_sqlite.h)",
+      "Bash(git -C /home/mrm/src/node log v25.6.1..HEAD -p -- test/parallel/test-sqlite*)",
+      "Bash(git -C /home/mrm/src/node log v25.6.1..HEAD -p -- deps/sqlite)",
+      "WebFetch(domain:photostructure.com)",
+      "Bash(git -C /home/mrm/src/node log origin/v25.x-staging --oneline -20 -- src/node_sqlite.cc src/node_sqlite.h)",
+      "Bash(npm pack --dry-run)"
     ],
     "additionalDirectories": [
       "/home/mrm/src/node-addon-examples",

CHANGELOG.md

@@ -2,6 +2,21 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.0.0] (2026-03-07)
+
+Promotion to v1.0.0 following API stabilization and 0.5.0 release.
+
+API compatible with `node:sqlite` from Node.js v25.8.1.
+
+### Added
+
+- **`db.limits` property**: Get and set SQLite limits (length, sqlLength, column, exprDepth, compoundSelect, vdbeOp, functionArg, attach, likePatternLength, variableNumber, triggerDepth) at runtime. Supports `Infinity` to reset to compile-time maximum. Also accepts `limits` option in `DatabaseSync` constructor.
+- **Statement iterator invalidation**: Calling `stmt.run()`, `stmt.get()`, `stmt.all()`, or `stmt.iterate()` now invalidates any active iterator on the same statement, throwing `ERR_INVALID_STATE`
+
+### Changed
+
+- **SQLite 3.52.0**: Updated from 3.51.2
+
 ## [0.5.0] (2026-02-06)
 
 ### Added
@@ -130,6 +145,7 @@ API compatible with `node:sqlite` from Node.js v25.6.1.
 - macOS (x64, ARM64)
 - Linux (x64, ARM64), (glibc 2.28+, musl)
 
+[1.0.0]: https://github.com/PhotoStructure/node-sqlite/releases/tag/v1.0.0
 [0.5.0]: https://github.com/PhotoStructure/node-sqlite/releases/tag/v0.5.0
 [0.4.0]: https://github.com/PhotoStructure/node-sqlite/releases/tag/v0.4.0
 [0.3.0]: https://github.com/PhotoStructure/node-sqlite/releases/tag/v0.3.0

CLAUDE.md

@@ -4,7 +4,9 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-This is @photostructure/sqlite - a standalone npm package that extracts the experimental SQLite implementation from Node.js core. The goal is to make Node.js's native SQLite functionality available to all Node.js versions, not just those with the experimental flag enabled.
+This is @photostructure/sqlite - a standalone npm package that extracts the Node.js SQLite implementation from Node.js core. The goal is to make Node.js's native SQLite functionality available to all Node.js versions (20+), not just those supporting the built-in `node:sqlite` module (22.5.0+).
+
+Note: `node:sqlite` was promoted to Release Candidate (Stability: 1.2) in Node.js v25.7.0. The `--experimental-sqlite` flag was required on 22.5.0–22.12.x; since 22.13.0 it works without a flag (but prints an ExperimentalWarning until v25.7.0).
 
 ### Key Features
 
@@ -240,7 +242,7 @@ This approach reduces test brittleness while ensuring error handling works corre
 
 ### Upstream Synchronization
 
-- Node.js SQLite is experimental and may change frequently
+- Node.js SQLite is Release Candidate (Stability: 1.2) since v25.7.0 — API is stable but minor changes remain possible
 - `sync-from-node.js` script maintains file synchronization
 - Changes should be reviewed for compatibility impact
 - Version tracking needed to correlate with Node.js releases
@@ -294,6 +296,7 @@ This approach reduces test brittleness while ensuring error handling works corre
 - **Run `npm run lint`** to check code quality
 - **Native rebuilds** use `npm run build:native:rebuild`
 - **Multi-platform prebuilds** are generated via GitHub Actions
+- **`package.json` version** is managed by the release GitHub Action — do not bump it manually
 
 ### Git Commit Messages
 

README.md

@@ -5,7 +5,7 @@
 [![npm version](https://img.shields.io/npm/v/@photostructure/sqlite.svg)](https://www.npmjs.com/package/@photostructure/sqlite)
 [![CI](https://github.com/photostructure/node-sqlite/actions/workflows/build.yml/badge.svg)](https://github.com/photostructure/node-sqlite/actions/workflows/build.yml)
 
-Native SQLite for Node.js 20+ without the experimental flag. Drop-in replacement for `node:sqlite`. Synced with Node.js v25.6.2 for the latest features including native `Symbol.dispose` resource management.
+Native SQLite for Node.js 20+. Drop-in replacement for `node:sqlite`. Synced with Node.js v25.8.1 for the latest features including native `Symbol.dispose` resource management.
 
 ## Installation
 
@@ -29,7 +29,7 @@ db.close();
 
 ## Features
 
-- 100% compatible with Node.js v25.6.2 built-in `node:sqlite` module\*
+- 100% compatible with Node.js v25.8.1 built-in `node:sqlite` module\*
 - Zero dependencies - native SQLite implementation
 - Synchronous API - no async overhead
 - Performance comparable to better-sqlite3

doc/done/20260307-P03-upstream-sync-v25.7.md

@@ -0,0 +1,74 @@
+# TPP: Sync upstream Node.js SQLite changes (v25.6.1 → v25.8.1)
+
+## ✅ COMPLETED
+
+## Goal Definition
+
+- **What Success Looks Like**: Two upstream features are ported and all tests pass: (1) statement iterator invalidation, (2) DatabaseSync `limits` property
+- **Core Problem**: The project's native implementation was missing two features from v25.x-staging. SQLTagStore was already implemented in TypeScript
+- **Key Constraints**: API compatibility with `node:sqlite` is non-negotiable. Never modify `src/upstream/*` manually — use the sync script
+- **Success Validation**: `npm test` (839 pass), `npm run test:node` (295 pass), `npm run lint` (clean)
+
+## Changes Made
+
+### 1. Statement iterator invalidation
+
+Added `reset_generation_` counter to `StatementSync` that increments on every statement reset. `StatementSyncIterator` captures the generation at creation and checks it in `Next()` — throws `ERR_INVALID_STATE` if the statement was reset by another call (run/get/all/iterate).
+
+**Files**: `src/sqlite_impl.h`, `src/sqlite_impl.cpp`
+
+Key details:
+
+- `ResetStatement()` replaces direct `sqlite3_reset()` calls in Run/Get/All/Iterate/Reset
+- Iterator's own `sqlite3_reset(stmt_->statement_)` calls (in Next/Return/ToArray for end-of-iteration) are NOT changed — they bypass `ResetStatement()` intentionally
+- Generation is captured in `SetStatement()`, checked in `Next()`
+
+### 2. DatabaseSync `limits` property
+
+Added `getLimit(id)` and `setLimit(id, value)` native methods. TypeScript layer creates a lazily-cached object with `Object.defineProperty` getters/setters for all 11 SQLite limits.
+
+**Files**: `src/sqlite_impl.h`, `src/sqlite_impl.cpp`, `src/index.ts`, `src/types/database-sync-instance.ts`, `src/types/database-sync-options.ts`
+
+Key details:
+
+- Constructor parses `options.limits` (integer-only, no Infinity, non-negative)
+- Runtime setter accepts `Infinity` to reset to compile-time max (`INT_MAX`)
+- `Object.keys(db.limits)` returns all 11 property names
+- Throws `ERR_INVALID_STATE` when database is closed (handled by native `getLimit`/`setLimit`)
+- Used `defineProperty` over `Proxy` — simpler, zero overhead, 11 fixed properties
+
+### 3. Upstream files
+
+Already synced via `npm run sync:node` — matches v25.x-staging (v25.8.1). Iterator invalidation hasn't landed on v25.x-staging yet, so we're ahead of upstream on that feature.
+
+### 4. Test updates
+
+- `test/invalid-operations.test.ts`: Updated iterator tests to match new invalidation behavior
+- All node-compat test files were already pre-written
+
+## Validation Results
+
+```bash
+$ npm test
+# 55 suites pass, 839 tests pass, 44 skipped
+
+$ npm run test:node
+# 295 pass, 0 fail, 4 skipped
+
+$ npm run lint
+# clean (0 errors)
+```
+
+## Tribal Knowledge
+
+### N-API has no NamedPropertyHandlerConfiguration
+
+V8's `NamedPropertyHandlerConfiguration` (used by upstream for limits) intercepts arbitrary named property access. N-API deliberately omits this. We use `Object.defineProperty` getters/setters in TypeScript instead.
+
+### SQLTagStore pattern: TypeScript over C++
+
+Both SQLTagStore and limits use the same pattern: minimal native primitives (`getLimit`/`setLimit`, `prepare`/`run`/`get`/`all`) with TypeScript orchestration on top. This avoids complex V8-specific C++ (NamedPropertyHandlerConfiguration, DictionaryTemplate, etc.) while maintaining API compatibility.
+
+### Iterator reset*generation* scope
+
+Only `StatementSync::ResetStatement()` increments the generation counter. The iterator's own `sqlite3_reset()` calls for end-of-iteration cleanup do NOT go through `ResetStatement()`. This prevents self-invalidation when iteration completes naturally.

doc/features.md

@@ -14,7 +14,7 @@ Features and capabilities in @photostructure/sqlite.
 
 ## SQLite version
 
-This package includes SQLite 3.51.1 with extensive compile-time options enabled. For complete build flag documentation, comparison with Node.js, and customization options, see [Build Flags & Configuration](./build-flags.md).
+This package includes SQLite 3.52.0 with extensive compile-time options enabled. For complete build flag documentation, comparison with Node.js, and customization options, see [Build Flags & Configuration](./build-flags.md).
 
 ## Enabled SQLite features
 

doc/internal/architecture.md

@@ -149,7 +149,7 @@ void QueueWork(std::function<void()> work) {
 
 1. **Complete Rewrite**: Would lose compatibility and require extensive testing
 2. **Fork Node.js**: Would require users to use custom Node.js build
-3. **Wait for Public API**: Node.js SQLite is still experimental
+3. **Wait for Public API**: Node.js SQLite was experimental at the time; it reached Release Candidate (Stability: 1.2) in v25.7.0
 
 ## Conclusion