sqlrite 0.10.0__tar.gz → 0.10.2__tar.gz

{sqlrite-0.10.0 → sqlrite-0.10.2}/.github/workflows/ci.yml

@@ -10,6 +10,7 @@
 #   - go-sdk                {ubuntu, macos}            cgo against libsqlrite_c + go test
 #   - wasm-build            ubuntu                     wasm-pack build + size report
 #   - desktop-build         ubuntu                     npm ci + cargo build -p sqlrite-desktop
+#   - journal-build         ubuntu                     npm ci + cargo build -p sqlrite-journal (SQLR-41 example)
 #
 # All jobs use caching so a warm PR run takes 2–3 minutes on ubuntu.
 # Go CI skips Windows for Phase 6b — Go's cgo on Windows needs a mingw
@@ -102,6 +103,7 @@ jobs:
         run: |
           cargo build --workspace \
             --exclude sqlrite-desktop \
+            --exclude sqlrite-journal \
             --exclude sqlrite-python \
             --exclude sqlrite-nodejs \
             --exclude sqlrite-benchmarks \
@@ -111,6 +113,7 @@ jobs:
         run: |
           cargo test --workspace \
             --exclude sqlrite-desktop \
+            --exclude sqlrite-journal \
             --exclude sqlrite-python \
             --exclude sqlrite-nodejs \
             --exclude sqlrite-benchmarks
@@ -147,6 +150,7 @@ jobs:
         run: |
           cargo clippy --workspace \
             --exclude sqlrite-desktop \
+            --exclude sqlrite-journal \
             --exclude sqlrite-python \
             --exclude sqlrite-nodejs \
             --exclude sqlrite-benchmarks \
@@ -158,6 +162,7 @@ jobs:
         run: |
           cargo doc --workspace \
             --exclude sqlrite-desktop \
+            --exclude sqlrite-journal \
             --exclude sqlrite-python \
             --exclude sqlrite-nodejs \
             --exclude sqlrite-benchmarks \
@@ -299,6 +304,15 @@ jobs:
   wasm-build:
     name: wasm-build
     runs-on: ubuntu-latest
+    # Pinned binaryen version — see docs/release-plan.md
+    # ("Pinned binaryen / wasm-opt") for the bump procedure. Older
+    # binaryen rejects rustc's multi-table WASM output with
+    # "Only 1 table definition allowed in MVP", which the runner
+    # image's cache state used to surface non-deterministically
+    # (SQLR-58). Pinning keeps wasm-opt out of "whatever's cached"
+    # territory.
+    env:
+      BINARYEN_VERSION: version_122
     steps:
       - uses: actions/checkout@v4
 
@@ -313,12 +327,29 @@ jobs:
           workspaces: sdk/wasm
           shared-key: wasm-build
 
+      - name: Install pinned binaryen (wasm-opt)
+        # MUST run before wasm-pack: wasm-pack picks up wasm-opt from
+        # PATH if present, otherwise downloads whatever binaryen its
+        # own internal cache happens to have. Pinning + prepending
+        # to PATH forces a deterministic version across runner images.
+        run: |
+          set -euo pipefail
+          curl -fsSL "https://github.com/WebAssembly/binaryen/releases/download/${BINARYEN_VERSION}/binaryen-${BINARYEN_VERSION}-x86_64-linux.tar.gz" \
+            -o "$RUNNER_TEMP/binaryen.tar.gz"
+          tar -xzf "$RUNNER_TEMP/binaryen.tar.gz" -C "$RUNNER_TEMP"
+          echo "$RUNNER_TEMP/binaryen-${BINARYEN_VERSION}/bin" >> "$GITHUB_PATH"
+          "$RUNNER_TEMP/binaryen-${BINARYEN_VERSION}/bin/wasm-opt" --version
+
       - name: Install wasm-pack
         uses: jetli/wasm-pack-action@v0.4.0
 
       - name: wasm-pack build --target web --release
         working-directory: sdk/wasm
-        run: wasm-pack build --target web --release
+        run: |
+          # Sanity-check that the pinned wasm-opt is what wasm-pack sees.
+          which wasm-opt
+          wasm-opt --version
+          wasm-pack build --target web --release
 
       - name: Report .wasm size
         # Surfaces size regressions in PR logs. Not a hard limit yet;
@@ -374,3 +405,58 @@ jobs:
 
       - name: Build Rust side
         run: cargo build -p sqlrite-desktop
+
+  # ---------------------------------------------------------------------------
+  # Journal example (SQLR-41): Tauri 2 + Svelte 5 daily-notes app under
+  # `examples/desktop-journal/`. Same shape as `desktop-build` — frontend
+  # first, then `cargo build -p sqlrite-journal`. Excluded from the
+  # default workspace commands for the same reasons (Svelte build is a
+  # prerequisite that the main rust-build-and-test job can't satisfy).
+  journal-build:
+    name: journal-build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: examples/desktop-journal/package-lock.json
+
+      - uses: dtolnay/rust-toolchain@stable
+
+      - name: Install Tauri Linux deps
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y \
+            libwebkit2gtk-4.1-dev \
+            libayatana-appindicator3-dev \
+            librsvg2-dev \
+            patchelf
+
+      - uses: Swatinem/rust-cache@v2
+        with:
+          shared-key: journal-build
+
+      - name: npm install
+        working-directory: examples/desktop-journal
+        # `npm ci` would be ideal, but the example doesn't ship a
+        # lockfile in version control (it's listed in .gitignore so
+        # downstream forkers don't have to fight a node-version-pinned
+        # lockfile). `npm install` is acceptable for an example app;
+        # the engine API surface is what we're really exercising.
+        run: npm install
+
+      - name: Build frontend
+        working-directory: examples/desktop-journal
+        run: npm run build
+
+      - name: Build Rust side (with ask)
+        run: cargo build -p sqlrite-journal --all-targets
+
+      - name: Build Rust side (no ask)
+        run: cargo build -p sqlrite-journal --no-default-features --all-targets
+
+      - name: Run journal unit tests
+        run: cargo test -p sqlrite-journal

sqlrite-0.10.2/.github/workflows/journal-release.yml

@@ -0,0 +1,103 @@
+# SQLRite Journal — installer build workflow (SQLR-41).
+#
+# Produces packaged installers for the example desktop journal app:
+#   - macOS:  .dmg + .app bundle
+#   - Linux:  .deb + .AppImage
+#   - Windows: .msi (best-effort; flag in README if it lights up red)
+#
+# Manual trigger by default — installers are heavy (~30–40 min total
+# wall clock across the matrix), and the example app changes much less
+# often than the engine. Tagged pushes matching `journal-v*` also fire.
+# Artifacts are attached to a draft GitHub release rather than the
+# engine's own release stream so engine releases don't accidentally
+# ship a journal binary baseline that's lagging behind.
+
+name: Journal example — installers
+
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - 'journal-v*'
+
+permissions:
+  contents: write   # tauri-action needs this to upload to the draft release
+
+jobs:
+  build:
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: macos-latest
+            label: macos-arm64
+            target: aarch64-apple-darwin
+          - os: macos-13
+            label: macos-x86_64
+            target: x86_64-apple-darwin
+          - os: ubuntu-latest
+            label: linux-x86_64
+            target: x86_64-unknown-linux-gnu
+          - os: windows-latest
+            label: windows-x86_64
+            target: x86_64-pc-windows-msvc
+
+    name: build (${{ matrix.label }})
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: ${{ matrix.target }}
+
+      - name: Install Tauri Linux deps
+        if: matrix.os == 'ubuntu-latest'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y \
+            libwebkit2gtk-4.1-dev \
+            libayatana-appindicator3-dev \
+            librsvg2-dev \
+            patchelf \
+            libsoup-3.0-dev \
+            libjavascriptcoregtk-4.1-dev
+
+      - uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: ./examples/desktop-journal/src-tauri
+          shared-key: journal-release-${{ matrix.label }}
+
+      - name: npm install
+        working-directory: examples/desktop-journal
+        run: npm install
+
+      # tauri-action does the magic: builds frontend, runs `cargo tauri
+      # build`, and uploads the resulting installers to a draft release
+      # tagged with `tagName`. We deliberately don't auto-publish — a
+      # human reviews the draft and clicks publish.
+      - uses: tauri-apps/tauri-action@v0
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          projectPath: examples/desktop-journal
+          tagName: ${{ startsWith(github.ref, 'refs/tags/journal-v') && github.ref_name || format('journal-v{0}', github.run_number) }}
+          releaseName: 'SQLRite Journal ${{ startsWith(github.ref, ''refs/tags/journal-v'') && github.ref_name || format(''build-{0}'', github.run_number) }}'
+          releaseBody: |
+            Installer artifacts for the SQLRite Journal example app
+            (SQLR-41). Built against the engine version pinned in
+            `examples/desktop-journal/src-tauri/Cargo.toml`.
+
+            * macOS: `.dmg` (Apple Silicon + Intel)
+            * Linux: `.deb` + `.AppImage`
+            * Windows: `.msi`
+
+            Source: <https://github.com/joaoh82/rust_sqlite/tree/main/examples/desktop-journal>
+          releaseDraft: true
+          prerelease: false
+          args: --target ${{ matrix.target }}

{sqlrite-0.10.0 → sqlrite-0.10.2}/.github/workflows/release-pr.yml

@@ -86,13 +86,15 @@ jobs:
 
       - name: Refresh Cargo.lock
         # `cargo build` updates Cargo.lock with the new workspace
-        # member versions. `--exclude sqlrite-desktop` because the
-        # desktop crate needs the Svelte frontend compiled first
-        # (Tauri's build.rs looks for `desktop/dist/`) — we're not
-        # building a release artifact here, just refreshing the lock.
-        # `--quiet` keeps the log tidy; a real compile failure still
-        # surfaces.
-        run: cargo build --workspace --exclude sqlrite-desktop --quiet
+        # member versions. We exclude the two Tauri crates
+        # (`sqlrite-desktop`, `sqlrite-journal`): both need their Svelte
+        # frontend compiled first (Tauri's build.rs looks for a `dist/`)
+        # and pull in the GTK/glib system stack that this runner doesn't
+        # install — we're not building a release artifact here, just
+        # refreshing the lock. Keep this exclude list in sync with the
+        # cargo steps in ci.yml. `--quiet` keeps the log tidy; a real
+        # compile failure still surfaces.
+        run: cargo build --workspace --exclude sqlrite-desktop --exclude sqlrite-journal --quiet
 
       - name: Configure git identity
         # Use the github-actions[bot] identity so the commit shows

{sqlrite-0.10.0 → sqlrite-0.10.2}/.github/workflows/release.yml

@@ -131,6 +131,7 @@ jobs:
             "sqlrite-desktop-v$V"
             "sqlrite-py-v$V"
             "sqlrite-node-v$V"
+            "sqlrite-notes-v$V"
             "sqlrite-wasm-v$V"
             "sdk/go/v$V"
             "v$V"
@@ -1154,6 +1155,108 @@ jobs:
             See the umbrella release [v${{ needs.detect.outputs.version }}](../../releases/tag/v${{ needs.detect.outputs.version }}) for the full changelog.
           generate_release_notes: true
 
+  # ---------------------------------------------------------------------------
+  # Step 3g': publish the `sqlrite-notes` example as a pure-JS npm
+  # package so users can `npx sqlrite-notes init <dir>` on a fresh
+  # machine without cloning the repo. (SQLR-64, follow-up from SQLR-40.)
+  #
+  # The package itself ships no binaries — it's a thin CLI on top of
+  # the `@joaoh82/sqlrite` N-API package (which carries the prebuilt
+  # `.node` binaries via the platform-dispatch shim) and spawns
+  # `sqlrite-mcp` as a subprocess for the read side. The Node bits
+  # are platform-agnostic JS modules, so this job is a single ubuntu
+  # cell instead of the publish-nodejs build matrix.
+  #
+  # `needs: publish-nodejs` is load-bearing: the example's
+  # `@joaoh82/sqlrite` dep pin resolves against the version that
+  # publish-nodejs just put on npm. Without that ordering, `npx
+  # sqlrite-notes@<new>` would resolve a slightly-stale engine on
+  # the first install after release (caret pin floats up *eventually*
+  # but the npm cache will have served the old one for minutes).
+  #
+  # Package name: **unscoped `sqlrite-notes`** (per ticket). The
+  # similarity rejection that hit `sqlrite` (vs `sqlite`) doesn't
+  # apply here — `notes` isn't a confusable suffix. If the registry
+  # ever rejects this on a future bootstrap, fall back to
+  # `@joaoh82/sqlrite-notes` and update both `package.json` and
+  # `docs/release-secrets.md`'s trusted-publisher section.
+  #
+  # OIDC trusted-publisher setup mirrors publish-nodejs verbatim —
+  # see that job's comment block for the long-form rationale on why
+  # `registry-url` is omitted, why we force-upgrade npm to 11.5+, and
+  # why `--provenance --access public --loglevel verbose` is the
+  # canonical flag combo.
+  publish-notes-example:
+    name: Publish sqlrite-notes example to npm
+    needs: [detect, tag-all, publish-nodejs]
+    if: needs.detect.outputs.should_release == 'true'
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      # OIDC for npm trusted publisher + provenance signing.
+      id-token: write
+      # For softprops/action-gh-release at the end.
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+
+      # Same OIDC dance as publish-nodejs — see that job's comment
+      # block for why we deliberately do NOT set `registry-url:`.
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Upgrade npm to latest (need 11.5+ for trusted publishing)
+        run: npm install -g npm@latest
+
+      - name: List publish payload + OIDC env diagnostics
+        working-directory: examples/nodejs-notes
+        run: |
+          ls -la
+          echo "---"
+          npm --version
+          echo "---"
+          echo "ACTIONS_ID_TOKEN_REQUEST_URL  is set: ${ACTIONS_ID_TOKEN_REQUEST_URL:+yes}${ACTIONS_ID_TOKEN_REQUEST_URL:-NO}"
+          echo "ACTIONS_ID_TOKEN_REQUEST_TOKEN is set: ${ACTIONS_ID_TOKEN_REQUEST_TOKEN:+yes}${ACTIONS_ID_TOKEN_REQUEST_TOKEN:-NO}"
+          echo "---"
+          # `npm pack --dry-run` prints exactly what will end up in
+          # the tarball. The `files` whitelist in package.json should
+          # produce: bin/sqlrite-notes.mjs, src/*.mjs, README.md,
+          # package.json — nothing else (no test fixtures, no
+          # node_modules).
+          npm pack --dry-run
+
+      - name: Publish to npm
+        working-directory: examples/nodejs-notes
+        run: npm publish --access public --provenance --loglevel verbose
+
+      - name: GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: sqlrite-notes-v${{ needs.detect.outputs.version }}
+          name: sqlrite-notes example v${{ needs.detect.outputs.version }}
+          body: |
+            Published to npm: https://www.npmjs.com/package/sqlrite-notes/v/${{ needs.detect.outputs.version }}
+
+            ```bash
+            # Ingest a folder of markdown notes into a SQLRite database
+            # — no clone, no Rust toolchain, no env setup beyond an
+            # optional embedding API key.
+            npx sqlrite-notes@${{ needs.detect.outputs.version }} init ~/Documents/notes
+            ```
+
+            The example uses `@joaoh82/sqlrite@^${{ needs.detect.outputs.version }}` for storage + retrieval (HNSW + BM25) and spawns [`sqlrite-mcp`](../../releases/tag/sqlrite-mcp-v${{ needs.detect.outputs.version }}) as a subprocess to expose the database to Claude Desktop / any MCP client. Install `sqlrite-mcp` separately — `cargo install sqlrite-mcp` or a prebuilt binary from the MCP release.
+
+            Verify package provenance:
+            ```bash
+            npm audit signatures
+            ```
+
+            Full docs: [`examples/nodejs-notes/README.md`](https://github.com/joaoh82/rust_sqlite/blob/main/examples/nodejs-notes/README.md).
+
+            See the umbrella release [v${{ needs.detect.outputs.version }}](../../releases/tag/v${{ needs.detect.outputs.version }}) for the full changelog.
+          generate_release_notes: true
+
   # ---------------------------------------------------------------------------
   # Step 3h: build the WASM package via wasm-pack and publish to
   # npm as @joaoh82/sqlrite-wasm. (Phase 6h.)
@@ -1189,6 +1292,14 @@ jobs:
     if: needs.detect.outputs.should_release == 'true'
     runs-on: ubuntu-latest
     environment: release
+    # Pinned binaryen version — see docs/release-plan.md
+    # ("Pinned binaryen / wasm-opt") for the bump procedure. Older
+    # binaryen rejects rustc's multi-table WASM output with
+    # "Only 1 table definition allowed in MVP" (SQLR-58). The
+    # release pipeline can't tolerate that flake — a failed
+    # publish-wasm leaves the rest of the release wave inconsistent.
+    env:
+      BINARYEN_VERSION: version_122
     permissions:
       # OIDC: required for npm trusted-publisher token exchange.
       # Same flow proven in publish-nodejs after the v0.1.5–0.1.7
@@ -1207,6 +1318,20 @@ jobs:
           shared-key: publish-wasm
           workspaces: 'sdk/wasm -> target'
 
+      - name: Install pinned binaryen (wasm-opt)
+        # MUST run before wasm-pack: wasm-pack picks up wasm-opt
+        # from PATH if present, otherwise downloads whatever
+        # binaryen its own internal cache happens to have. Pinning
+        # + prepending to PATH forces a deterministic version
+        # across runner images.
+        run: |
+          set -euo pipefail
+          curl -fsSL "https://github.com/WebAssembly/binaryen/releases/download/${BINARYEN_VERSION}/binaryen-${BINARYEN_VERSION}-x86_64-linux.tar.gz" \
+            -o "$RUNNER_TEMP/binaryen.tar.gz"
+          tar -xzf "$RUNNER_TEMP/binaryen.tar.gz" -C "$RUNNER_TEMP"
+          echo "$RUNNER_TEMP/binaryen-${BINARYEN_VERSION}/bin" >> "$GITHUB_PATH"
+          "$RUNNER_TEMP/binaryen-${BINARYEN_VERSION}/bin/wasm-opt" --version
+
       # Install wasm-pack — the canonical tool for building +
       # packaging Rust crates as npm-publishable WASM modules.
       # `cargo binstall` would be faster than `cargo install`
@@ -1239,6 +1364,9 @@ jobs:
       - name: Build WASM package
         working-directory: sdk/wasm
         run: |
+          # Sanity-check that the pinned wasm-opt is on PATH (SQLR-58).
+          which wasm-opt
+          wasm-opt --version
           wasm-pack build --release --target bundler --scope joaoh82
           echo "--- generated pkg/ contents ---"
           ls -la pkg/
@@ -1455,7 +1583,7 @@ jobs:
   # config if we add one later.
   finalize:
     name: Finalize umbrella release
-    needs: [detect, publish-crate, publish-ask, publish-mcp, build-mcp-binaries, publish-ffi, publish-desktop, publish-python, publish-nodejs, publish-wasm, publish-go]
+    needs: [detect, publish-crate, publish-ask, publish-mcp, build-mcp-binaries, publish-ffi, publish-desktop, publish-python, publish-nodejs, publish-notes-example, publish-wasm, publish-go]
     if: needs.detect.outputs.should_release == 'true'
     runs-on: ubuntu-latest
     steps:
@@ -1479,6 +1607,7 @@ jobs:
             - 🖥️ [Desktop](../../releases/tag/sqlrite-desktop-v${{ needs.detect.outputs.version }}) — unsigned installers for Linux (AppImage + deb), macOS (dmg aarch64), Windows (msi)
             - 🐍 [Python](../../releases/tag/sqlrite-py-v${{ needs.detect.outputs.version }}) → [PyPI](https://pypi.org/project/sqlrite/${{ needs.detect.outputs.version }}/) — abi3-py38 wheels for Linux x86_64/aarch64, macOS aarch64, Windows x86_64 + sdist
             - 🟢 [Node.js](../../releases/tag/sqlrite-node-v${{ needs.detect.outputs.version }}) → [npm](https://www.npmjs.com/package/@joaoh82/sqlrite/v/${{ needs.detect.outputs.version }}) — N-API bindings with prebuilt `.node` binaries for Linux x86_64/aarch64, macOS aarch64, Windows x86_64
+            - 📝 [`sqlrite-notes` example](../../releases/tag/sqlrite-notes-v${{ needs.detect.outputs.version }}) → [npm](https://www.npmjs.com/package/sqlrite-notes/v/${{ needs.detect.outputs.version }}) — `npx sqlrite-notes init <dir>` ingests a folder of markdown notes into a SQLRite DB and exposes it to Claude Desktop / any MCP client
             - 🌐 [WASM](../../releases/tag/sqlrite-wasm-v${{ needs.detect.outputs.version }}) → [npm](https://www.npmjs.com/package/@joaoh82/sqlrite-wasm/v/${{ needs.detect.outputs.version }}) — browser/bundler-target WebAssembly build via wasm-pack
             - 🐹 [Go SDK](../../releases/tag/sdk%2Fgo%2Fv${{ needs.detect.outputs.version }}) → `go get github.com/joaoh82/rust_sqlite/sdk/go@v${{ needs.detect.outputs.version }}` — `database/sql` driver via cgo against `libsqlrite_c`
 

{sqlrite-0.10.0 → sqlrite-0.10.2}/.gitignore

@@ -44,3 +44,12 @@ examples/wasm/pkg
 
 # macOS
 .DS_Store
+
+# Local agent / Claude Code worktrees. These shouldn't ever get
+# committed — but `git add -A` from main while a worktree is live
+# under .claude/worktrees/<name>/ will capture it as a gitlink
+# (mode 160000) because the worktree dir looks like a submodule to
+# the parent index. Ignoring the whole tree prevents that whole
+# class of accident. (The release commit 937f8b4 hit exactly this
+# bug; the next commit untracks the leftover gitlinks.)
+.claude/worktrees/

sqlrite-0.10.2/AGENTS.md

@@ -0,0 +1,102 @@
+# AGENTS.md
+
+This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.
+
+## Project
+
+SQLRite is a from-scratch SQLite-style embedded database written in Rust. It's published on crates.io as `sqlrite-engine` (imported as `use sqlrite::…` — the lib target keeps the short name) and ships as: a REPL binary (`sqlrite`), a Tauri 2 + Svelte 5 desktop app, a Model Context Protocol stdio server (`sqlrite-mcp`), a C FFI shim (`sqlrite-ffi`), and language SDKs (Python via PyO3, Node via napi-rs, Go via cgo, WASM via wasm-bindgen). Phases 1–7 are shipped; the current branch `phase-8-plan` drafts inverted-index + BM25 full-text search and hybrid retrieval.
+
+## Workspace layout
+
+`Cargo.toml` is a workspace whose members are: `.` (the engine, package `sqlrite-engine`, lib `sqlrite`), `desktop/src-tauri`, `examples/desktop-journal/src-tauri`, `sqlrite-ffi`, `sqlrite-ask`, `sqlrite-mcp`, `sdk/python`, `sdk/nodejs`, `benchmarks`. `sdk/wasm` and `sdk/go` are deliberately **not** workspace members (wasm32 target / cgo separation).
+
+- `src/` — engine. Public API is `Connection`/`Statement`/`Rows`/`Row`/`Value` from [src/connection.rs](src/connection.rs), re-exported via [src/lib.rs](src/lib.rs). Any new SDK should bind only to this surface.
+- `sqlrite-ask/` — pure-Rust LLM adapter (Anthropic/OpenAI/Ollama) for natural-language → SQL. The engine's `ask` feature provides the thin `ConnectionAskExt::ask` glue.
+- `sqlrite-mcp/` — MCP stdio server. Seven tools: `list_tables`, `describe_table`, `query`, `execute`, `schema_dump`, `vector_search`, `ask`. `--read-only` opens with a shared lock and hides `execute`.
+- `sqlrite-ffi/` — C ABI cdylib + generated `sqlrite.h` header. Backs the Go SDK and any C consumer.
+- `desktop/` — Tauri 2 + Svelte 5 generic SQL playground GUI. Embeds the engine directly (no FFI hop).
+- `examples/desktop-journal/` — Tauri 2 + Svelte 5 local-first journaling app (SQLR-41). Showcase for Phase 8 BM25 + `ask` in a non-AI-native product. Mirrors `desktop/`'s engine-as-Cargo-dep pattern but uses the modern `Connection` API.
+- `benchmarks/` — SQLR-4 / SQLR-16 bench harness. `Driver` trait + SQLRite + SQLite (rusqlite-bundled) drivers + criterion-driven workloads. Excluded from the default CI build/test/clippy/doc commands; run locally with `make bench` (or `make bench-duckdb`). See [docs/benchmarks-plan.md](docs/benchmarks-plan.md).
+- `web/` — marketing + docs site (Next.js 15 + Tailwind v4). Independent of the Cargo workspace; lives in-repo for now but is structured to lift into its own repository later. See [web/README.md](web/README.md).
+
+Architecture deep-dive: [docs/architecture.md](docs/architecture.md). The full doc index is [docs/_index.md](docs/_index.md).
+
+## Engine data flow
+
+SQL string → [src/sql/mod.rs](src/sql/mod.rs) `process_command` parses with the external `sqlparser` crate (SQLite dialect) → [src/sql/parser/](src/sql/parser/) trims the AST into internal structs (`CreateQuery`, `InsertQuery`, `SelectQuery`) → [src/sql/executor.rs](src/sql/executor.rs) runs the statement against the in-memory `Database` ([src/sql/db/database.rs](src/sql/db/database.rs)). On any write, auto-save serializes changed pages through [src/sql/pager/](src/sql/pager/) — 4 KiB pages, cell-encoded B-trees per table and index, WAL + crash-safe checkpoint, fs2 advisory locks. Vector search (Phase 7d) goes through [src/sql/hnsw.rs](src/sql/hnsw.rs); KNN uses a bounded-heap top-k in the executor. Transactions snapshot the in-memory state; ROLLBACK restores it. There is no query optimizer beyond the KNN/HNSW shortcut, no joins, no aggregates yet.
+
+## Commands
+
+CI is the source of truth — the workspace excludes that follow are required because the desktop crate needs a Svelte build first, the PyO3/napi-rs cdylibs can't link standalone test binaries, and the `benchmarks/` harness deliberately stays out of CI (criterion is noisy on shared runners; the rusqlite-bundled build is heavy).
+
+```sh
+# Build / test the Rust workspace (matches CI)
+cargo build --workspace --exclude sqlrite-desktop --exclude sqlrite-journal --exclude sqlrite-python --exclude sqlrite-nodejs --exclude sqlrite-benchmarks --all-targets
+cargo test  --workspace --exclude sqlrite-desktop --exclude sqlrite-journal --exclude sqlrite-python --exclude sqlrite-nodejs --exclude sqlrite-benchmarks
+
+# Single test (exact name; --nocapture to see println!)
+cargo test <test_name> -- --nocapture
+
+# Lint (CI runs all three)
+cargo fmt --all -- --check
+cargo clippy --workspace --exclude sqlrite-desktop --exclude sqlrite-journal --exclude sqlrite-python --exclude sqlrite-nodejs --exclude sqlrite-benchmarks --all-targets
+cargo doc    --workspace --exclude sqlrite-desktop --exclude sqlrite-journal --exclude sqlrite-python --exclude sqlrite-nodejs --exclude sqlrite-benchmarks --no-deps
+
+# Run the REPL (default features include cli + ask + file-locks)
+cargo run                                  # in-memory
+cargo run -- path/to/db.sqlrite            # open/create file
+cargo run -- --readonly path/to/db.sqlrite # shared-lock open
+
+# Crate-specific
+cargo build --release -p sqlrite-ffi       # C cdylib + sqlrite.h
+cd desktop && npm install && npm run tauri dev   # desktop app dev mode
+cargo run -p sqlrite-mcp -- /path/to.sqlrite     # MCP server (stdio)
+cd examples/desktop-journal && npm install && npm run tauri dev  # journal example app
+
+# Benchmarks (SQLR-4 / SQLR-16) — local-only, never CI
+make bench                                 # SQLRite + SQLite (lean)
+make bench-duckdb                          # adds DuckDB driver (Group B only)
+
+# Release plumbing
+scripts/bump-version.sh 0.2.0              # bumps version across 11 manifests
+```
+
+`SQLRITE_LLM_API_KEY` is required for the `.ask` REPL command, the engine's `ask` feature, and the MCP `ask` tool. Clippy is **not** `-D warnings` yet (intentional — see top of [.github/workflows/ci.yml](.github/workflows/ci.yml)); deny-by-default lints still fail CI.
+
+## Project-specific conventions
+
+- **Errors.** Single `SQLRiteError` enum (thiserror, six variants) with a project-wide `Result<T>` alias. All public APIs return typed errors; no panics. The enum hand-rolls `PartialEq` because `std::io::Error` doesn't derive it.
+- **Storage isn't bincode.** Tables and indexes share a cell-encoded B-tree format with a 4 KiB page size; the file header carries a format version (currently v4 after the Phase 7a vector column work). The diff-based pager only writes changed pages. See [docs/file-format.md](docs/file-format.md) and [docs/pager.md](docs/pager.md).
+- **B-tree commit strategy.** Bottom-up rebuild on every commit (O(N), correct-by-construction). No in-place splits — deferred design decision.
+- **Feature gates matter.** `default = ["cli", "ask", "file-locks"]`. The REPL `[[bin]]` `required-features = ["cli", "ask"]`. WASM and lean library embeddings build with `default-features = false` to avoid rustyline / clap / fs2 / sqlrite-ask. Don't pull these into the always-on dependency set.
+- **Don't reinvent the SQL parser.** `sqlparser` is the tokenizer and AST source; project code only narrows that AST. New SQL features start by mapping the existing `sqlparser` AST node, not by extending a custom grammar.
+- **Phase numbering is real.** The roadmap is sequenced in [docs/roadmap.md](docs/roadmap.md); design discussions live at github.com/sqlrite/design and feature work generally tracks an open phase plan in `docs/phase-*-plan.md`. Treat in-flight phase plans as load-bearing context.
+- **Concurrency.** Engine mutates state through `Arc<Mutex<_>>` (Tauri-friendly). On-disk concurrency uses fs2 advisory locks: shared for readers, exclusive for the single writer.
+
+## Knowledge Base
+
+### Project-specific — `~/Documents/josh-obsidian-synced/Projects/rust_sqlite/`
+
+- **Code:** `/Users/joaoh82/projects/rust_sqlite`
+- **Context (read first):** `~/Documents/josh-obsidian-synced/Projects/rust_sqlite/context.md`
+- **Notes (running journal):** `~/Documents/josh-obsidian-synced/Projects/rust_sqlite/notes.md`
+- **Project wiki:** `~/Documents/josh-obsidian-synced/Projects/rust_sqlite/wiki/`
+
+**How to use each:**
+
+- `context.md` — stable background (product goals, stakeholders, domain). Read before starting non-trivial work. Update only when underlying facts change.
+- `notes.md` — append-only dated journal. Add entries under `## YYYY-MM-DD` headings for decisions, blockers, TODOs, and incidents — anything worth preserving but not stable enough for `context.md`.
+- `wiki/` — reference sub-docs (e.g. `Architecture.md`, `Local Dev Setup.md`, `Tech Services.md`). Create new files as topics emerge.
+
+**When to save:**
+
+- New stable fact about the product/domain → update `context.md`.
+- A decision, incident, or working note → append a dated entry to `notes.md`.
+- Reusable reference material (setup steps, credential locations, architecture) → new/updated file in `wiki/`.
+
+### Cross-project knowledge — `~/Documents/josh-obsidian-synced/vault/`
+
+- **General wiki:** `~/Documents/josh-obsidian-synced/vault/wiki/` — start at `_master-index.md`, then drill into the relevant topic's `_index.md`.
+- **Raw dumps:** `~/Documents/josh-obsidian-synced/vault/raw/` — drop unprocessed research here as `YYYY-MM-DD-{slug}.md`.
+
+Read the general wiki when the question isn't specific to this project. Drop raw research or imported notes into `vault/raw/` so it's captured even before it's distilled.

{sqlrite-0.10.0 → sqlrite-0.10.2}/Cargo.lock

@@ -4799,7 +4799,7 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-ask"
-version = "0.10.0"
+version = "0.10.2"
 dependencies = [
  "serde",
  "serde_json",
@@ -4827,7 +4827,7 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-desktop"
-version = "0.10.0"
+version = "0.10.2"
 dependencies = [
  "serde",
  "serde_json",
@@ -4839,7 +4839,7 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-engine"
-version = "0.10.0"
+version = "0.10.2"
 dependencies = [
  "clap",
  "env_logger",
@@ -4856,7 +4856,7 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-ffi"
-version = "0.10.0"
+version = "0.10.2"
 dependencies = [
  "cbindgen",
  "serde",
@@ -4864,9 +4864,22 @@ dependencies = [
  "sqlrite-engine",
 ]
 
+[[package]]
+name = "sqlrite-journal"
+version = "0.10.1"
+dependencies = [
+ "serde",
+ "serde_json",
+ "sqlrite-engine",
+ "tauri",
+ "tauri-build",
+ "tauri-plugin-dialog",
+ "thiserror 2.0.18",
+]
+
 [[package]]
 name = "sqlrite-mcp"
-version = "0.10.0"
+version = "0.10.2"
 dependencies = [
  "clap",
  "libc",
@@ -4877,7 +4890,7 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-nodejs"
-version = "0.10.0"
+version = "0.10.2"
 dependencies = [
  "napi",
  "napi-build",
@@ -4887,7 +4900,7 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-python"
-version = "0.10.0"
+version = "0.10.2"
 dependencies = [
  "pyo3",
  "sqlrite-engine",

{sqlrite-0.10.0 → sqlrite-0.10.2}/Cargo.toml

@@ -27,7 +27,7 @@ resolver = "3"
 # `package =` key so the import name stays `sqlrite` internally:
 #     sqlrite = { package = "sqlrite-engine", path = "…" }
 name = "sqlrite-engine"
-version = "0.10.0"
+version = "0.10.2"
 authors = ["Joao Henrique Machado Silva <joaoh82@gmail.com>"]
 edition = "2024"
 rust-version = "1.85"
@@ -150,4 +150,4 @@ fs2 = { version = "0.4", optional = true }
 # crate publishes to crates.io, and a path-only dep without a
 # version field fails the manifest verification step. See PR #58
 # retrospective in docs/roadmap.md.
-sqlrite-ask = { version = "0.10.0", path = "sqlrite-ask", optional = true }
+sqlrite-ask = { version = "0.10.2", path = "sqlrite-ask", optional = true }