latticesql 4.2.0 → 4.2.2

package/docs/configuration.md

@@ -17,6 +17,7 @@ Complete reference for `lattice.config.yml` — the YAML schema config format in
 - [Multiple entities](#multiple-entities)
 - [Programmatic config API](#programmatic-config-api)
 - [Complete example](#complete-example)
+- [Troubleshooting](#troubleshooting)
 
 ---
 
@@ -451,3 +452,29 @@ without `fts` are still searchable via the LIKE fallback. Indexes are created
 **only** for opt-in tables, so a library consumer with no `fts` config incurs
 no index and no write-path overhead. See `docs/api-reference.md` →
 _Full-text search_ for the `fullTextSearch` API.
+
+## Troubleshooting
+
+### The local SQLite engine auto-rebuilds when the Node runtime changes
+
+The local SQLite backend is powered by the `better-sqlite3` native module,
+whose compiled binary is pinned to the Node ABI present when it was installed.
+If your Node version later changes — a package-manager upgrade, a version
+switch via a Node manager, or simply a different Node in CI than on your
+machine — that prebuilt binary no longer matches the runtime.
+
+Lattice handles this transparently: the SQLite engine is loaded the first time
+a workspace opens, and when it detects an ABI mismatch it **automatically
+rebuilds `better-sqlite3` for the current runtime** in-process, then continues.
+You'll see a single line on stderr while the rebuild runs (so a slow rebuild
+isn't a silent hang); on success there's nothing else to do.
+
+An error is surfaced only as a last resort — when the module isn't installed at
+all, or the automatic rebuild can't complete (no build toolchain, no network to
+fetch a prebuild, etc.). In that case the message tells you exactly what to run:
+`npm rebuild better-sqlite3` (or a clean reinstall), then retry.
+
+To disable the automatic rebuild (e.g. in a sandboxed or read-only environment
+where you'd rather manage the native module yourself), set the environment
+variable `LATTICE_SQLITE_NO_AUTOREBUILD=1`. With it set, an ABI mismatch raises
+the same actionable error instead of attempting a rebuild.

package/docs/workspaces.md

@@ -92,6 +92,16 @@ A bare `new Lattice(path)` does **not** auto-render (`_scheduleAutoRender`
 early-returns when no output dir is set) — call `render(dir)` / `reconcile(dir)`
 manually, or opt in with `enableAutoRender(dir)`.
 
+On open, a staleness gate decides whether the existing tree can be reused or must
+be re-rendered. Alongside the data cursor (has anything the tree depends on
+changed?), the manifest records a **render-output format version**. When a
+release changes how the tree is derived or templated — i.e. the bytes a clean
+render produces for unchanged data — that version is bumped, and the gate treats
+any workspace whose manifest records an older version as stale. The result is a
+**one-time full re-render on the first open after upgrading**, so a render-logic
+fix reaches workspaces rendered by an older version automatically; once the
+manifest is re-stamped, subsequent opens skip again when nothing has changed.
+
 ## File loopback (3.4)
 
 When the GUI is serving a workspace, editing a rendered `.md` file on disk is automatically captured back into the database through the normal write path — so the change lands in the changelog (versioned/undoable) and appears live in the GUI, exactly as if the edit had been made there. Structured frontmatter and body `key: value` fields round-trip automatically; edits that can't be safely parsed (free-form or custom renders) are surfaced as a notice rather than guessed at, so a lossy render can't corrupt a row. Render echoes are suppressed via the manifest, so there is no write loop.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "latticesql",
-  "version": "4.2.0",
+  "version": "4.2.2",
   "description": "Persistent structured memory for AI agent systems — pluggable SQLite or Postgres backend, LLM context bridge",
   "type": "module",
   "main": "./dist/index.js",