latticesql 3.3.4 → 3.4.0

package/docs/api-reference.md

@@ -608,6 +608,54 @@ const stop = await db.watch('./context', {
 stop();
 ```
 
+---
+
+#### `reverseSyncFromFiles(outputDir, opts?): Promise<ReverseSyncResult>`
+
+Detect external modifications to rendered context files and apply changelog-aware reverse-sync updates to the database.
+
+```ts
+const result = await db.reverseSyncFromFiles('./context');
+console.log(`Scanned ${result.filesScanned} files, changed ${result.filesChanged}`);
+
+// With changelog-aware apply and automatic default round-trip:
+await db.reverseSyncFromFiles('./context', {
+  apply: async (update) => {
+    await db.update(update.table, update.pk, update.set);
+  },
+  useDefault: true,
+  onSkip: (info) => {
+    console.log(`Skipped ${info.table}/${info.slug}/${info.filename} (custom render)`);
+  },
+});
+```
+
+Compares file content hashes against the current manifest, so a render-written file is recognized as an echo and skipped. Unlike `reconcile()` (which runs raw SQL), this is the changelog-aware entry point used by the GUI file-loopback: pass `apply` to route each update through a versioned write (so a file edit lands in the changelog and shows up live, just like a GUI edit), and `useDefault` to round-trip structured frontmatter + body `key: value` fields for files without a hand-written `reverseSync` function. A file whose changes can't be safely parsed (free-form/custom render) is surfaced via `onSkip` rather than guessed at, so a lossy render can't corrupt a row.
+
+**`ReverseSyncProcessOptions`** (all optional):
+
+| Option       | Type                                                  | Description                                                                              |
+| ------------ | ----------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| `apply`      | `(update: ReverseSyncUpdate) => Promise<void>`        | Route each update through a changelog-aware path instead of raw SQL                      |
+| `useDefault` | `boolean`                                             | Derive updates for files lacking a hand-written `reverseSync` (frontmatter + body pairs) |
+| `onSkip`     | `(info: { table; slug; filename; filePath }) => void` | Called when a changed file produced no importable update (free-form/custom render)       |
+
+The result reports `filesScanned`, `filesChanged`, `updatesApplied`, and any per-file `errors`.
+
+---
+
+#### `rebuildFtsIndexes(): Promise<void>`
+
+(Re)build the full-text search indexes for all tables with `fts` configuration, backfilling existing rows. Used after `migrate-to-cloud` to ensure search works on a migrated cloud workspace.
+
+```ts
+await db.rebuildFtsIndexes();
+```
+
+The `migrate-to-cloud` command calls this automatically after copying rows; use it manually to recover search if an index was omitted or needs rebuilding. Idempotent — running it multiple times is safe.
+
+---
+
 **`WatchOptions`:**
 
 | Option      | Type                              | Default | Description                                                    |

package/docs/assistant.md

@@ -43,6 +43,14 @@ in the GUI via the same mode-aware navigator the activity feed uses; it links th
 user-facing record (the contract/person/etc.) rather than an internal `files` id,
 and only ids it actually retrieved.
 
+**The assistant reads your organized context.** A new `get_row_context` tool lets
+the assistant pull a record's full rendered context — its own fields, related
+records, and combined summary — in a single call. It leverages the context tree
+Lattice maintains rather than re-stitching together raw reads, so the model can
+answer follow-ups like "summarize this record" or "what are the related items?" in
+one tool call. It falls back to direct row tools when a record hasn't been rendered
+yet.
+
 **Deleting a table is guarded + reversible.** The `delete_entity` tool refuses
 built-in tables, tables another table links to, and tables you don't own. An
 **empty** table is soft-deleted immediately; a **non-empty** one is **not**
@@ -51,6 +59,12 @@ count and the assistant asks, then you choose `delete_data` (soft-delete the row
 too) or `move_to` another table. The physical table + rows are kept (no hard
 drop), so the whole thing is revertible from version history.
 
+**Adding a field to an existing table.** The `add_column` tool lets the assistant
+add a single column to an existing table on request ("add a priority field to
+projects", "add an email column"). The column is registered live, persisted,
+audited, and revertible. On a cloud, the per-column masking view is rebuilt so
+members see the new field immediately.
+
 Conversations persist in the native `chat_threads` / `chat_messages` entities;
 use the thread switcher to revisit them. A new thread is **named from a short AI
 summary** of its first exchange (e.g. "Adding New Notes About Cheese"). The
@@ -74,6 +88,13 @@ open, the chat passes that record (table + id) as context, so "delete this file"
 one. It's a hint only — every action still goes through the same permission-gated
 tools, so it can't reach a record you couldn't otherwise touch.
 
+**Pasted GUI links resolve to the actual record.** When you paste a local GUI link
+(the address bar's `…/#/fs/<table>/<id>`) into the chat, the assistant resolves it
+deterministically to its real data in the database (via the same permission-gated
+read as any other access), so it can answer queries about that record without
+needing to fetch or guess. Resolution happens in code; the resolved data appears in
+context alongside the viewed record.
+
 The assistant can also **answer questions about Lattice itself.** Ask "what is
 private mode?" or "how do I invite a member?" and it calls the `lattice_help` tool,
 which searches Lattice's own documentation (these `docs/*.md` files — the single

package/docs/cloud.md

@@ -158,6 +158,10 @@ Lattice only needs the roles to exist and to be members of `lattice_members`.
 
 ---
 
+### Cloud sharing internals consolidated (v3.4)
+
+The internal machinery backing row sharing was refactored in v3.4 with **no behavior change** to the live features: row `private` / `everyone` / custom "specific people" sharing, table `default_row_visibility` and `never_share`, and the `owner` secret-column mask all work identically. The consolidation removed unreachable masking machinery and moved permission checks into single `SECURITY DEFINER` helpers, eliminating the risk of regressions when sharing logic changes. The changes are additive and idempotent — clouds converge safely on an owner's next open.
+
 ## Sharing: private by default
 
 Every row is **private to its owner** the moment it's written — the per-table
@@ -236,6 +240,22 @@ now lives canonically in the DB and the mask view regenerates from it on change.
 
 ---
 
+## Opening the cloud & the converge
+
+When any member opens a cloud, Lattice runs a **converge** pass: it reads the current Postgres schema against the workspace's registered entities and reconciles them — granting table/column privileges to the member group, rebuilding masking views, installing any missing RLS machinery. Since v3.4, the converge is **per-table fault-isolated**: if the connecting role cannot `ALTER` or `GRANT` a table (most often because it was created by a different Postgres role), that one table is skipped with an actionable reason instead of failing the whole workspace and degrading all objects to "Failed to fetch". The skip is reported in `GET /api/dbconfig` as `convergeWarnings`, for example: `"owned by role X, but this workspace connects as Y — fix with: `ALTER TABLE … OWNER TO Y`"`.
+
+`POST /api/workspaces/reload` re-reads the config and re-registers entities in place without restarting the GUI, so a table added out-of-band surfaces immediately.
+
+### Plaintext database URL heal-on-open
+
+If a workspace config stores a raw `postgres://…` connection string (with its password in cleartext) in the `db:` line — typically from an older workspace or a migration — opening it now automatically moves the URL into the encrypted credential store and rewrites the line to a `${LATTICE_DB:<label>}` reference. This is idempotent: configs already using a reference, or pointing to a SQLite file, are untouched. An existing credential is never overwritten, so the operation is safe to repeat.
+
+## Rendered context scoped to viewer
+
+On a cloud, the background render now reads every table **through the member's row-level-security connection and through the per-column masking view**. The rendered markdown a member's assistant reads off disk contains only the rows they may see (per RLS), with owner-only columns blanked, and with any per-viewer enrichment values they're allowed to see folded in. When sharing changes — a row is shared or un-shared — the affected member's context tree re-renders promptly, so it never lingers on a stale view.
+
+Owners and local single-user workspaces render the full tree unchanged, as before.
+
 ## The three user flows
 
 There are exactly three things you do with a cloud: **migrate** into one, **join**

package/docs/workspaces.md

@@ -67,6 +67,19 @@ join one. Creating/joining switches into the new workspace; the normal layout
 returns on reload. The last workspace can now be deleted (it drops you back to the
 welcome screen rather than being refused).
 
+## Seamless GUI auto-update (3.4)
+
+When `lattice gui` is launched from a published install (global or project-local npm install), it runs as a small supervisor that silently installs the latest published version before opening the browser. While you work, the supervisor keeps checking for updates in the background; when a new version lands it installs it and relaunches the server on the same port. The open tab reconnects, notices the version changed, and reloads onto the new build — **no manual refresh, no reinstall**.
+
+A git checkout or `npx` copy is left untouched (auto-update is disabled there); a failed install surfaces in the GUI rather than being swallowed.
+
+**HTTP endpoints** (for polling / UI integration):
+
+| Route                | Method | Returns                   |
+| -------------------- | ------ | ------------------------- |
+| `/api/version`       | GET    | `{ version: string }`     |
+| `/api/update/status` | GET    | Update state and progress |
+
 ## Auto-render (SQL → markdown)
 
 `enableAutoRender(outputDir)` debounces a re-render on every
@@ -79,6 +92,26 @@ 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)`.
 
+## 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.
+
+**For embedders**, `reverseSyncFromFiles()` exposes the same changelog-aware reverse-sync the GUI loopback uses:
+
+```ts
+import { Lattice } from 'latticesql';
+
+const db = new Lattice(config);
+await db.init();
+
+// Round-trip frontmatter + body `key: value` edits from the rendered tree
+// back into the DB. Pass `apply` to route each update through a versioned
+// write (so a file edit is recorded exactly like a GUI edit).
+const result = await db.reverseSyncFromFiles('./context', { useDefault: true });
+```
+
+`reverseSyncFromFiles(outputDir, opts)` compares file hashes against the current manifest (so a render-written file is recognized as an echo and skipped), parses the changed files, applies the updates, and returns a summary of what was applied.
+
 The canonical `Context/` layout is DB-aligned and zero-config: table → folder,
 row → subfolder, `<ENTITY>.md` plus relation rollups, derived from the schema
 via `deriveCanonicalContexts`.

package/package.json

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