latticesql 2.1.1 → 2.2.0

package/dist/index.cjs

@@ -4374,6 +4374,12 @@ function buildAdapter(dbPath, options) {
   return new SQLiteAdapter(sqlitePath, adapterOpts);
 }
 var NOT_DELETED2 = "(deleted_at IS NULL OR deleted_at = '')";
+function rowAclVisibleExists(teamExpr, tableExpr, pkExpr) {
+  return `EXISTS (SELECT 1 FROM "__lattice_row_acl" la WHERE la."team_id" = ${teamExpr} AND la."table_name" = ${tableExpr} AND la."pk" = ${pkExpr} AND (la."owner_user_id" = ? OR la."visibility" = 'everyone' OR (la."visibility" = 'custom' AND EXISTS (SELECT 1 FROM "__lattice_row_grants" lg WHERE lg."team_id" = la."team_id" AND lg."table_name" = la."table_name" AND lg."pk" = la."pk" AND lg."grantee_user_id" = ?))))`;
+}
+function rowAclAbsent(teamExpr, tableExpr, pkExpr) {
+  return `NOT EXISTS (SELECT 1 FROM "__lattice_row_acl" la2 WHERE la2."team_id" = ${teamExpr} AND la2."table_name" = ${tableExpr} AND la2."pk" = ${pkExpr})`;
+}
 var Lattice = class _Lattice {
   _adapter;
   _changelogService;
@@ -5473,6 +5479,131 @@ var Lattice = class _Lattice {
     const rows = await allAsyncOrSync(this._adapter, sql, params);
     return this._decryptRows(table, rows);
   }
+  /**
+   * Row-level-security list read for Lattice Teams (2.2). Returns only the
+   * rows of `table` that `userId` may see in team `teamId`, evaluated
+   * entirely in SQL (indexed, bounded — never "load every row then filter
+   * in JS"). A row is visible iff it has a `__lattice_row_acl` entry owned by
+   * the user or marked 'everyone', or a 'custom' entry with a matching
+   * `__lattice_row_grants` row, OR it has no ACL entry at all and the caller
+   * passes `noAclVisible` (the table default is 'everyone', or the user owns
+   * the table — the pre-2.2 / never-narrowed case). Soft-deleted rows are
+   * excluded by default; results reuse the same decrypt path as `query()`.
+   *
+   * The ACL predicate joins on the table's primary-key column cast to TEXT
+   * (ACL pks are stored as TEXT), so it is correct regardless of the user
+   * table's pk type and works on both SQLite and Postgres. The teams layer's
+   * `listVisibleRows` (src/teams/row-access.ts) is the intended caller.
+   */
+  async queryVisible(table, opts) {
+    const notInit = this._notInitError();
+    if (notInit) return notInit;
+    this._assertIdent(table);
+    if (opts.orderBy) this._assertIdent(table, opts.orderBy);
+    const cols = this._ensureColumnCache(table);
+    const pkCol = this._schema.getPrimaryKey(table)[0] ?? "id";
+    let softDelete = "";
+    if (cols.has("deleted_at") && opts.deleted !== "any") {
+      softDelete = opts.deleted === "only" ? `t."deleted_at" IS NOT NULL AND ` : `t."deleted_at" IS NULL AND `;
+    }
+    const pkExpr = `CAST(t."${pkCol}" AS TEXT)`;
+    let sql = `SELECT t.* FROM "${table}" t WHERE ${softDelete}(${rowAclVisibleExists("?", "?", pkExpr)}`;
+    const params = [opts.teamId, table, opts.userId, opts.userId];
+    if (opts.noAclVisible) {
+      sql += ` OR ${rowAclAbsent("?", "?", pkExpr)}`;
+      params.push(opts.teamId, table);
+    }
+    sql += `)`;
+    if (opts.orderBy && cols.has(opts.orderBy)) {
+      const dir = opts.orderDir === "desc" ? "DESC" : "ASC";
+      sql += ` ORDER BY t."${opts.orderBy}" ${dir}`;
+    }
+    if (opts.limit !== void 0 && Number.isFinite(opts.limit)) {
+      sql += ` LIMIT ${Math.trunc(opts.limit).toString()}`;
+    }
+    if (opts.offset !== void 0 && Number.isFinite(opts.offset)) {
+      if (opts.limit === void 0 && this.getDialect() === "sqlite") sql += " LIMIT -1";
+      sql += ` OFFSET ${Math.trunc(opts.offset).toString()}`;
+    }
+    const rows = await allAsyncOrSync(this._adapter, sql, params);
+    return this._decryptRows(table, rows);
+  }
+  /**
+   * Visible-row counts for MANY tables in a single round-trip, using the same
+   * ACL predicate as {@link queryVisible} — so dashboard tiles agree with what
+   * the rows view lists and a physical count never reveals the existence or
+   * volume of rows the user can't see. One aggregated
+   * `SELECT (SELECT COUNT(*) …) AS c0, …` statement (no per-table fan-out, so
+   * a session pooler with few slots survives concurrent refreshes), capped at
+   * 50 tables per pass; overflow is logged and skipped (no silent truncation)
+   * and those tables count as absent — the caller renders "—". Soft-deleted
+   * rows are excluded wherever the table carries `deleted_at`, matching the
+   * default rows view.
+   */
+  async countVisibleMany(specs, opts) {
+    const out = /* @__PURE__ */ new Map();
+    const notInit = this._notInitError();
+    if (notInit) return notInit;
+    if (specs.length === 0) return out;
+    const VISIBLE_COUNT_CAP = 50;
+    let bounded = specs;
+    if (bounded.length > VISIBLE_COUNT_CAP) {
+      const dropped = bounded.length - VISIBLE_COUNT_CAP;
+      console.warn(
+        `[lattice] visible-count pass capped at ${String(VISIBLE_COUNT_CAP)} tables; ${String(dropped)} table(s) report no count this pass`
+      );
+      bounded = bounded.slice(0, VISIBLE_COUNT_CAP);
+    }
+    const selects = [];
+    const params = [];
+    for (const [i, spec] of bounded.entries()) {
+      this._assertIdent(spec.table);
+      const cols = this._ensureColumnCache(spec.table);
+      const pkCol = this._schema.getPrimaryKey(spec.table)[0] ?? "id";
+      const softDelete = cols.has("deleted_at") ? `t."deleted_at" IS NULL AND ` : "";
+      const pkExpr = `CAST(t."${pkCol}" AS TEXT)`;
+      let predicate = rowAclVisibleExists("?", "?", pkExpr);
+      params.push(opts.teamId, spec.table, opts.userId, opts.userId);
+      if (spec.noAclVisible) {
+        predicate += ` OR ${rowAclAbsent("?", "?", pkExpr)}`;
+        params.push(opts.teamId, spec.table);
+      }
+      selects.push(
+        `(SELECT COUNT(*) FROM "${spec.table}" t WHERE ${softDelete}(${predicate})) AS c${String(i)}`
+      );
+    }
+    const row = await getAsyncOrSync(this._adapter, `SELECT ${selects.join(", ")}`, params);
+    if (!row) return out;
+    for (const [i, spec] of bounded.entries()) {
+      const raw = row[`c${String(i)}`];
+      const n = typeof raw === "bigint" ? Number(raw) : Number(raw);
+      if (Number.isFinite(n) && n >= 0) out.set(spec.table, n);
+    }
+    return out;
+  }
+  /**
+   * Hosted-sync change-log pull, filtered per recipient for 2.2 row-level
+   * security (the hosted server's sole enforcement mechanism). Returns
+   * `__lattice_change_log` rows with seq > `since` for team `teamId` that
+   * `userId` is permitted to receive:
+   *   - targeted envelopes (`recipient_user_id = userId`), plus
+   *   - broadcast envelopes (`recipient_user_id IS NULL`) that are either
+   *     table-level (`pk IS NULL` — schema / unshare, delivered to all) or
+   *     whose row is currently visible to the user via `__lattice_row_acl` /
+   *     `__lattice_row_grants` (or has no ACL entry and the table defaults to
+   *     'everyone').
+   * Ordered by seq, capped at `limit`. Raw SQL because the predicate needs
+   * OR / EXISTS that the `query()` API can't express; bounded by the seq
+   * window and indexed ACL point-lookups. Mirrors {@link queryVisible}'s
+   * visibility logic so a member never pulls the bytes of a row they can't see.
+   */
+  async listChangesForRecipient(teamId, since, userId, limit) {
+    const notInit = this._notInitError();
+    if (notInit) return notInit;
+    const sql = `SELECT cl.* FROM "__lattice_change_log" cl WHERE cl."team_id" = ? AND cl."seq" > ? AND (cl."recipient_user_id" = ? OR (cl."recipient_user_id" IS NULL AND (cl."pk" IS NULL OR ${rowAclVisibleExists('cl."team_id"', 'cl."table_name"', 'cl."pk"')} OR (${rowAclAbsent('cl."team_id"', 'cl."table_name"', 'cl."pk"')} AND EXISTS (SELECT 1 FROM "__lattice_shared_objects" so WHERE so."team_id" = cl."team_id" AND so."table_name" = cl."table_name" AND so."deleted_at" IS NULL AND so."default_row_visibility" = 'everyone'))))) ORDER BY cl."seq" ASC LIMIT ${Math.trunc(limit).toString()}`;
+    const params = [teamId, since, userId, userId, userId];
+    return allAsyncOrSync(this._adapter, sql, params);
+  }
   async count(table, opts = {}) {
     const notInit = this._notInitError();
     if (notInit) return notInit;
@@ -7194,7 +7325,13 @@ var CLOUD_INTERNAL_TABLE_DEFS = {
       // Client-generated idempotency key for offline replay: a queued edit
       // carries a stable edit_id, so re-sending it after a reconnect is a
       // no-op rather than a duplicate write. Nullable + additive.
-      edit_id: "TEXT"
+      edit_id: "TEXT",
+      // Per-recipient targeting for 2.2 hard row-level sync. NULL =
+      // broadcast (delivered to every member, then filtered at pull time
+      // against __lattice_row_acl); non-null = targeted to exactly this
+      // user (the grant / revoke / delete fan-out). Nullable + additive,
+      // same precedent as client_ts / edit_id.
+      recipient_user_id: "TEXT"
     },
     render: () => "",
     outputFile: ".lattice-teams/change-log.md"
@@ -7210,6 +7347,44 @@ var CLOUD_INTERNAL_TABLE_DEFS = {
     primaryKey: ["team_id", "table_name", "pk"],
     render: () => "",
     outputFile: ".lattice-teams/row-links.md"
+  },
+  // Per-row access control for a team cloud (2.2 row-level permissions).
+  // Mirrors __lattice_object_owners at row granularity: each shared row
+  // has an owner (its creator) and a visibility. Enforcement is at the
+  // application layer (see src/teams/row-access.ts) — every member shares
+  // the same physical DB, so a row a user can't see must be filtered out
+  // before its bytes reach them. Kept out-of-band (never injected into
+  // user tables) so the user's own schema stays untouched.
+  __lattice_row_acl: {
+    columns: {
+      team_id: "TEXT NOT NULL",
+      table_name: "TEXT NOT NULL",
+      pk: "TEXT NOT NULL",
+      owner_user_id: "TEXT NOT NULL",
+      // 'private' = owner only · 'everyone' = all team members ·
+      // 'custom' = the explicit grant list in __lattice_row_grants.
+      visibility: "TEXT NOT NULL CHECK (visibility IN ('private', 'everyone', 'custom'))",
+      created_at: "TEXT NOT NULL",
+      updated_at: "TEXT NOT NULL"
+    },
+    primaryKey: ["team_id", "table_name", "pk"],
+    render: () => "",
+    outputFile: ".lattice-teams/row-acl.md"
+  },
+  // Explicit per-row grant list, consulted only when the owning row's
+  // __lattice_row_acl.visibility = 'custom'. One row per (row, grantee).
+  __lattice_row_grants: {
+    columns: {
+      team_id: "TEXT NOT NULL",
+      table_name: "TEXT NOT NULL",
+      pk: "TEXT NOT NULL",
+      grantee_user_id: "TEXT NOT NULL",
+      granted_by_user_id: "TEXT NOT NULL",
+      granted_at: "TEXT NOT NULL"
+    },
+    primaryKey: ["team_id", "table_name", "pk", "grantee_user_id"],
+    render: () => "",
+    outputFile: ".lattice-teams/row-grants.md"
   }
 };
 var LOCAL_INTERNAL_TABLE_DEFS = {
@@ -7310,6 +7485,48 @@ async function installCloudInternalTriggers(db) {
   };
   await db.migrate([migration]);
 }
+async function installRowPermsSchema(db) {
+  const migrations = [
+    {
+      // 01 — per-table default visibility for newly-created rows. Born
+      // 'private' unless the table owner opts the table into 'everyone';
+      // the backfill (06) flips already-shared tables to preserve pre-2.2
+      // visibility. No IF NOT EXISTS: the version guard runs this exactly
+      // once, which is what SQLite's ADD COLUMN needs (it has no
+      // IF NOT EXISTS form).
+      version: "internal:row-perms:01-default-row-visibility:v1",
+      sql: `ALTER TABLE "__lattice_shared_objects" ADD COLUMN "default_row_visibility" TEXT NOT NULL DEFAULT 'private' CHECK ("default_row_visibility" IN ('private', 'everyone'))`
+    },
+    {
+      // 02-05 — indexes. One CREATE INDEX per migration (single-statement
+      // for the SQLite path). IF NOT EXISTS is valid in both dialects.
+      version: "internal:row-perms:02-idx-change-log-team-seq:v1",
+      sql: `CREATE INDEX IF NOT EXISTS "idx_lattice_change_log_team_seq" ON "__lattice_change_log" ("team_id", "seq")`
+    },
+    {
+      version: "internal:row-perms:03-idx-change-log-team-recipient-seq:v1",
+      sql: `CREATE INDEX IF NOT EXISTS "idx_lattice_change_log_team_recipient_seq" ON "__lattice_change_log" ("team_id", "recipient_user_id", "seq")`
+    },
+    {
+      version: "internal:row-perms:04-idx-change-log-team-table-pk:v1",
+      sql: `CREATE INDEX IF NOT EXISTS "idx_lattice_change_log_team_table_pk" ON "__lattice_change_log" ("team_id", "table_name", "pk")`
+    },
+    {
+      version: "internal:row-perms:05-idx-row-grants-grantee:v1",
+      sql: `CREATE INDEX IF NOT EXISTS "idx_lattice_row_grants_grantee" ON "__lattice_row_grants" ("team_id", "grantee_user_id", "table_name", "pk")`
+    },
+    {
+      // 06 — upgrade backfill. Every already-shared table defaults to
+      // 'everyone' so pre-2.2 rows stay visible to all members (nothing
+      // disappears on upgrade). Pre-2.2 rows have no __lattice_row_acl
+      // entry; resolveRowAcl() folds in this table default, so they read
+      // as 'everyone' until an owner narrows an individual row. Runs once.
+      version: "internal:row-perms:06-backfill-shared-defaults:v1",
+      sql: `UPDATE "__lattice_shared_objects" SET "default_row_visibility" = 'everyone' WHERE "deleted_at" IS NULL`
+    }
+  ];
+  await db.migrate(migrations);
+}
 
 // src/teams/schema-spec.ts
 function renderColumnType(spec, dialect) {
@@ -7665,7 +7882,8 @@ async function appendChangeEnvelope(db, entry) {
     owner_user_id: entry.owner_user_id ?? null,
     created_at: now,
     client_ts: entry.client_ts ?? now,
-    edit_id: entry.edit_id ?? null
+    edit_id: entry.edit_id ?? null,
+    recipient_user_id: entry.recipient_user_id ?? null
   });
   return seq;
 }
@@ -7705,7 +7923,14 @@ async function shareObject(db, teamId, createdByUserId, table, spec) {
       created_by_user_id: createdByUserId,
       created_at: prior?.created_at ?? now,
       updated_at: now,
-      deleted_at: null
+      deleted_at: null,
+      // 2.2: a freshly-shared table defaults to 'everyone' so the existing
+      // "share a table → every member sees its rows" contract is preserved.
+      // The owner can narrow the table default (or individual rows) afterward.
+      // Re-share (the branch above) intentionally omits this so an owner's
+      // earlier choice survives a schema bump (the upsert only sets the
+      // columns it lists).
+      default_row_visibility: "everyone"
     });
   }
   await applySchemaSpec(db, table, outSpec);
@@ -7799,88 +8024,26 @@ async function destroyTeamDirect(db) {
   }
   await db.delete("__lattice_team_identity", "singleton");
 }
-async function redeemInviteDirect(cloudUrl, inviteToken, email, name) {
-  if (!isPostgresUrl(cloudUrl)) {
-    throw new Error(
-      `redeemInviteDirect: cloudUrl must be a postgres:// URL (got ${cloudUrl.slice(0, 12)}\u2026)`
-    );
-  }
-  const db = new Lattice(cloudUrl);
-  try {
-    await db.init();
-    for (const [table, def] of Object.entries(CLOUD_INTERNAL_TABLE_DEFS)) {
-      await db.defineLate(table, def);
-    }
-    await installCloudInternalTriggers(db);
-    const invites = await db.query("__lattice_invitations", {
-      filters: [
-        { col: "token_hash", op: "eq", val: hashToken(inviteToken) },
-        { col: "redeemed_at", op: "isNull" }
-      ],
-      limit: 1
-    });
-    const invite = invites[0];
-    if (!invite) {
-      throw new Error("Invitation invalid or already used");
-    }
-    if (invite.expires_at && new Date(invite.expires_at).getTime() < Date.now()) {
-      throw new Error("Invitation expired");
-    }
-    if (invite.invitee_email && invite.invitee_email.toLowerCase() !== email.toLowerCase()) {
-      throw new Error("Invitation is addressed to a different email");
-    }
-    const team = await db.get("__lattice_team", invite.team_id);
-    if (!team || team.deleted_at) {
-      throw new Error("Team no longer exists");
-    }
-    const now = (/* @__PURE__ */ new Date()).toISOString();
-    const userId = await db.insert("__lattice_users", {
-      email,
-      name,
-      created_at: now,
-      updated_at: now
-    });
-    await db.insert("__lattice_team_members", {
-      team_id: invite.team_id,
-      user_id: userId,
-      role: "member",
-      joined_at: now
-    });
-    const { raw, hash } = generateToken();
-    await db.insert("__lattice_api_tokens", {
-      user_id: userId,
-      token_hash: hash,
-      name: `invited:${team.name}`,
-      created_at: now
-    });
-    await db.update("__lattice_invitations", invite.id, {
-      redeemed_at: now,
-      redeemed_by_user_id: userId
-    });
-    return {
-      user: { id: userId, email, name },
-      raw_token: raw,
-      team: { id: team.id, name: team.name }
-    };
-  } finally {
-    try {
-      db.close();
-    } catch {
-    }
-  }
-}
+var directDeprecationWarned = false;
 async function openCloud(cloudUrl) {
   if (!isPostgresUrl(cloudUrl)) {
     throw new Error(
       `direct-ops: cloudUrl must be a postgres:// URL (got ${cloudUrl.slice(0, 12)}\u2026)`
     );
   }
+  if (!directDeprecationWarned) {
+    directDeprecationWarned = true;
+    console.warn(
+      "[teams] Direct postgres:// team-cloud connection is deprecated and does NOT enforce 2.2 row-level security. Migrate to a hosted Lattice Teams server."
+    );
+  }
   const db = new Lattice(cloudUrl);
   await db.init();
   for (const [table, def] of Object.entries(CLOUD_INTERNAL_TABLE_DEFS)) {
     await db.defineLate(table, def);
   }
   await installCloudInternalTriggers(db);
+  await installRowPermsSchema(db);
   return db;
 }
 function closeQuiet(db) {
@@ -7991,6 +8154,7 @@ async function unlinkRowDirect(local, cloudUrl, teamId, table, pk) {
 }
 
 // src/teams/client.ts
+var DIRECT_CLOUD_DEPRECATION_MESSAGE = "Direct postgres:// team-cloud connections are deprecated and do not support row-level security. Create or join a workspace through a hosted Lattice Teams server (an http(s):// URL) instead. Existing direct connections continue to work but should be migrated.";
 var TeamsClient = class {
   constructor(local) {
     this.local = local;
@@ -8023,6 +8187,9 @@ var TeamsClient = class {
    * members join via `redeemInvite`). Returns the new user + bearer
    * token + team summary so the caller can immediately save a
    * connection.
+   *
+   * @param teamName The workspace display name (stored as `team_name` for
+   * backward compatibility — a cloud IS a workspace with members).
    */
   async register(cloudUrl, email, name, teamName) {
     return this.fetchUnauthed(cloudUrl, "POST", "/api/auth/register", {
@@ -8033,7 +8200,7 @@ var TeamsClient = class {
   }
   async redeemInvite(cloudUrl, inviteToken, email, name) {
     if (isPostgresUrl(cloudUrl)) {
-      return redeemInviteDirect(cloudUrl, inviteToken, email, name);
+      throw new Error(DIRECT_CLOUD_DEPRECATION_MESSAGE);
     }
     return this.fetchUnauthed(cloudUrl, "POST", "/api/auth/redeem-invite", {
       invite_token: inviteToken,
@@ -8044,9 +8211,11 @@ var TeamsClient = class {
   // ── High-level orchestration (v1.13+) ───────────────────────────────────
   // Wraps the multi-step flows the GUI's Database panel + library
   // consumers both need: connecting to an existing cloud DB (with
-  // optional team join), and upgrading a non-team cloud into a team
-  // cloud. The HTTP routes in src/gui/dbconfig-routes.ts are thin
-  // shells over these methods.
+  // optional team join), and initializing a fresh cloud DB's owner so
+  // its members + per-table sharing surface exists. A cloud workspace IS
+  // a workspace with members — there is no separate "team" to convert to.
+  // The HTTP routes in src/gui/dbconfig-routes.ts are thin shells over
+  // these methods.
   /**
    * Connect a local project to an existing cloud DB by URL. Probes
    * the target for team status first; if it's a teams DB, the caller
@@ -8095,15 +8264,18 @@ var TeamsClient = class {
     return { probe };
   }
   /**
-   * Upgrade an already-connected cloud DB to a team DB. Two paths
-   * depending on the cloud URL's scheme:
+   * Initialize a fresh cloud DB's owner: register the first member (who
+   * becomes owner) so the cloud's members + per-table sharing surface
+   * exists. This is NOT a "convert a cloud into a team" step — a cloud
+   * workspace IS a workspace with members; this just bootstraps the owner
+   * the first time a cloud is opened. The hosted server path is the only
+   * supported one:
    *
    *   - `http(s)://…` — POST to the cloud's `/api/auth/register` endpoint
-   *     (`lattice serve --team-cloud` is fronting the Postgres).
-   *   - `postgres(ql)://…` — drive the same INSERT sequence directly
-   *     against the cloud Postgres via {@link registerDirectViaPostgres}.
-   *     The HTTP path can't be used here because the browser's Fetch
-   *     API refuses URLs with embedded credentials.
+   *     (a hosted `lattice serve` teams server is fronting the Postgres).
+   *   - `postgres(ql)://…` — rejected: direct postgres:// owner bootstrap
+   *     is deprecated. Row-level security is enforced by the hosted server,
+   *     so it is the only supported connection method for new workspaces.
    *
    * On success writes the bearer token to `~/.lattice/keys/<label>.token`
    * **and** persists the local `__lattice_team_connections` row so the
@@ -8113,8 +8285,11 @@ var TeamsClient = class {
    * the token file, leaving GUI authenticated calls with no
    * `cloud_url` + `my_user_id` + `api_token_encrypted` row to read.
    */
-  async upgradeToTeamCloud(opts) {
-    const reg = isPostgresUrl(opts.cloudUrl) ? await registerDirectViaPostgres(opts.cloudUrl, opts.email, opts.displayName, opts.teamName) : await this.register(opts.cloudUrl, opts.email, opts.displayName, opts.teamName);
+  async registerCloudOwner(opts) {
+    if (isPostgresUrl(opts.cloudUrl)) {
+      throw new Error(DIRECT_CLOUD_DEPRECATION_MESSAGE);
+    }
+    const reg = await this.register(opts.cloudUrl, opts.email, opts.displayName, opts.teamName);
     writeToken(opts.label, reg.raw_token);
     await this.saveConnection({
       team_id: reg.team.id,
@@ -8147,7 +8322,7 @@ var TeamsClient = class {
     }
     try {
       const displayName = opts.displayName?.trim() ? opts.displayName : opts.email;
-      await this.upgradeToTeamCloud({
+      await this.registerCloudOwner({
         label: opts.label,
         cloudUrl: opts.cloudUrl,
         teamName: opts.workspaceName,

package/dist/index.d.cts

@@ -1969,6 +1969,76 @@ declare class Lattice {
      */
     search(table: string, query: string, opts?: SearchOptions): Promise<SearchResult[]>;
     query(table: string, opts?: QueryOptions): Promise<Row[]>;
+    /**
+     * Row-level-security list read for Lattice Teams (2.2). Returns only the
+     * rows of `table` that `userId` may see in team `teamId`, evaluated
+     * entirely in SQL (indexed, bounded — never "load every row then filter
+     * in JS"). A row is visible iff it has a `__lattice_row_acl` entry owned by
+     * the user or marked 'everyone', or a 'custom' entry with a matching
+     * `__lattice_row_grants` row, OR it has no ACL entry at all and the caller
+     * passes `noAclVisible` (the table default is 'everyone', or the user owns
+     * the table — the pre-2.2 / never-narrowed case). Soft-deleted rows are
+     * excluded by default; results reuse the same decrypt path as `query()`.
+     *
+     * The ACL predicate joins on the table's primary-key column cast to TEXT
+     * (ACL pks are stored as TEXT), so it is correct regardless of the user
+     * table's pk type and works on both SQLite and Postgres. The teams layer's
+     * `listVisibleRows` (src/teams/row-access.ts) is the intended caller.
+     */
+    queryVisible(table: string, opts: {
+        teamId: string;
+        userId: string;
+        /**
+         * Whether rows with NO `__lattice_row_acl` entry are visible to this
+         * user — true when the table default is 'everyone' OR the user owns the
+         * table (the pre-2.2 / never-narrowed case). Resolved by the teams layer
+         * (`listVisibleRows`); defaults to false, i.e. only rows with an explicit
+         * ACL entry granting access are returned.
+         */
+        noAclVisible?: boolean;
+        /** Soft-delete handling: 'exclude' (default), 'only' (trash), 'any'. */
+        deleted?: 'exclude' | 'only' | 'any';
+        limit?: number;
+        offset?: number;
+        orderBy?: string;
+        orderDir?: 'asc' | 'desc';
+    }): Promise<Row[]>;
+    /**
+     * Visible-row counts for MANY tables in a single round-trip, using the same
+     * ACL predicate as {@link queryVisible} — so dashboard tiles agree with what
+     * the rows view lists and a physical count never reveals the existence or
+     * volume of rows the user can't see. One aggregated
+     * `SELECT (SELECT COUNT(*) …) AS c0, …` statement (no per-table fan-out, so
+     * a session pooler with few slots survives concurrent refreshes), capped at
+     * 50 tables per pass; overflow is logged and skipped (no silent truncation)
+     * and those tables count as absent — the caller renders "—". Soft-deleted
+     * rows are excluded wherever the table carries `deleted_at`, matching the
+     * default rows view.
+     */
+    countVisibleMany(specs: {
+        table: string;
+        noAclVisible: boolean;
+    }[], opts: {
+        teamId: string;
+        userId: string;
+    }): Promise<Map<string, number>>;
+    /**
+     * Hosted-sync change-log pull, filtered per recipient for 2.2 row-level
+     * security (the hosted server's sole enforcement mechanism). Returns
+     * `__lattice_change_log` rows with seq > `since` for team `teamId` that
+     * `userId` is permitted to receive:
+     *   - targeted envelopes (`recipient_user_id = userId`), plus
+     *   - broadcast envelopes (`recipient_user_id IS NULL`) that are either
+     *     table-level (`pk IS NULL` — schema / unshare, delivered to all) or
+     *     whose row is currently visible to the user via `__lattice_row_acl` /
+     *     `__lattice_row_grants` (or has no ACL entry and the table defaults to
+     *     'everyone').
+     * Ordered by seq, capped at `limit`. Raw SQL because the predicate needs
+     * OR / EXISTS that the `query()` API can't express; bounded by the seq
+     * window and indexed ACL point-lookups. Mirrors {@link queryVisible}'s
+     * visibility logic so a member never pulls the bytes of a row they can't see.
+     */
+    listChangesForRecipient(teamId: string, since: number, userId: string, limit: number): Promise<Row[]>;
     count(table: string, opts?: CountOptions): Promise<number>;
     render(outputDir: string): Promise<RenderResult>;
     sync(outputDir: string): Promise<SyncResult>;
@@ -3722,6 +3792,9 @@ declare class TeamsClient {
      * members join via `redeemInvite`). Returns the new user + bearer
      * token + team summary so the caller can immediately save a
      * connection.
+     *
+     * @param teamName The workspace display name (stored as `team_name` for
+     * backward compatibility — a cloud IS a workspace with members).
      */
     register(cloudUrl: string, email: string, name: string, teamName: string): Promise<RegisterResponse>;
     redeemInvite(cloudUrl: string, inviteToken: string, email: string, name: string): Promise<RedeemResponse>;
@@ -3753,15 +3826,18 @@ declare class TeamsClient {
         };
     }>;
     /**
-     * Upgrade an already-connected cloud DB to a team DB. Two paths
-     * depending on the cloud URL's scheme:
+     * Initialize a fresh cloud DB's owner: register the first member (who
+     * becomes owner) so the cloud's members + per-table sharing surface
+     * exists. This is NOT a "convert a cloud into a team" step — a cloud
+     * workspace IS a workspace with members; this just bootstraps the owner
+     * the first time a cloud is opened. The hosted server path is the only
+     * supported one:
      *
      *   - `http(s)://…` — POST to the cloud's `/api/auth/register` endpoint
-     *     (`lattice serve --team-cloud` is fronting the Postgres).
-     *   - `postgres(ql)://…` — drive the same INSERT sequence directly
-     *     against the cloud Postgres via {@link registerDirectViaPostgres}.
-     *     The HTTP path can't be used here because the browser's Fetch
-     *     API refuses URLs with embedded credentials.
+     *     (a hosted `lattice serve` teams server is fronting the Postgres).
+     *   - `postgres(ql)://…` — rejected: direct postgres:// owner bootstrap
+     *     is deprecated. Row-level security is enforced by the hosted server,
+     *     so it is the only supported connection method for new workspaces.
      *
      * On success writes the bearer token to `~/.lattice/keys/<label>.token`
      * **and** persists the local `__lattice_team_connections` row so the
@@ -3771,9 +3847,10 @@ declare class TeamsClient {
      * the token file, leaving GUI authenticated calls with no
      * `cloud_url` + `my_user_id` + `api_token_encrypted` row to read.
      */
-    upgradeToTeamCloud(opts: {
+    registerCloudOwner(opts: {
         label: string;
         cloudUrl: string;
+        /** Workspace display name (stored as `team_name` for backward compatibility). */
         teamName: string;
         email: string;
         displayName: string;
@@ -4113,9 +4190,13 @@ declare function isPostgresUrl(url: string): boolean;
  *   - Refuses if any non-deleted user already exists on the cloud.
  *   - Refuses if the `__lattice_team_identity` singleton already exists.
  *
- * On success returns the same shape the HTTP route returns so the
- * caller (`TeamsClient.upgradeToTeamCloud`) can use either path
- * interchangeably.
+ * On success returns the same shape the HTTP route returns so a
+ * direct-postgres register can mirror the hosted register path.
+ *
+ * @deprecated Since 2.2 — new direct registrations are rejected (a direct
+ * connection bypasses row-level security). Retained only for the
+ * grandfathered existing-connection path; will be removed in 3.0. Create or
+ * join new workspaces through a hosted Teams server (an `http(s)://` URL).
  */
 declare function registerDirectViaPostgres(cloudUrl: string, email: string, name: string, teamName: string): Promise<DirectRegisterResult>;