latticesql 1.13.10 → 1.15.0

package/README.md

@@ -804,6 +804,16 @@ await db.seed({
 });
 ```
 
+A junction link whose target row doesn't resolve is **never silently dropped**. `SeedResult.unresolvedLinks` lists every such link (source record, field, target name, junction). Pass `onUnresolvedLink: 'throw'` to abort with a `SeedReconciliationError` instead — for pipelines that must never leave a record citing a relationship that has no link in the graph:
+
+```typescript
+const result = await db.seed({ ...config, onUnresolvedLink: 'collect' });
+if (result.unresolvedLinks.length) {
+  // create the missing targets, then re-seed
+  console.warn('unresolved links:', result.unresolvedLinks);
+}
+```
+
 ### `buildReport()` (v0.14+)
 
 ```typescript
@@ -2091,12 +2101,14 @@ The convergence means you don't need to duplicate entity-context definitions in
 
 **Dashboard renders every entity (v1.13.3+).** Previously the dashboard cards filtered through a hardcoded entity list (`meetings`, `people`, `messages`, `projects`, `repositories`, `files`). Installs whose YAML declared different names saw a blank dashboard. Now every first-class entity gets a card; the hardcoded list survives as an ordering preference only.
 
+**Approximate row counts on Postgres (v1.14.1+).** The dashboard / entity-list view reads row counts from `pg_class.reltuples` (the planner statistic maintained by `ANALYZE` / autovacuum) so that a single query covers every table. Older versions issued one `COUNT(*)` per table in parallel, which exhausted small connection pools (e.g. a 95-table database against Supabase's 15-slot session pooler). The trade is that list-view counts are approximate and include soft-deleted rows for tables that have a `deleted_at` column; per-table drill-in still shows exact filtered counts. SQLite-backed installs are unaffected and continue to show exact, soft-delete-aware counts (no pool to exhaust).
+
 **Views**
 
 - **Dashboard** (`#/`) — one card per first-class entity with live row counts.
 - **Table view** (`#/objects/<entity>`) — intrinsic columns, `belongsTo` chips, and a column per junction this entity participates in.
 - **Detail view** (`#/objects/<entity>/<id>`) — read mode by default; `Edit` flips cells into inputs (`Save` PATCHes, `Cancel` reverts).
-- **Data Model** (`#/settings/data-model`) — entity-level graph plus a side panel for adding / removing junction-table links between rows.
+- **Data Model** (inside **Database Settings**, v1.14+) — entity-level graph including the native `files`/`secrets` objects, with a per-entity editor. On a team cloud each table you own carries a **Share with team / Unshare** toggle. (Pre-1.14 this was a separate `#/settings/data-model` nav item; that hash still resolves for back-compat.)
 
 **Internal tables added on first open**
 
@@ -2112,18 +2124,22 @@ These tables are prefixed with `_lattice_gui_` and are hidden from `/api/entitie
 
 **HTTP surface** (all routes scoped to `http://127.0.0.1:<port>/api`):
 
-| Route                      | Method | Lattice call                  |
-| -------------------------- | ------ | ----------------------------- |
-| `/project`                 | GET    | (config + manifest summary)   |
-| `/entities`                | GET    | tables + `db.count` per table |
-| `/graph`                   | GET    | (schema graph for Data Model) |
-| `/tables/:table/rows`      | GET    | `db.query(table, …)`          |
-| `/tables/:table/rows`      | POST   | `db.insert(table, body)`      |
-| `/tables/:table/rows/:id`  | GET    | `db.get(table, id)`           |
-| `/tables/:table/rows/:id`  | PATCH  | `db.update(table, id, body)`  |
-| `/tables/:table/rows/:id`  | DELETE | `db.delete(table, id)`        |
-| `/tables/:junction/link`   | POST   | `db.link(junction, body)`     |
-| `/tables/:junction/unlink` | POST   | `db.unlink(junction, body)`   |
+| Route                          | Method | Lattice call                                                    |
+| ------------------------------ | ------ | --------------------------------------------------------------- |
+| `/project`                     | GET    | (config + manifest summary)                                     |
+| `/entities`                    | GET    | tables + `db.count` per table                                   |
+| `/graph`                       | GET    | (schema graph for Data Model)                                   |
+| `/tables/:table/rows`          | GET    | `db.query(table, …)`                                            |
+| `/tables/:table/rows`          | POST   | `db.insert(table, body)`                                        |
+| `/tables/:table/rows/:id`      | GET    | `db.get(table, id)`                                             |
+| `/tables/:table/rows/:id`      | PATCH  | `db.update(table, id, body)`                                    |
+| `/tables/:table/rows/:id`      | DELETE | `db.delete(table, id)`                                          |
+| `/tables/:junction/link`       | POST   | `db.link(junction, body)`                                       |
+| `/tables/:junction/unlink`     | POST   | `db.unlink(junction, body)`                                     |
+| `/schema/entities`             | POST   | create a new entity/table                                       |
+| `/schema/entities/:name/share` | POST   | share/unshare a table you own with the team (cloud, owner-only) |
+
+On a team cloud, `/entities` and `/graph` (and the queryable `/tables/*` allowlist) are filtered to the tables you own plus tables shared to the team — so the API surface matches exactly what the GUI shows; a table you can't see is not reachable. `/entities` rows carry `shared` / `ownedByMe` flags in that mode.
 
 The server only binds to `127.0.0.1` and has no authentication. See [SECURITY.md](./SECURITY.md) for the threat model — do not expose this port to a non-loopback interface.
 
@@ -2150,6 +2166,18 @@ registerNativeEntities(db);
 await db.init();
 ```
 
+`isNativeEntity(name)` / `NATIVE_ENTITY_NAMES` are the single source of truth for "is this table a framework-shipped native object?" — adding a key to `NATIVE_ENTITY_DEFS` flows everywhere automatically (table creation, GUI surfacing, recognition).
+
+**Adopting an existing `files`/`secrets` table (v1.14+).** If a database already has its own `files` or `secrets` table — possibly with a different/legacy column shape — `adoptNativeEntities(db)` (run after `init()`) labels that physical table as THE native object instead of duplicating it: it merges the native column superset non-destructively (`CREATE TABLE IF NOT EXISTS` + `ADD COLUMN IF NOT EXISTS`, never dropping data) and records the binding in an internal `__lattice_native_entities` registry. Legacy plaintext `secrets.value` rows stay readable (decrypt passes non-`enc:` values through) and new writes encrypt. `listNativeBindings(db)` reads the bindings. The GUI runs this automatically on every open and exposes the bindings at `GET /api/native-entities`.
+
+```ts
+import { adoptNativeEntities, listNativeBindings } from 'latticesql';
+
+await db.init();
+await adoptNativeEntities(db); // merge + label existing files/secrets as native
+const bindings = await listNativeBindings(db); // [{ entity, tableName, origin }]
+```
+
 **Machine-local user config at `~/.lattice/` (v1.12+).** A small set of files outside any Lattice DB so a user's identity, encrypted master key, saved cloud-DB credentials, and per-team bearer tokens survive switching projects:
 
 | File                            | Purpose                                                                                                  |
@@ -2220,9 +2248,19 @@ lattice teams join \
 
 The cloud rejects redemption if the caller's claimed email doesn't match the invitation's `invitee_email` (case-insensitive). Sharing an invite token in a public channel is therefore safe — only the addressee can redeem it.
 
-**Other subcommands** (`lattice teams help` for the full list): `list`, `members`, `leave`, `destroy`, `share`, `unshare`, `shared`, `sync`, `link`, `unlink`, `pull`, `push`, `status`.
+**Other subcommands** (`lattice teams help` for the full list): `list`, `members`, `leave`, `destroy`, `share`, `unshare`, `shared`, `sync`, `link`, `unlink`, `pull`, `push`, `status`, `dlq`.
+
+**Dead-letter queue (v1.15+).** A pulled change envelope that fails to apply (e.g. it arrived before the row/table it depends on), and any non-owner-overwrite divergence notice, lands in `__lattice_team_dlq`. Inspect and recover it instead of losing it behind the pull cursor:
+
+```bash
+lattice teams dlq list  --team <name>            # show entries (op, target, error)
+lattice teams dlq retry --team <name> [--id <id>] # replay; a late dependency now applies cleanly
+lattice teams dlq purge --team <name> [--id <id>] # discard without applying
+```
 
-**Same flows from the GUI.** The local `lattice gui` Project Config view drives the entire teams lifecycle — create / join, invite by email, share tables, link rows, see sync status. Identity (display name + email) comes from `~/.lattice/identity.json` and is prefilled in every modal.
+**Per-table ownership + opt-in sharing (v1.14+).** Team members share one physical Postgres, so visibility is enforced at the app layer via a `__lattice_object_owners` table: each table records its creator, and a user sees only the tables they own plus tables explicitly shared to the team. The native `files`/`secrets` objects are owned by the database creator and private by default. Sharing is an explicit, owner-only action (not a side effect of creating a table). The filter gates API access, not just the display.
+
+**Same flows from the GUI (v1.14+).** The local `lattice gui` drives the entire teams lifecycle from **Database Settings**: rename (owner-only), invite by email (owner-only), the inline Members list (the owner is always shown as `creator`; your own row offers Leave/Destroy; non-owners can't kick), share/unshare from the Data Model, and sync status. Member admin is resolved from `GET /api/dbconfig` against the active cloud DB, so it works even when the team cloud itself is the active database. Identity (display name + email) comes from `~/.lattice/identity.json` and is locked in the Join modal. Leaving a team removes the local config + credential and switches you to another database.
 
 **Joining via the GUI is one click (v1.13.7+).** When you click "Join via invite" and the redeem succeeds, the team's cloud URL is automatically saved as a switchable database credential and a sibling YAML config is written to your project directory. The new entry shows up in the database dropdown as `<team-name>.config`. Clicking it opens the SPA with the team's shared tables already populated — no YAML editing, no `db.define()` calls.
 
@@ -2593,14 +2631,40 @@ interface AutoUpdateResult {
 
 ## Telemetry
 
-`latticesql` installs and runs with **zero telemetry network calls**. No postinstall pings, no runtime beacons, no anonymous-ID files written to your home directory. The only outbound requests the package ever makes are the explicit, caller-invoked `checkForUpdate()` / `autoUpdate()` calls to `registry.npmjs.org` — and you only get those if you call them.
+`latticesql` includes [Scarf](https://scarf.sh) install analytics so we can understand how the package is used in the wild — what versions are running, on what platforms, at roughly what scale. This signal is what lets us prioritize fixes, deprecations, and new features against real usage instead of guesswork.
+
+**What is sent — once, at `npm install` time, by the `@scarf/scarf` postinstall hook:**
 
-To understand who's using the package we rely on two passive signals that require no instrumentation in your install or your runtime:
+- Package name + version (e.g. `latticesql@1.13.6`)
+- Node.js version, OS, CPU architecture
+- A coarse, non-identifying hash derived from the install host (Scarf's default — used for deduplication, not identification)
+- The public IP of the install request (visible to any HTTPS endpoint; not stored long-term by Scarf)
 
-- **A 1×1 tracking pixel** embedded at the bottom of this README, served by [Scarf](https://scarf.sh). It fires when this README is rendered (e.g. on the npmjs.com package page). It sees only what any HTTPS image request sees — the requester's user-agent and IP, which Scarf de-identifies into coarse geo/company aggregates. Block it with any standard ad-blocker, or use a privacy-focused npm UI that doesn't render images, and Scarf sees nothing.
-- **Public npm download counts**, queried by us from npm's own [downloads API](https://api.npmjs.org/downloads/range/last-month/latticesql). These are the same counts npmjs.com itself publishes — no per-user data, just aggregate package downloads.
+**What is NOT sent:**
+
+- No data from your application code, schemas, rows, or query strings
+- No environment variables, file paths, hostnames, or usernames
+- No runtime telemetry — `latticesql` makes zero outbound telemetry calls after install. The only network requests it makes at runtime are the explicit `checkForUpdate()` / `autoUpdate()` calls to `registry.npmjs.org`, which you opt into by calling them.
+
+**How to opt out** — any one of these suppresses the install ping:
+
+```bash
+# Per-install (recommended for CI):
+SCARF_ANALYTICS=false npm install latticesql
 
-Neither signal touches your code, your data, your environment, or your install pipeline. If your network blocks `static.scarf.sh`, the README still renders (image alt text is empty); installs and runtime behavior are identical.
+# Or, project-wide (add to .npmrc):
+scarf-analytics=false
+
+# Or, the cross-tool standard:
+DO_NOT_TRACK=1 npm install latticesql
+
+# Or, disable all postinstall scripts entirely:
+npm install latticesql --ignore-scripts
+```
+
+Opting out has no effect on functionality — the package works identically. The Scarf postinstall is a fire-and-forget HTTPS ping with a short timeout; even when enabled it cannot fail your install.
+
+See Scarf's own [privacy documentation](https://docs.scarf.sh) for the upstream policy.
 
 ---
 
@@ -2619,7 +2683,3 @@ See [CHANGELOG.md](./CHANGELOG.md) for the full history.
 ## License
 
 [Apache 2.0](./LICENSE) — includes explicit patent grant (Section 3).
-
-<!-- Scarf README pixel — see § Telemetry above for what it does and how to block it. -->
-
-![](https://static.scarf.sh/a.png?x-pxid=bcbfdaa1-ef11-455a-bcc8-3ec215709da4)