ltcai 8.1.0 → 8.3.0

package/docs/V3_BACKEND_ARCHITECTURE.md

@@ -1,138 +0,0 @@
-# Lattice AI v3 Backend Architecture
-
-Lattice AI v3 keeps the product local-first and knowledge-centric by combining
-three retrieval layers inside the backend:
-
-```text
-User Data
-  -> Chunking
-  -> Local Embeddings
-  -> SQLite Vector Index
-
-User Data
-  -> Entity Extraction
-  -> Relationship Extraction
-  -> SQLite Knowledge Graph
-
-Search
-  -> Hybrid Retrieval
-     -> Keyword
-     -> Vector
-     -> Graph
-  -> Unified Results
-```
-
-## Storage Model
-
-The authoritative knowledge store remains `knowledge_graph.py` on SQLite.
-Existing legacy graph rows are preserved, with the normalized v2 projection kept
-as a derived read surface.
-
-- `nodes`: entities, documents, folders, conversations, tasks, decisions, and
-  chunk nodes.
-- `edges`: directed relationships with type, weight, metadata, and timestamps.
-- `chunks`: extracted text chunks linked back to the source node.
-- `knowledge_sources` and `local_file_index`: approved local folder indexing
-  state, source metadata, and incremental scan bookkeeping.
-- `vector_embeddings`: derived local vector index rows for non-chunk nodes and
-  full chunk text.
-- `vector_index_operations`: rebuild/incremental indexing history and status.
-
-Vector rows are derived data. A full rebuild may delete and recreate vector
-rows, but it does not mutate source documents, nodes, relationships, chunks, or
-local file records.
-
-## Embeddings
-
-The default embedding model is `lattice-local-hash-v1`, a deterministic local
-feature-hashing embedder in `latticeai/core/local_embeddings.py`.
-
-It provides:
-
-- no cloud dependency,
-- no model download requirement,
-- deterministic output for tests and migrations,
-- normalized vectors for cosine similarity by dot product,
-- a stable interface for replacing the implementation with a local model
-  runtime later.
-
-It is a fallback vector signal, not a production semantic embedding model.
-Future provider support may include Ollama, MLX, OpenAI-compatible providers,
-and other local embedding providers behind the same vector-index interface.
-
-## Search Model
-
-`latticeai/services/search_service.py` composes the retrieval layers.
-
-- Keyword search uses the existing graph text search over title, summary, and
-  metadata.
-- Vector search embeds the query locally and ranks SQLite vector rows by
-  similarity.
-- Graph search performs direct graph matching, relationship search, and bounded
-  neighbor expansion.
-- Hybrid search fuses the three result streams with configurable weights and
-  returns one UI-ready result shape with per-source scores.
-
-Default hybrid weights:
-
-```json
-{
-  "keyword": 0.35,
-  "vector": 0.40,
-  "graph": 0.25
-}
-```
-
-## API Contracts
-
-The v3 backend exposes frontend-ready routes under `/api` while preserving all
-existing `/knowledge-graph/...` compatibility routes.
-
-```text
-POST /api/search/hybrid
-GET  /api/search/hybrid?q=...
-POST /api/search/keyword
-GET  /api/search/keyword?q=...
-POST /api/search/vector
-GET  /api/search/vector?q=...
-GET  /api/graph
-GET  /api/graph/node?node_id=...
-POST /api/graph/node
-GET  /api/graph/relationship
-POST /api/graph/relationship
-GET  /api/index/status
-POST /api/index/rebuild
-```
-
-Results include stable fields for UI consumption:
-
-- `id`
-- `node_id`
-- `item_type`
-- `type`
-- `title`
-- `summary`
-- `score`
-- `rank`
-- `sources`
-- `source_scores`
-- `metadata`
-- `updated_at`
-- optional `graph_context`
-
-## Migration Impact
-
-The migration is additive and non-destructive:
-
-- new SQLite tables are created with `CREATE TABLE IF NOT EXISTS`,
-- existing graph and local file data is preserved,
-- normalized v2 graph projection remains a derived compatibility layer,
-- vector rows can be rebuilt from existing graph/chunk rows,
-- `GET /api/index/status` reports missing or stale vector items,
-- `POST /api/index/rebuild` repairs the derived index.
-
-## Backend Ownership
-
-This architecture deliberately avoids frontend shell redesign. The backend owns
-storage, indexing, retrieval, ranking, and API contracts; the UI can consume the
-new `/api` routes without requiring visual system changes.

package/docs/V3_FRONTEND.md

@@ -1,146 +0,0 @@
-# Lattice AI v3 — Frontend Product Shell
-
-> Historical v3 shell notes. The current product shell is the React/Vite app
-> built from `frontend/` into `static/app/` with `npm run build:assets`; current
-> linting uses `scripts/lint_frontend.mjs`.
-
-> A token-native single-page workspace shell for Lattice AI v3. It ships as the
-> primary product experience and calls the real v3 retrieval/chat APIs while
-> rendering clear unavailable states for local services that are not running.
-
-Entry point: **`/app`** (served by `latticeai/api/static_routes.py` →
-the current `static/app/index.html` bundle; the historical v3 shell used
-`static/v3/index.html`). Login, auto-login after registration, SSO callback, and
-the PWA manifest land on `/app`. Legacy multi-page static screens have been
-deleted; compatibility routes (`/workspace`, `/chat`, `/graph`, `/admin`, …)
-redirect into their `/app#/...` views.
-
----
-
-## Product model
-
-| Concept | Surface |
-| --- | --- |
-| **Personal / Organization workspace** | Scope switcher in the rail (`X-Workspace-Id` header is sent on every adapter call). |
-| **Basic / Advanced / Admin mode** | Mode switcher in the topbar. Mode gates which rail items appear and how dense each view is. |
-| **Retrieval lattice** | The signature identity: **Knowledge Graph + Vector Index + Hybrid Search**, surfaced on Home and as a live 3-dot index chip in the topbar. |
-
-Mode gating (`MODE_RANK` in `core/routes.js`): Basic ⊂ Advanced ⊂ Admin.
-Deep-linking into an `admin/*` route auto-promotes the shell to Admin mode.
-
----
-
-## Information architecture
-
-One declarative table (historically `static/v3/js/core/routes.js`, now
-represented by the React routes under `frontend/src/`) drives the nav rail, the
-command palette, the router, breadcrumbs, and lazy view loading.
-
-```
-Brain          Knowledge Graph · Hybrid Search · Memory
-Ask            Chat
-Capture        Files · Pipeline*
-Act            Agents* · Runs* · Workflows* · Planning* · Hooks*
-Library        Models · Skills* · MCP* · Marketplace*
-System         Overview · Account · Workspaces · Snapshots · Activity · Network* · Settings · My Computer*
-Administration Users · Permissions · Audit Logs · Security · Policies · Private VPC   (admin mode)
-```
-
-`*` = revealed in Advanced mode and above. Routes are hash-based
-(`#/knowledge-graph`, `#/admin/users`) so the SPA needs no server rewrites.
-
----
-
-## Design system
-
-Token-native, layered on the existing **single color source**
-(`static/css/tokens.css`, `data-lt-theme` light/dark). No legacy override layers
-(`responsive.css` / `workspace.css` / `platform.css`) are loaded by v3.
-Runtime assets are loaded through `static/app/asset-manifest.json`; the build
-step writes hashed CSS/JS assets and `/app` reads the manifest instead of
-using manual `?v=` query strings.
-
-| File | Responsibility |
-| --- | --- |
-| `css/lattice.tokens.css` | Structural tokens — type scale, spacing (4pt), radii, elevation, motion, z-index, layout rails, pillar accents, lattice mesh. |
-| `css/lattice.base.css` | Reset, element defaults, the signature lattice backdrop, a11y utilities. |
-| `css/lattice.components.css` | Primitive vocabulary — cards, panels, buttons, inputs, pills, stats, tables, tabs, switches, meters, empty/loading/error states, toasts. |
-| `css/lattice.shell.css` | App chrome — rail, topbar, command palette, mobile drawer, retrieval pillars. |
-| `css/lattice.views.css` | Bespoke view layouts — hero, graph canvas, search results, chat, files, pipeline, admin. |
-
-**Rule:** component CSS uses only `var(--token)`; no per-component hardcoded
-themed colors and no `!important`. Both themes flow from the token values.
-
-**Identity:** a crystalline *lattice* mark, a faint node-and-edge mesh backdrop,
-and a three-pillar retrieval motif (graph = blue, vector = teal, hybrid =
-magenta). Deliberately **not** a clone of ChatGPT / Claude / Cursor / VS Code /
-Notion / Obsidian.
-
----
-
-## Shell + view contract
-
-`core/shell.js` builds the chrome and renders views. Each view is a lazy ES
-module under `js/views/` exporting:
-
-```js
-export async function render(ctx) { /* … */ return singleDomNode; }
-// optional: export const layout = "flush";  // full-bleed (chat)
-```
-
-`ctx = { h, icon, api, store, c, route, params, navigate, toast }`
-
-- `h()` — dependency-free hyperscript (`core/dom.js`); child strings are
-  auto-escaped (no injection surface).
-- `c` — component factories (`core/components.js`).
-- `store` — observable app state (theme / mode / workspace), persisted to
-  `localStorage` (`core/store.js`).
-
----
-
-## Integration contract
-
-`core/api.js` is the only transport layer. Every call hits the **real** endpoint
-first and returns `{ ok, status, data, source }` where `source` is `"live"` or
-`"unavailable"`. Unavailable responses carry empty data so primary surfaces do
-not invent counters, sample graphs, fake health, or fake run history.
-
-Core live surfaces established before v3.2.0:
-
-| Adapter | Endpoint | Unavailable state |
-| --- | --- | --- |
-| `api.indexStatus()` | `GET /api/index/status` | empty retrieval status |
-| `api.graph(params)` | `GET /api/graph` → `GET /knowledge-graph/graph` | empty graph |
-| `api.hybridSearch(q, opts)` | `POST /api/search/hybrid` | empty results |
-| `api.streamChat(body)` | `POST /chat` SSE | unavailable chat message |
-
-No backend retrieval logic is implemented in the frontend — only transport,
-normalization, clear provenance badges, and graceful fallback. When the live
-chat backend reports `no_model_loaded`, v3 Chat shows a setup message instead of
-falling back to generated text.
-
-Embedding disclosure: production profiles are exposed for local/Ollama/MLX and
-OpenAI-compatible providers. `lattice-local-hash-v1` remains a deterministic
-fallback and is not presented as a production semantic embedding model.
-
----
-
-## Responsive strategy
-
-- **Desktop (≥1101px):** full 268px rail + content.
-- **Tablet (761–1100px):** rail collapses to a 76px icon rail.
-- **Mobile (≤760px):** rail becomes an off-canvas drawer (hamburger in the
-  topbar); grids collapse to single column; the chat context rail hides.
-
-Plus: `prefers-color-scheme` following, `prefers-reduced-motion` honored, visible
-focus rings, skip link, keyboard command palette (⌘K / Ctrl-K).
-
----
-
-## Validation
-
-- `npm run lint` (covers the current frontend through `scripts/lint_frontend.mjs`).
-- `npm run build:assets` (writes hashed `static/app` assets and `asset-manifest.json`).
-- `npm run test:visual` (`tests/visual/v3.spec.js` against the mock server, which
-  serves `/app` and mocks the future API surfaces).
-- Browser-rendered smoke checks of every route in light and dark themes.

package/docs/V4_1_FRONTEND_ARCHITECTURE_REVIEW.md

@@ -1,65 +0,0 @@
-# v4.1.0 Frontend Architecture Review
-
-## Scope
-
-This review covers the v4.1.0 replacement of the `/app` frontend and desktop
-shell. It does not redesign Brain Core, storage, backend API contracts, or the
-agent/workflow runtime.
-
-## Baseline
-
-v4.0.1 served a static frontend assembled under `static/v3` with bespoke build
-and lint scripts. Capability parity existed, but the implementation duplicated
-view systems, carried legacy static route assumptions, and could not cleanly
-share typed API contracts with the FastAPI backend.
-
-## Target Architecture
-
-- Desktop shell: Tauri 2.0 primary, Electron fallback only.
-- Frontend: React, TypeScript, Vite, TanStack Query, Zustand, React Flow,
-  Cytoscape.js, Tailwind CSS, local shadcn-style primitives.
-- API: generated OpenAPI TypeScript client from the existing FastAPI app.
-- Runtime: single client-side SPA, no SSR, no CDN.
-- Backend: existing FastAPI app remains the source of truth.
-
-## Implemented Architecture
-
-- `frontend/` owns the React/Vite source.
-- `frontend/src/api/openapi.ts` is generated from `frontend/openapi.json`.
-- `frontend/src/api/client.ts` wraps generated-client JSON calls and keeps
-  streaming chat plus multipart upload as explicit fetch special cases.
-- `frontend/src/routes.ts` defines Brain, Ask, Capture, Act, Library, System and
-  maps legacy hash routes into those groups.
-- `static/app` is the shipped build output and is served by `/app`.
-- `src-tauri/` contains the Tauri 2.0 shell and backend-origin bridge.
-- `desktop/electron/` contains the fallback shell.
-- `static/sw.js` precaches the React app manifest/assets for offline-capable
-  local startup.
-
-## Boundary Decisions
-
-- The backend contract was preserved; only the frontend consumer changed.
-- Brain Core and storage modules were not modified for UI convenience.
-- No CDN fallback was introduced; all visual/runtime dependencies are bundled.
-- No demo-only controls were added. Unavailable capabilities render explicit
-  unavailable/error states based on API responses.
-- npm runtime installs are kept lean: React/Vite/Tauri/Electron toolchains are
-  development dependencies because the distributable app ships built assets.
-
-## Capability Mapping
-
-| v4.0.1 capability | v4.1.0 surface |
-| --- | --- |
-| Knowledge Graph, hybrid search, memory, provenance, portability | Brain |
-| Chat, conversations, context trace, attachments | Ask |
-| Uploads, connected folders, local runtime, URL capture, index pipeline | Capture |
-| Agents, runs, approvals, workflows, triggers, hooks, tools | Act |
-| Models, embeddings, skills, MCP, templates/plugins | Library |
-| Account, auth, workspaces, snapshots, activity, network, settings, admin/security | System |
-
-## Residual Risk
-
-- The first Vite bundle is larger than 500 kB after minification because graph,
-  workflow, and app shell libraries are included in the initial desktop SPA
-  bundle. This is a performance optimization target, not a capability blocker,
-  and the build remains fully local/offline.

package/docs/V4_1_FRONTEND_MIGRATION_REPORT.md

@@ -1,70 +0,0 @@
-# v4.1.0 Frontend Migration Report
-
-## Objective
-
-Replace the v4.0.1 static frontend implementation with the Digital Brain
-desktop architecture while preserving capabilities, user data, backend API
-contracts, and local-first/offline operation.
-
-## Migration Summary
-
-- Added React + TypeScript + Vite source under `frontend/`.
-- Added generated OpenAPI schema/client files under `frontend/openapi.json` and
-  `frontend/src/api/openapi.ts`.
-- Added React capability pages for Brain, Ask, Capture, Act, Library, System.
-- Added Tauri 2.0 desktop shell under `src-tauri/`.
-- Added Electron fallback shell under `desktop/electron/`.
-- Replaced `/app` static serving with `static/app/index.html`.
-- Replaced v3 asset build/lint scripts with Vite build and frontend lint guards.
-- Removed `static/v3` and retired `scripts/build_v3_assets.mjs` /
-  `scripts/lint_v3.mjs`.
-- Updated package metadata so Python wheel/sdist, npm tgz, and VSIX builds ship
-  the new `static/app` assets.
-
-## Compatibility
-
-- Existing FastAPI routes are preserved.
-- The generated OpenAPI client is produced from the live app schema.
-- Legacy app hash routes are mapped into the new primary navigation groups.
-- Service worker caching now targets the Vite app manifest instead of v3 assets.
-- User data formats, Brain database files, Workspace OS state, snapshots,
-  conversations, memories, and graph data are not migrated or destructively
-  changed by the frontend rebuild.
-
-## Capability Parity
-
-| Capability | Migration result |
-| --- | --- |
-| Brain graph exploration | Cytoscape.js graph view in Brain |
-| Hybrid search | Brain search tab backed by `/api/search/hybrid` |
-| Memory recall | Brain memory tab backed by memory APIs |
-| Provenance and portability | Brain provenance/portability actions |
-| Chat and context trace | Ask surface with streaming chat and context panel |
-| Conversation management | Ask history backed by conversation APIs |
-| Document upload | Capture upload using multipart backend endpoint |
-| Connected folders/local runtime | Capture desktop/local runtime APIs |
-| Index pipeline and URL capture | Capture pipeline/browser ingestion APIs |
-| Agents and run records | Act agents/runs/approvals backed by runtime APIs |
-| Workflow graph | Act React Flow visualization and workflow APIs |
-| Triggers, hooks, tools | Act surfaces backed by trigger/hook/tool APIs |
-| Models and embeddings | Library model/embedding APIs |
-| Skills, MCP, templates/plugins | Library registry APIs |
-| Account/auth/profile/password | System account APIs |
-| Workspaces/invitations | System workspace APIs |
-| Snapshots/time-machine | System snapshot APIs |
-| Activity/presence/network | System activity and network APIs |
-| Admin/security/settings | System admin and settings APIs |
-
-## Removed Frontend Debt
-
-- Duplicate static v3 view modules.
-- Legacy frontend build pipeline.
-- Legacy v3 frontend lint script.
-- Static v3 asset tree in release packages.
-- Direct then-current release references to v4.0.1 in then-latest docs.
-
-## Data Preservation
-
-No user data migration is required for v4.1.0. All persisted state remains owned
-by the existing backend stores. The frontend rebuild only changes the client and
-desktop shell used to access those stores.

package/docs/V4_1_VALIDATION_REPORT.md

@@ -1,47 +0,0 @@
-# v4.1.0 Validation Report
-
-## Summary
-
-v4.1.0 RC validation passed for the React/Vite frontend, Tauri desktop shell,
-FastAPI backend compatibility, release artifacts, and installed-wheel smoke.
-
-## Commands Run
-
-| Area | Command | Result |
-| --- | --- | --- |
-| OpenAPI generation | `npm run frontend:openapi` | Pass; generated 308 paths |
-| Static app build | `npm run build:assets` | Pass; wrote `static/app/asset-manifest.json` |
-| Frontend lint / no CDN / API compatibility | `npm run lint` | Pass; scanned 28 frontend/static files; OpenAPI exposes 308 paths |
-| TypeScript build | `npm run typecheck` | Pass; frontend TS + VS Code extension build |
-| Python compile | `npm run check:python` | Pass; compiled 206 modules |
-| Ruff | `node scripts/run_python.mjs -m ruff check .` | Pass |
-| Unit tests | `npm run test:unit -- --tb=short` | Pass; 585 passed, 2 warnings |
-| Live integration tests | `LTCAI_TEST_BASE_URL=http://127.0.0.1:8899 npm run test:integration -- --tb=short` | Pass; 9 passed |
-| Playwright visual/offline tests | `npx playwright test tests/visual/v3.spec.js` | Pass; 12 passed |
-| Tauri cargo check | `npm run desktop:tauri:check` | Pass |
-| Tauri desktop build | `LATTICEAI_DESKTOP_NO_BACKEND=1 npm run desktop:tauri:build` | Pass; built `.app` and DMG |
-| Electron fallback syntax/version | `node --check desktop/electron/main.cjs && npx electron --version` | Pass; Electron v42.4.0 |
-| Release artifacts | `npm run release:artifacts` plus resumed `npm pack && npm run package:vsix` | Pass |
-| Artifact validation | `npm run release:validate` | Pass; exact v4.1.0 wheel/sdist/VSIX/tgz found |
-| Wheel smoke | `node scripts/run_python.mjs scripts/wheel_smoke.py --wheel dist/ltcai-4.1.0-py3-none-any.whl` | Pass; imports 19 modules and `/health` reports 4.1.0 |
-| npm pack dry-run | `npm pack --dry-run` | Pass; `ltcai-4.1.0.tgz`, 259 files, 2.9 MB |
-
-## Generated Artifacts
-
-- `dist/ltcai-4.1.0-py3-none-any.whl`
-- `dist/ltcai-4.1.0.tar.gz`
-- `dist/ltcai-4.1.0.vsix`
-- `ltcai-4.1.0.tgz`
-- `src-tauri/target/release/bundle/macos/Lattice AI.app`
-- `src-tauri/target/release/bundle/dmg/Lattice AI_4.1.0_aarch64.dmg`
-
-## Notes
-
-- Vite reports one large initial bundle warning after minification. The app
-  remains fully local/offline and passes visual/offline startup validation.
-- `cargo check` reports a future-incompatibility warning in transitive
-  `block v0.1.6`; the current Tauri 2.0 build passes on Rust 1.96.
-- Release artifact validation warns that historical artifacts remain in
-  `dist/`; this is expected and reinforces the rule to upload only exact
-  v4.1.0 filenames, never a wildcard from the `dist` directory.
-- No external registry publish was performed.

package/docs/V4_2_BRAIN_CORE_ARCHITECTURE.md

@@ -1,97 +0,0 @@
-# Lattice AI v4.2.0 — Brain Core Architecture
-
-Status: released validation complete
-
-v4.2.0 extracts the Digital Brain backend boundary into the importable
-`lattice_brain` package while preserving the existing FastAPI contracts and the
-v4.1.0 user data layout. FastAPI, CLI, tests, and future tools can now import
-Brain Core directly instead of reaching through root compatibility modules.
-
-## Package Boundary
-
-- `lattice_brain` is the independent Brain Core package namespace.
-- `latticeai.brain` remains as a compatibility namespace for existing callers.
-- Root modules such as `knowledge_graph.py` and `kg_schema.py` remain
-  compatibility shims.
-- FastAPI now constructs the graph and durable conversation store through
-  `lattice_brain.BrainCore`.
-
-## Brain Core Surfaces
-
-The package exposes the implemented v4 brain modules:
-
-- Knowledge system: `KnowledgeGraphStore`
-- Memory system: `BrainMemory`
-- Context assembler: `ContextAssembler`
-- Durable conversations: `ConversationStore`
-- Device identity and signed exchange helpers
-- Brain Network compatibility exports
-- Encrypted `.latticebrain` archives
-- Storage abstraction and migration tools
-
-The frontend still talks only to FastAPI localhost APIs. No frontend code calls
-Python directly.
-
-## Storage Layer
-
-`lattice_brain.storage` introduces:
-
-- `StorageEngine` ABC
-- `SQLiteEngine` default engine
-- `PostgresEngine` opt-in engine with pgvector extension setup
-- `DockerPostgresWizard` explicit-consent local Docker setup
-- `SQLiteToPostgresMigrator` idempotent migration planner/runner, including
-  rowid-less FTS5 shadow table support through declared primary keys
-
-SQLite remains the default. Postgres is never required. If
-`LATTICEAI_STORAGE_ENGINE=postgres` is selected without a DSN or optional
-dependency support, startup fails honestly instead of silently falling back to
-SQLite.
-
-## Vector Search
-
-SQLite vector search remains real and local:
-
-- Existing vector rows stay in `vector_embeddings`.
-- The active fallback is deterministic local hash embeddings with brute-force
-  cosine scoring.
-- `sqlite-vec` is detected and loaded when available.
-- Capability reports distinguish `sqlite-vec` from `bruteforce-cosine`; the
-  fallback is reported honestly and is still a real search path.
-
-Postgres scale mode initializes a pgvector-backed `brain_vectors` table when
-the `vector` extension is available.
-
-## Archive Model
-
-v4.2.0 adds encrypted `.latticebrain` archives:
-
-- AES-256-GCM payload encryption
-- PBKDF2-HMAC-SHA256 key derivation
-- Encrypted SQLite database and blob payload
-- Restore replaces the target DB/WAL/SHM safely and restores blobs
-- Wrong passphrase or tampered data fails closed
-
-The existing JSON export/import and ZIP backup/restore paths remain compatible.
-
-## FastAPI APIs
-
-New localhost APIs:
-
-- `GET /api/brain/storage`
-- `POST /api/brain/storage/postgres/docker`
-- `POST /api/brain/storage/migrate-postgres`
-- `POST /api/knowledge-graph/archive`
-- `POST /api/knowledge-graph/archive/restore`
-
-All mutating operations require admin authorization. Docker starts only when the
-request explicitly carries consent.
-
-## Compatibility
-
-- Existing v4.1.0 SQLite data remains in `knowledge_graph.sqlite`.
-- Existing `knowledge_graph.py`, `kg_schema.py`, and `latticeai.brain.*`
-  imports continue to work.
-- Existing FastAPI routes remain available.
-- Existing release artifacts still build.
-- No data-loss migration is performed automatically.

package/docs/V4_2_STORAGE_MIGRATION_REPORT.md

@@ -1,91 +0,0 @@
-# Lattice AI v4.2.0 — Storage Migration Report
-
-Status: released validation complete
-
-v4.2.0 adds a pluggable storage layer without changing the default local-first
-runtime. Existing users continue on SQLite. Postgres is an explicit opt-in
-scale target, not a required dependency and not an automatic fallback.
-
-## Existing Data
-
-- Existing v4.1.0 data remains in `~/.ltcai/knowledge_graph.sqlite`.
-- Blob payloads remain in `~/.ltcai/knowledge_graph_blobs/`.
-- Durable conversations continue to share the same SQLite DB family.
-- No startup migration rewrites user data for v4.2.0.
-
-## SQLite Engine
-
-`SQLiteEngine` owns SQLite connection setup:
-
-- WAL mode
-- foreign keys enabled
-- local path creation
-- backup and restore helpers
-- sqlite-vec loading attempt when installed
-- honest capability report when sqlite-vec is unavailable
-
-The current graph store continues to use SQLite-specific SQL and is therefore
-wired only to `SQLiteEngine` for the active FastAPI runtime.
-
-## Postgres Engine
-
-`PostgresEngine` is opt-in and fail-closed:
-
-- Requires `LATTICEAI_POSTGRES_DSN` when explicitly selected.
-- Requires optional `psycopg` support.
-- Creates `lattice_brain` schema by default.
-- Runs `CREATE EXTENSION IF NOT EXISTS vector`.
-- Creates a pgvector-backed `brain_vectors` table.
-
-If Postgres is selected but unavailable, Lattice AI reports the error. It does
-not hide the failure by falling back to SQLite.
-
-## Docker Setup
-
-`DockerPostgresWizard` writes a local Docker Compose file for
-`pgvector/pgvector:pg16`. It never runs Docker unless the caller explicitly
-passes consent.
-
-API behavior:
-
-- `consent=false`: writes the compose file and returns `consent_required`.
-- `dry_run=true`: returns the exact Docker command without starting anything.
-- `consent=true` and `dry_run=false`: runs `docker compose up -d postgres`.
-
-## SQLite to Postgres Migration
-
-`SQLiteToPostgresMigrator` plans and copies all user tables from a SQLite brain
-database into Postgres:
-
-- Introspects non-internal SQLite tables.
-- Preserves every row.
-- Uses table `id` as the idempotence key when present.
-- Uses declared primary keys, including composite keys on rowid-less FTS5 shadow
-  tables.
-- Uses preserved `__source_rowid` when no declared key exists and SQLite rowid
-  is available.
-- Upserts rows on repeated runs.
-- Leaves the source SQLite database untouched.
-
-The API defaults to dry-run migration planning. Actual copy requires an
-explicit DSN and `dry_run=false`.
-
-Live v4.2.0 validation used explicit Docker consent to start
-`pgvector/pgvector:pg16`, copy a seeded v4 SQLite brain database into
-Postgres, verify source and destination row counts, rerun the migration
-idempotently, query pgvector distance ordering, and tear down the test Compose
-stack with volumes.
-
-## Encrypted Archives
-
-`.latticebrain` archive support was added for local encrypted backup/restore:
-
-- Database and blobs are zipped locally.
-- Payload is encrypted with AES-256-GCM.
-- Keys derive from the user passphrase via PBKDF2-HMAC-SHA256.
-- Restore rejects bad passphrases or tampered payloads.
-
-## Compatibility Result
-
-No v4.1.0 capability is removed. SQLite remains the default and does not depend
-on Docker, Postgres, pgvector, or network access.