sqlrite 0.10.0__tar.gz → 0.10.1__tar.gz

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

@@ -299,6 +299,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 +322,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;

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

@@ -1189,6 +1189,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 +1215,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 +1261,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/

{sqlrite-0.10.0 → sqlrite-0.10.1}/.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.0 → sqlrite-0.10.1}/Cargo.lock

@@ -4799,7 +4799,7 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-ask"
-version = "0.10.0"
+version = "0.10.1"
 dependencies = [
  "serde",
  "serde_json",
@@ -4827,7 +4827,7 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-desktop"
-version = "0.10.0"
+version = "0.10.1"
 dependencies = [
  "serde",
  "serde_json",
@@ -4839,7 +4839,7 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-engine"
-version = "0.10.0"
+version = "0.10.1"
 dependencies = [
  "clap",
  "env_logger",
@@ -4856,7 +4856,7 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-ffi"
-version = "0.10.0"
+version = "0.10.1"
 dependencies = [
  "cbindgen",
  "serde",
@@ -4866,7 +4866,7 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-mcp"
-version = "0.10.0"
+version = "0.10.1"
 dependencies = [
  "clap",
  "libc",
@@ -4877,7 +4877,7 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-nodejs"
-version = "0.10.0"
+version = "0.10.1"
 dependencies = [
  "napi",
  "napi-build",
@@ -4887,7 +4887,7 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-python"
-version = "0.10.0"
+version = "0.10.1"
 dependencies = [
  "pyo3",
  "sqlrite-engine",

{sqlrite-0.10.0 → sqlrite-0.10.1}/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.1"
 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.1", path = "sqlrite-ask", optional = true }

{sqlrite-0.10.0 → sqlrite-0.10.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlrite
-Version: 0.10.0
+Version: 0.10.1
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License

{sqlrite-0.10.0 → sqlrite-0.10.1}/README.md

@@ -108,6 +108,15 @@ Wire it into Claude Code (`~/.claude.json`):
 
 `--read-only` opens the DB with a shared lock and hides the `execute` tool. Full docs + the other six tools' references in [`docs/mcp.md`](docs/mcp.md).
 
+### End-to-end example apps
+
+Beyond the per-language quickstarts in [`examples/`](examples/), the SQLR-38 umbrella tracks longer, opinionated example apps that exercise SQLRite in real-world shapes:
+
+| App | SDK | What it shows |
+|---|---|---|
+| [Python LLM agent with persistent memory](examples/python-agent/) | Python | Vector + lexical recall, fact extraction, summaries — all in one `.sqlrite` file |
+| [Chat-with-your-notes via Claude Desktop MCP](examples/nodejs-notes/) | Node.js | Markdown → hybrid HNSW + BM25 index → `sqlrite-mcp --read-only` → Claude Desktop |
+
 ### Developer guide
 
 In-depth documentation lives under [`docs/`](docs/). Start at [`docs/_index.md`](docs/_index.md) — it navigates to:

{sqlrite-0.10.0 → sqlrite-0.10.1}/desktop/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sqlrite-desktop-frontend",
   "private": true,
-  "version": "0.10.0",
+  "version": "0.10.1",
   "type": "module",
   "scripts": {
     "dev": "vite",

{sqlrite-0.10.0 → sqlrite-0.10.1}/docs/release-plan.md

@@ -247,7 +247,10 @@ The "publish" half. Auto-fires on the release commit.
     GitHub Release `sqlrite-node-vX.Y.Z`.
   - **publish-wasm** — `wasm-pack build --target bundler --release`,
     then `wasm-pack publish` via OIDC. Creates
-    `sqlrite-wasm-vX.Y.Z` GitHub Release.
+    `sqlrite-wasm-vX.Y.Z` GitHub Release. Installs a
+    [pinned binaryen / wasm-opt](#pinned-binaryen--wasm-opt) before
+    invoking `wasm-pack`, so the published bundle is byte-stable
+    across runner image cache states.
   - **publish-go** — nothing to build on the Go side. Verifies
     `sdk/go/vX.Y.Z` was pushed correctly by `tag-all`. Pulls the
     per-platform `libsqlrite_c` tarballs produced by
@@ -285,6 +288,64 @@ The "publish" half. Auto-fires on the release commit.
   exist (because the real release happened weeks ago). Workflow
   aborts with a clear "tag already exists" error. No damage.
 
+## Pinned binaryen / wasm-opt
+
+The WASM build paths in `ci.yml` (`wasm-build`) and `release.yml`
+(`publish-wasm`) both install a **pinned version of binaryen**
+(which provides `wasm-opt`) before invoking `wasm-pack`. The pin
+lives in a `BINARYEN_VERSION` job-level `env:` in each workflow.
+
+**Current pin: `version_122`** (released Feb 2025).
+
+### Why this exists (SQLR-58)
+
+`wasm-pack` invokes `wasm-opt` to size-optimize the published
+bundle. If `wasm-opt` is already on `PATH`, `wasm-pack` uses that
+one; otherwise it downloads its own copy into a per-runner cache.
+That cache is keyed on the runner image and survives across
+images opaquely — which means CI was getting whatever binaryen
+the cache happened to hold. When the cached copy was old enough
+to predate multi-table WASM support, `wasm-opt` would reject
+recent rustc output with:
+
+> `[parse exception: Only 1 table definition allowed in MVP]`
+> `Fatal: error in parsing input`
+> `Error: failed to execute wasm-opt: exited with exit code: 1`
+
+The failure was non-deterministic (re-runs frequently passed,
+because the new image had a different cache state), but it broke
+the release pipeline at least once before [PR #135](https://github.com/joaoh82/rust_sqlite/pull/135).
+Pinning binaryen + prepending it to `PATH` forces `wasm-pack`
+to always see the same `wasm-opt`, regardless of runner state.
+
+### Bump procedure
+
+1. Look at the [binaryen releases page](https://github.com/WebAssembly/binaryen/releases)
+   and pick a recent stable version (avoid release candidates).
+2. Locally, download that release's `x86_64-linux` tarball and
+   run `wasm-opt --version` to confirm it builds. Optional but
+   nice: also run `wasm-pack build --target web --release` in
+   `sdk/wasm` with the new `wasm-opt` on `PATH` and confirm the
+   `.wasm` artifact size is in the same ballpark as before
+   (regressions > 10% are worth investigating).
+3. Update `BINARYEN_VERSION` in both `.github/workflows/ci.yml`
+   (job `wasm-build`) and `.github/workflows/release.yml` (job
+   `publish-wasm`). Keep the two in lockstep — a divergence
+   means CI and release produce subtly different artifacts.
+4. Update the "Current pin" line above to match.
+5. PR + merge. CI will exercise the new version on the WASM
+   build job before the release pipeline ever sees it.
+
+### Why a tarball, not apt-get
+
+Ubuntu's apt-packaged `binaryen` is reliably 1–2 years behind
+upstream and pinning it requires the matching apt index, which is
+itself unstable across runner image refreshes. The official
+WebAssembly/binaryen GitHub release tarballs are stable URLs and
+sha-pinnable (we don't currently verify the sha256 — a follow-up
+if supply-chain integrity becomes a concern; the tarball is
+short-lived and contained to the runner).
+
 ## Secrets / one-time setup
 
 With lockstep + OIDC-based trusted publishing, the only long-lived

{sqlrite-0.10.0 → sqlrite-0.10.1}/docs/sql-engine.md

@@ -133,7 +133,7 @@ Two specialized shortcuts in [`src/sql/executor.rs`](../src/sql/executor.rs) rec
 ORDER BY vec_distance_l2(<col>, <bracket-array literal>) ASC LIMIT k
 ```
 
-Returns top-k from the HNSW graph in `O(log N)` per probe. Mirrored shapes for `vec_distance_cosine` and `vec_distance_dot`.
+Returns top-k from the HNSW graph in `O(log N)` per probe. Mirrored shapes for `vec_distance_cosine` and `vec_distance_dot`. INSERT maintains HNSW incrementally. DELETE / UPDATE mark the graph dirty; the next INSERT on the indexed vector column rebuilds the in-memory graph from surviving rows before adding the new node, and save/COMMIT still rebuilds dirty graphs before serializing.
 
 `try_fts_probe` (Phase 8b) — BM25 keyword:
 

{sqlrite-0.10.0 → sqlrite-0.10.1}/examples/README.md

@@ -16,6 +16,15 @@ Phase 5 lands these incrementally — each sub-phase fills in one language. The
 
 See [docs/roadmap.md](../docs/roadmap.md) for what each sub-phase delivers.
 
+## End-to-end example apps
+
+Beyond the per-SDK quick-start tours above, the [SQLR-38 umbrella](../docs/roadmap.md) tracks longer, opinionated example apps that exercise SQLRite end-to-end in real-world shapes:
+
+| App | Language / SDK | What it shows | Directory |
+|---|---|---|---|
+| LLM agent with persistent memory | Python | Vector + lexical recall, fact extraction, summaries — all in one `.sqlrite` file | [`python-agent/`](python-agent/) |
+| Chat with your notes (MCP)       | Node.js | Markdown → SQLRite hybrid retrieval, served to Claude Desktop via `sqlrite-mcp --read-only` | [`nodejs-notes/`](nodejs-notes/) |
+
 ## Running the Rust quickstart
 
 ```bash
@@ -63,6 +72,27 @@ python examples/python/hello.py
 
 Mirrors the Rust quickstart shape via the DB-API: `sqlrite.connect(":memory:")` → `cursor.execute` → iterate tuples, plus a BEGIN/ROLLBACK block. See [`python/hello.py`](python/hello.py) and [`sdk/python/README.md`](../sdk/python/README.md) for the full API tour.
 
+## Running the Python LLM agent (SQLR-39)
+
+```bash
+cd examples/python-agent
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e .
+python -m sqlrite_agent          # works offline; no API key required
+```
+
+A full CLI chat agent whose long-term memory is one `.sqlrite` file. Embeds each turn, hybrid-searches over past messages and a structured `facts` table on every recall, and survives process restarts. Read [`python-agent/README.md`](python-agent/README.md) for the demo script and architecture diagram.
+
+## Running the Node.js notes assistant (SQLR-40)
+
+```bash
+cd examples/nodejs-notes
+npm install
+node bin/sqlrite-notes.mjs init ~/Documents/notes
+```
+
+Ingests a folder of markdown notes into a `notes.sqlrite` file with HNSW + BM25 indexes, then `sqlrite-notes serve` wraps `sqlrite-mcp --read-only` so **Claude Desktop / any MCP client** can `bm25_search` / `vector_search` / `query` / `ask` your local notes directly — no cloud sync, no third-party indexer. Default embedder is fully offline (deterministic hash bag-of-words); flip to `--embedder openai` with `OPENAI_API_KEY` set for real semantic recall. Read [`nodejs-notes/README.md`](nodejs-notes/README.md) for the Claude Desktop config snippet and the hybrid-retrieval SQL walkthrough.
+
 ## Running the Node.js sample
 
 ```bash

sqlrite-0.10.1/examples/nodejs-notes/.gitignore

@@ -0,0 +1,6 @@
+node_modules/
+*.sqlrite
+*.sqlrite-journal
+.env
+.env.local
+test-fixtures-tmp/