memhouse 0.4.3 → 0.7.0

package/{mem-house → memhouse}/per-member/INSTALL.md

@@ -50,7 +50,9 @@ Two properties that make the block safe to paste anywhere:
   otherwise build Merge rooms pointing at `default` that return zero rows forever, with no
   error at any point.
 
-Measured: 17 statements, run over HTTP with no database selected, 17 succeeded, and the
+Measured: 18 statements (the 17 objects plus a leading `SET
+allow_experimental_full_text_index = 1`), run over HTTP with no database selected, 18
+succeeded on both 26.7.2.59 and 25.11.9.34, and the
 Merge rooms came out bound to `Merge('mem', '^sessions_')`.
 
 ## Option 2 — give the installer admin, it runs the SQL
@@ -78,31 +80,51 @@ who plays admin and how the handle is chosen.
 ## The grant set — two statements per room, and the split is the point
 
 ```sql
-GRANT ALL    ON mem.sessions_polat TO polat;
+GRANT SELECT, INSERT, ALTER UPDATE, ALTER DELETE, ALTER ADD COLUMN, OPTIMIZE
+             ON mem.sessions_polat TO polat;
 GRANT SELECT ON mem.sessions_polat TO polat WITH GRANT OPTION;
 ```
 
-**`ALL`, not re-grantable.** The member owns their room outright — `DROP` and `TRUNCATE`
-included, because it is their memory to destroy. It also covers the mutation privileges
-the shipper needs without naming them, which matters: the shipper clears a session's rows
-before re-inserting, and which of `ALTER UPDATE` / `ALTER DELETE` a server demands varies
-by version (`DELETE FROM` is a lightweight delete implemented as
-`ALTER TABLE … UPDATE _row_exists = 0`, so 25.11 wants one where 26.7 wanted the other).
+**Exactly what the shipper uses, not `ALL`.** `ALL` expands to 45 privileges on 26.7 and
+one of them is `CREATE TABLE` **on the member's own room name** — so the member owns the
+NAME, not just the data, and can do this:
 
-**`SELECT`, re-grantable.** A share is read-only **by construction**, not by convention.
-`GRANT ALL … WITH GRANT OPTION` expands to 45 privileges on 26.7 — `DROP TABLE`,
-`TRUNCATE`, `CREATE ROW POLICY`, `SYSTEM DROP REPLICA` among them — every one of which a
-member could then hand to a colleague while meaning "let them read my sessions".
+```sql
+DROP TABLE messages_polat;
+CREATE TABLE messages_polat AS all_messages ENGINE = Merge('mem','^messages_');
+```
+
+`all_messages` is `Merge(mem,'^messages_')`, so it then contains a Merge over its own
+namespace and **every other member's rows are counted twice in the team room**. Measured:
+a house reading alice 6030 / bob 2401 / carol 12 became bob 4802 / carol 24, with no error
+on either ClickHouse version. Confidentiality survives — the Merge still narrows by grants,
+so nothing new becomes readable — but a team-wide number is what that room is for.
+
+`ALTER UPDATE` and `ALTER DELETE` are both named because `DELETE FROM` is a lightweight
+delete implemented as `ALTER TABLE … UPDATE _row_exists = 0`, and which of the two a server
+demands varies by version (25.11 wants one where 26.7 wanted the other). `ALTER ADD COLUMN`
+is for `ensureSchema`'s rollout. Replacing a room is the admin's job, not the member's.
 
-Measured on 26.7.2:
+**`SELECT`, re-grantable.** A share is read-only **by construction**, not by convention:
+the member can hand a colleague `SELECT` and nothing else, because they hold nothing else
+to hand over.
+
+Measured on 26.7.2 and 25.11.9:
 
 ```
 polat grants SELECT to bob      ok
 polat grants DROP TABLE to bob  497 Not enough privileges
-polat drops their own room      ok
+polat drops their own room      497 Not enough privileges
+polat creates any table         497 Not enough privileges
+polat installs, ships, resets   ok
 bob ends up with                GRANT SELECT ON mem.sessions_polat
 ```
 
+One definition, in `rooms.js` as `MEMBER_PRIVS`, used by both `provision.js` and
+`install --print-sql`. They drifted once — the first was narrowed and the second went on
+emitting `GRANT ALL` for a release, so the attack above stayed reachable through the path
+this document calls the common case.
+
 Never `ON mem.*`. A member who can read `mem.*` can read every other member's rooms, and
 then this is a shared house with longer table names.
 
@@ -181,3 +203,26 @@ failed install leaves a config behind that the next command reads as truth.
 `memhouse service install` inlines the same values into the unit file, because a service
 must not depend on a shell-quoted file it does not parse the same way. That is a second
 copy, also 0600, removed by `memhouse service uninstall`.
+
+## `--adopt-user` needs house admin — it is not the new-machine path
+
+`--adopt-user` is read only on the `--admin-user` branch, so it provisions a member and
+requires admin on the house. Passing it without `--admin-user` used to be ignored silently;
+it is refused now.
+
+The actual "same person, new machine" path needs no admin at all — you already have a
+member credential, so just use it:
+
+    memhouse install --url https://… --user <member> --password …
+
+That finds the existing rooms and writes the config. `--adopt-user` is for the case where
+an admin is *creating or re-attaching* a member and wants the existing password verified
+before anything is written.
+
+## Offboarding, from the member's side
+
+`DROP USER <member>` leaves their rooms and revokes everything (verified: no orphan grants
+survive). From that member's machine every command then fails with `AUTHENTICATION_FAILED`
+and advises reinstalling — which cannot work, and is indistinguishable from a wrong
+password. There is no signal that says "you were offboarded"; ClickHouse does not
+distinguish the two either. Worth knowing before you use it on someone.

package/{mem-house → memhouse}/per-member/SCHEMA.md

@@ -71,3 +71,50 @@ which is what it was always supposed to mean.
 
 - the kernel capability that provisions a member
 - member removal: drop the three rooms, revoke, decide what happens to rooms shared outward
+
+## What a member can still learn about the others
+
+Isolation is a grant that is absent, so no member can read another's rows — verified by
+trying every read and write against another member's rooms, plus `system.parts`,
+`system.query_log`, `system.processes` and the rest, all of which refuse. Two things do
+leak, both structural rather than bugs in the code, and neither is fixed by tightening a
+grant:
+
+**The roster.** A member's handle is part of their table name, and ClickHouse distinguishes
+"forbidden" from "absent": `SELECT count() FROM messages_bob` returns `Code: 497
+ACCESS_DENIED` (HTTP 500) if bob exists and `Code: 60 UNKNOWN_TABLE` (HTTP 404) if he does
+not. So any member can enumerate the membership of the house by guessing handles.
+`system.tables` correctly hides the other rooms; this reopens it. `EXISTS TABLE` does not
+leak — it answers 497 either way — so it is specifically the natural probe that talks. If
+the membership of a house is itself sensitive, the per-member layout is the wrong shape for
+it.
+
+**Volume.** `system.tables.total_rows` and `total_bytes` are readable for the Merge rooms,
+and a Merge room spans every member:
+
+    name            total_rows   total_bytes
+    all_messages    87           42455        <- the whole house
+    messages_alice  33           25070        <- what alice can actually read
+
+So a member can see the house's combined row count and byte volume, and by polling it, when
+other members are shipping. Withholding `SELECT` on the Merge rooms is not the fix — it
+makes the team room deny rather than narrow, which is the property those rooms exist for.
+
+## Why members are not granted ALL on their own rooms
+
+`GRANT ALL ON <db>.messages_<m>` expands to 45 privileges on 26.7, and one of them is
+`CREATE TABLE` **on that name**. A member would then own the name rather than the data:
+
+    DROP TABLE messages_alice;
+    CREATE TABLE messages_alice AS all_messages ENGINE = Merge('<db>','^messages_');
+
+`all_messages` is `Merge(db,'^messages_')`, so it now contains a Merge over its own
+namespace and every other member's rows are counted twice in the team room — measured, a
+house reading alice 6030 / bob 2401 / carol 12 became bob 4802 / carol 24, with no error.
+Confidentiality survives (the Merge still narrows by grants) but integrity does not, and a
+team-wide number is what the room is for. It is the same failure recorded above under the
+`sessions_v` rename, reached on purpose instead of by accident.
+
+Members therefore get exactly what the shipper uses — `SELECT, INSERT, ALTER UPDATE, ALTER
+DELETE, ALTER ADD COLUMN, OPTIMIZE` — and nothing that defines an object. Replacing a room
+is the admin's job.

package/memhouse/per-member/provision.js

@@ -0,0 +1,265 @@
+#!/usr/bin/env node
+// mem — provision one member's rooms and grants. Idempotent; also the schema-rollout hook.
+//
+//   provision.js --member <name> [--merge] [--owner-grants]
+//
+// Run as the OWNER. Steps, all IF NOT EXISTS / re-runnable:
+//   1. create the member's three rooms from schema-member.sql.tpl
+//   2. grant the member their own three rooms, TWO statements each: MEMBER_PRIVS (not
+//      re-grantable), then `SELECT WITH GRANT OPTION`. The split is the point —
+//      MEMBER_PRIVS is exactly what the shipper uses and nothing that DEFINES an object,
+//      and attaching grant-option to `SELECT` alone makes a share read-only by
+//      construction. It is deliberately NOT `ALL`: that includes CREATE TABLE on the
+//      member's own room name, which lets them replace the room with a Merge over every
+//      member's and double the others' rows in the team room. See rooms.js.
+//
+//      THREE ROOMS, not four objects: the session rollup is a saved query over these
+//      same rooms, not a stored view, so it needs no object and no grant of its own.
+//   3. --merge: create/refresh the three Merge rooms, borrowing this member's columns
+//   4. grant the member SELECT on whichever Merge rooms exist — a Merge reduces to the
+//      rooms the caller can already read, so this is what makes the team room fail
+//      CLOSED rather than deny outright
+//
+// Grants are explicit, per room, and NEVER `ON mem.*` — a member who can read the whole
+// house can read every other member's rooms, which would make this a shared house with
+// longer table names. No wildcards are used anywhere; the only pattern in the design is
+// the Merge regex, anchored on a fixed room type.
+//
+// Env: MEM_URL / MEM_USER / MEM_PASSWORD / MEM_DB, falling back to MEMHOUSE_*. URL and
+// USER are REQUIRED — see the note at cfg. MEM_DB defaults to 'mem'.
+
+const fs = require('fs');
+const crypto = require('crypto');
+const path = require('path');
+// Named, not thrown as a raw MODULE_NOT_FOUND with a require stack. This runs as a
+// SUBPROCESS of `memhouse install`, after the admin path has already created a ClickHouse
+// user — so its failure mode is a half-provisioned house, and "Cannot find module" plus a
+// stack trace is the least useful thing to print at that moment. Seen for real in a
+// checkout where `npm install` had not been run.
+let createClient, ClickHouseLogLevel;
+try { ({ createClient, ClickHouseLogLevel } = require('@clickhouse/client')); }
+catch {
+  console.error("provision.js: dependency '@clickhouse/client' is not installed.");
+  console.error(`  From a checkout:      npm install --prefix ${path.join(__dirname, '..', '..')}`);
+  console.error(`  From an npm install:  ${require('./rooms').installCommand()}`);
+  process.exit(2);
+}
+const { ROOM_TYPES, mergeRooms, assertUsableMember, MEMBER_PRIVS, MEMBER_PROFILE, MEMBER_PROFILE_SETTINGS } = require('./rooms');
+
+const args = process.argv.slice(2);
+const flag = (n) => args.includes(`--${n}`);
+const opt = (n, d = null) => { const i = args.indexOf(`--${n}`); return i >= 0 ? args[i + 1] : d; };
+
+// Defaults MUST match what the shipper and CLI use, or an operator who overrides only
+// the thing that differs — a password, say — silently provisions rooms in a house the
+// product never reads, or fails to authenticate as a user that does not exist.
+//
+// Which is why there is no default URL or user any more, here either. This file CREATES
+// USERS AND GRANTS; pointing it at a guessed http://localhost:8123 as memhouse_root aims
+// the most privileged operation in the product at whatever house happens to be listening.
+// Observed: running it with no env at all made an authentication attempt against the
+// pilot's own ClickHouse.
+const cfg = {
+  url: process.env.MEM_URL || process.env.MEMHOUSE_URL,
+  username: process.env.MEM_USER || process.env.MEMHOUSE_USER,
+  password: process.env.MEM_PASSWORD || process.env.MEMHOUSE_PASSWORD || '',
+  database: process.env.MEM_DB || process.env.MEMHOUSE_DB || 'mem',
+};
+if (!cfg.url || !cfg.username) {
+  console.error('provision.js: no house given. Set MEM_URL and MEM_USER (or MEMHOUSE_URL/MEMHOUSE_USER).');
+  console.error('  This creates users and grants — it will not guess http://localhost:8123 as memhouse_root.');
+  process.exit(2);
+}
+
+// Statements are split on ';' at end of line — the templates contain no ';' inside a
+// statement body, and keeping the splitter dumb keeps the templates readable.
+function statements(sql) {
+  return sql
+    .split(/;\s*$/m)
+    .map((s) => s.replace(/^\s*--.*$/gm, '').trim())
+    .filter(Boolean);
+}
+
+/** Which of the three Merge rooms actually exist — a member may be provisioned first. */
+async function mergeRoomsPresent(client, database) {
+  const names = Object.values(mergeRooms());
+  const rs = await client.query({
+    query: `SELECT name FROM system.tables WHERE database = {db:String} AND name IN ({names:Array(String)}) ORDER BY name`,
+    query_params: { db: database, names },
+    format: 'JSONEachRow',
+  });
+  return (await rs.json()).map((r) => r.name);
+}
+
+async function main() {
+  const member = opt('member');
+  if (!member) { console.error('usage: provision.js --member <name> [--merge]'); process.exit(2); }
+  assertUsableMember(member);
+
+  const here = __dirname;
+
+  // Create the house with a client that has NOT selected it — on a fresh server the
+  // database does not exist yet, and selecting it fails before it can be created.
+  // See the note in shipper/ship.js: the driver's ERROR-level dump buries every
+  // refusal this file prints. MEMHOUSE_DEBUG=1 restores it.
+  const quiet = { level: process.env.MEMHOUSE_DEBUG ? ClickHouseLogLevel.DEBUG : ClickHouseLogLevel.OFF };
+  const bootstrap = createClient({ ...cfg, database: '', log: quiet });
+  await bootstrap.command({ query: `CREATE DATABASE IF NOT EXISTS ${cfg.database}` });
+  await bootstrap.close();
+
+  console.log(`[mem] provisioning in ${cfg.url} database '${cfg.database}' as '${cfg.username}'`);
+  const client = createClient({ ...cfg, log: quiet, clickhouse_settings: { async_insert: 0 } });
+
+  // 0. the member themselves.
+  //
+  // This file never created the ClickHouse user, so the path `memhouse install` prints and
+  // INSTALL.md repeats — `provision.js --member <name> --merge` — created three rooms and
+  // then died on `There is no role \`<name>\` in \`user directories\``, leaving orphan rooms
+  // that nothing removes and that the --merge step then folded into all_sessions. It also
+  // ignored --member-password. The documented second-member path did not work at all.
+  const existing = await client.query({
+    query: `SELECT name FROM system.users WHERE name = {n:String}`,
+    query_params: { n: member }, format: 'JSONEachRow',
+  });
+  if ((await existing.json()).length === 0) {
+    const pw = opt('member-password') || crypto.randomBytes(24).toString('base64url');
+    await client.command({ query: `CREATE USER ${member} IDENTIFIED BY '${pw.replace(/'/g, "\\'")}'` });
+    console.log(`[mem] created ClickHouse user '${member}'`);
+    if (!opt('member-password')) {
+      console.log(`[mem] password for '${member}': ${pw}`);
+      console.log('[mem] shown once — hand it over, or pass --member-password next time');
+    }
+    console.log(`[mem] they finish with: memhouse install --url ${cfg.url} --db ${cfg.database} --user ${member} --password '…'`);
+  } else {
+    console.log(`[mem] ClickHouse user '${member}' already exists — provisioning rooms only`);
+  }
+
+  // 1. rooms
+  const tpl = fs.readFileSync(path.join(here, 'schema-member.sql.tpl'), 'utf-8');
+  const roomSql = statements(tpl.replaceAll('{{MEMBER}}', member));
+  for (const q of roomSql) {
+    // allow_experimental_full_text_index: a no-op on 26.x, required on 25.x for the
+    // messages text indexes.
+    await client.command({ query: q, clickhouse_settings: { allow_experimental_full_text_index: 1 } });
+  }
+  // CREATE TABLE IF NOT EXISTS is a no-op on an existing room, so re-running provision.js
+  // over a room that has DRIFTED left it lossy while printing "rooms ready". The owner's
+  // route has to heal as well as create — it is the one route that always holds the rights.
+  {
+    const { templateColumns } = require('../shipper/ship');
+    const want = templateColumns(tpl);
+    for (const ty of ROOM_TYPES) {
+      const room = `${ty}_${member}`;
+      const rs = await client.query({
+        query: 'SELECT name FROM system.columns WHERE database = {d:String} AND table = {n:String}',
+        query_params: { d: cfg.database, n: room }, format: 'JSONEachRow',
+      });
+      const have = new Set((await rs.json()).map((r) => r.name));
+      if (!have.size) continue;
+      for (const c of (want[ty] || [])) {
+        if (have.has(c.name)) continue;
+        await client.command({
+          query: `ALTER TABLE ${cfg.database}.${room} ADD COLUMN IF NOT EXISTS ${c.name} ${c.type}`,
+          clickhouse_settings: { allow_experimental_full_text_index: 1 },
+        });
+        console.log(`[mem] added missing column ${room}.${c.name}`);
+      }
+    }
+  }
+  console.log(`[mem] rooms ready for '${member}': ${ROOM_TYPES.map((t) => `${t}_${member}`).join(', ')}`);
+
+  // 2. grants — two statements per room, and the split is the point.
+  //
+  // ALL, NOT re-grantable: the member owns their room outright, DROP and TRUNCATE
+  // included, because it is their memory to destroy. It also covers the mutation
+  // privileges the shipper needs without naming them — the shipper clears a session's
+  // rows before re-inserting, and which of ALTER UPDATE / ALTER DELETE a server demands
+  // varies by version (`DELETE FROM` is a lightweight delete, implemented as
+  // `ALTER TABLE … UPDATE _row_exists = 0`, so 25.11 wants ALTER UPDATE where 26.7 wanted
+  // ALTER DELETE). Granting one and not the other produces a pass that fails elsewhere.
+  //
+  // SELECT, re-grantable: a share is READ-ONLY BY CONSTRUCTION rather than by convention.
+  // `GRANT ALL … WITH GRANT OPTION` expands to 45 privileges on 26.7 — DROP TABLE,
+  // TRUNCATE, CREATE ROW POLICY, SYSTEM DROP REPLICA among them — and every one of those
+  // would become something a member could hand to a colleague while meaning "let them
+  // read my sessions". Measured: with this split, `GRANT SELECT … TO bob` succeeds and
+  // `GRANT DROP TABLE … TO bob` is refused 497.
+  // NOT `GRANT ALL`. On 26.7 that expands to 45 privileges including CREATE TABLE **on
+  // the member's own room name** — which means a member owns the NAME, not just the data,
+  // and can put any engine behind it. Measured on both versions:
+  //
+  //     DROP TABLE messages_alice;                                      -- allowed
+  //     CREATE TABLE messages_alice AS all_messages
+  //       ENGINE = Merge('<db>','^messages_');                          -- allowed
+  //
+  // `all_messages` is Merge(db,'^messages_'), so it then contains a Merge over its own
+  // namespace and every OTHER member's rows are counted twice in the team room: a house
+  // reading alice 6030 / bob 2401 / carol 12 became bob 4802 / carol 24, silently, no
+  // error. Confidentiality survives — the Merge still narrows by grants, so alice reads
+  // nothing new — but integrity does not, and a team-wide number is the whole point of
+  // the room. SCHEMA.md already records the same failure reached by accident; this is the
+  // same failure reachable on purpose by any member.
+  //
+  // So: the privileges the shipper actually uses, and nothing that lets a member define
+  // an object. ALTER UPDATE and ALTER DELETE both, because `DELETE FROM` is a lightweight
+  // delete implemented as `ALTER TABLE … UPDATE _row_exists = 0` and which of the two a
+  // server demands varies by version (25.11 wants UPDATE where 26.7 wanted DELETE).
+  // ALTER ADD COLUMN for ensureSchema's rollout. No CREATE TABLE, no DROP TABLE, no
+  // TRUNCATE: the admin who provisioned the room is the one who can replace it.
+  //
+  // SELECT is re-grantable so a share is READ-ONLY BY CONSTRUCTION rather than by
+  // convention — `GRANT SELECT … TO bob` succeeds, `GRANT DROP TABLE … TO bob` is 497.
+  for (const t of ROOM_TYPES) {
+    const room = `${cfg.database}.${t}_${member}`;
+    await client.command({ query: `GRANT ${MEMBER_PRIVS} ON ${room} TO ${member}` });
+    await client.command({ query: `GRANT SELECT ON ${room} TO ${member} WITH GRANT OPTION` });
+  }
+  console.log(`[mem] granted ${MEMBER_PRIVS} on 3 rooms to '${member}'; SELECT is the only re-grantable one`);
+
+  // 2b. A settings profile with CEILINGS, not just defaults.
+  //
+  // Every isolation test passed on confidentiality and none existed for availability: a
+  // member could `SETTINGS max_memory_usage=100000000000`, `max_execution_time=0` and
+  // `max_threads=64` on a shared house, and take the server down for everyone. The
+  // constraint form (`MAX`) is what makes it a ceiling — a plain default is advisory and a
+  // member simply overrides it, which is what they were doing.
+  //
+  // Generous on purpose: a full re-ship of a large house is a big INSERT, and the point is
+  // to stop one member exhausting the box, not to make honest work fail.
+  try {
+    await client.command({ query: `CREATE SETTINGS PROFILE OR REPLACE ${MEMBER_PROFILE} SETTINGS ${MEMBER_PROFILE_SETTINGS}` });
+    await client.command({ query: `ALTER USER ${member} SETTINGS PROFILE '${MEMBER_PROFILE}'` });
+    console.log(`[mem] settings profile '${MEMBER_PROFILE}' applied to '${member}' (memory, time and thread ceilings)`);
+  } catch (e) {
+    // A server where the admin cannot create profiles still gets a working member; say so
+    // rather than failing the provision.
+    console.log(`[mem] note: could not apply the '${MEMBER_PROFILE}' settings profile — ${e.message}`);
+    console.log('[mem] the member works, but nothing bounds their query resources on this server');
+  }
+
+  // 3. Merge rooms
+  if (flag('merge')) {
+    const mtpl = fs.readFileSync(path.join(here, 'schema-merge.sql.tpl'), 'utf-8');
+    for (const q of statements(mtpl.replaceAll('{{TEMPLATE_MEMBER}}', member))) {
+      await client.command({ query: q });
+    }
+    console.log('[mem] merge rooms ready: all_sessions, all_messages, all_tool_calls');
+  }
+
+  // 4. Merge-room grants. Broad on purpose, and safe for the reason the whole layout
+  // rests on: a Merge table reduces to the underlying rooms the CALLER holds grants for.
+  // Measured on 25.11 — bob with SELECT on all_messages and nothing on messages_alice
+  // reads his own row and none of alice's, with `_table` showing only messages_bob, and
+  // no error. Withholding this grant does not make anything safer; it makes the team
+  // room deny outright instead of failing closed, which is a different and worse thing.
+  const merged = await mergeRoomsPresent(client, cfg.database);
+  for (const room of merged) {
+    await client.command({ query: `GRANT SELECT ON ${cfg.database}.${room} TO ${member}` });
+  }
+  if (merged.length) console.log(`[mem] granted SELECT on ${merged.join(', ')} to '${member}'`);
+  else console.log('[mem] no merge rooms yet — run once with --merge to create them');
+
+  await client.close();
+}
+
+main().catch((e) => { console.error(`[mem] provision failed: ${e.message}`); process.exit(1); });

package/memhouse/per-member/rooms.js

@@ -0,0 +1,235 @@
+// Room-name resolution.
+//
+// Every member owns their rooms, named TYPE-FIRST: `sessions_<member>`,
+// `messages_<member>`, `tool_calls_<member>`. Type-first is what lets the Merge rooms
+// anchor on a fixed room type (`^sessions_`) and never match themselves.
+//
+// THIS IS THE ONLY LAYOUT. There was a shared one — three rooms named `sessions`,
+// `messages`, `tool_calls`, with row policies narrowing each caller to their own rows —
+// and it is gone. A shared read is a Merge room plus a GRANT, which is strictly less
+// machinery than a policy that has to be right on every table and every read path; and
+// isolation by absent grant fails closed, where a row policy fails open the moment one is
+// missing.
+//
+// The member is never supplied by the caller — it is read back from the server with
+// currentUser(), the same value the rooms' user_id column is stamped with. A client that
+// could name its own member could write into someone else's rooms.
+//
+// `sessions_v` IS A SAVED QUERY, NOT A ROOM. It was briefly a stored view, which cost a
+// name inside the `^sessions_` namespace the Merge rooms select on (silently merged into
+// `all_sessions`, doubling every count), a fourth grant per member, and a fourth object to
+// provision, roll forward and drop. A saved query is substituted with the caller's own
+// room names and runs under the caller's credential, so it inherits their grants and
+// raises no view-ownership question at all.
+
+const ROOM_TYPES = ['sessions', 'messages', 'tool_calls'];
+
+/**
+ * What a member is granted on their own rooms. ONE definition, because there are two paths
+ * that provision a house — provision.js and `install --print-sql` — and when only the first
+ * was narrowed the second went on emitting `GRANT ALL` for a release. GRANT ALL includes
+ * CREATE TABLE **on the member's own room name**, so a member owns the name rather than the
+ * data and can replace the room with a Merge over everyone's, doubling other members' rows
+ * in the team room.
+ *
+ * ALTER UPDATE and ALTER DELETE both: `DELETE FROM` is a lightweight delete implemented as
+ * `ALTER TABLE … UPDATE _row_exists = 0`, and which of the two a server demands varies by
+ * version. ALTER ADD COLUMN for ensureSchema's rollout. Nothing that defines an object.
+ */
+const MEMBER_PRIVS = 'SELECT, INSERT, ALTER UPDATE, ALTER DELETE, ALTER ADD COLUMN, OPTIMIZE';
+
+/**
+ * Resource ceilings for a member, as a settings profile.
+ *
+ * Here for the same reason MEMBER_PRIVS is here: there are two paths that provision a
+ * house — provision.js and `install --print-sql` — and a change made to one of them and
+ * not the other has now happened eight times. Anything a member is GIVEN belongs in this
+ * file, so both paths read the same definition.
+ *
+ * MIN..MAX, not CONST and not MAX alone.
+ *
+ * A plain default is advisory — a member writes `SETTINGS max_memory_usage = …` on their
+ * query and overrides it. MAX alone is not enough either: in ClickHouse **0 means
+ * unlimited** for these, and 0 satisfies any MAX, so `SETTINGS max_memory_usage = 0`
+ * removed the ceiling entirely. MIN 1 closes that.
+ *
+ * CONST closes it too and was tried first — but CONST refuses EVERY change, including the
+ * server's own. `rawQuery` in memhouse/server/queries.js pins max_result_rows and
+ * max_execution_time to protect the dashboard from an unbounded query, and under CONST
+ * those pins were refused with Code 452, so /api/query returned an error for every input
+ * on any house provisioned after that change. A ceiling has to stop a member RAISING the
+ * limit while still letting anyone LOWER it.
+ *
+ * max_memory_usage is per QUERY; max_memory_usage_for_user bounds the member across
+ * concurrent queries, without which N parallel queries x the per-query ceiling is
+ * unbounded.
+ *
+ * Limits are generous on purpose: the point is to stop one member exhausting a shared
+ * server, not to make an honest full re-ship fail — a 20M-row scan runs inside them.
+ *
+ * KNOWN GAP, deliberately not closed here: ALTER UPDATE, ALTER DELETE and OPTIMIZE are in
+ * MEMBER_PRIVS and execute in the background merge pool, where these per-query settings do
+ * not apply. A member looping `OPTIMIZE … FINAL` on a large room can still load the box.
+ * Bounding that needs server-level merge-pool configuration, which is the operator's, not
+ * something a per-member profile can express.
+ */
+/**
+ * The global-install command that will actually work HERE.
+ *
+ * Every site that printed `npm install -g memhouse --allow-scripts=better-sqlite3` printed
+ * a line that fails with EACCES on any distro-packaged Node, because the global prefix is
+ * root-owned — measured on a clean Ubuntu machine, exit 243, including as step 1 of
+ * `prompt --install`, which advertises itself as rendered for this machine. The README
+ * learned this; eight code sites had not.
+ *
+ * `sudo` is right for exactly one of the two causes and makes the other worse, and what
+ * tells them apart is who owns the prefix — so look, rather than guess.
+ */
+function installCommand() {
+  const base = 'npm install -g memhouse --allow-scripts=better-sqlite3';
+  try {
+    const { execFileSync } = require('child_process');
+    const prefix = execFileSync('npm', ['prefix', '-g'], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    const st = require('fs').statSync(prefix);
+    if (st.uid !== process.getuid()) return `sudo ${base}`;
+  } catch { /* npm not on PATH, or an unreadable prefix: fall through to the plain form */ }
+  return base;
+}
+
+const MEMBER_PROFILE = 'memhouse_member';
+const MEMBER_PROFILE_SETTINGS = [
+  'max_memory_usage = 8000000000 MIN 1 MAX 8000000000',
+  'max_memory_usage_for_user = 16000000000 MIN 1 MAX 16000000000',
+  'max_execution_time = 600 MIN 1 MAX 600',
+  'max_threads = 16 MIN 1 MAX 16',
+  'max_result_rows = 10000000 MIN 1 MAX 10000000',
+].join(', ');
+
+// ClickHouse usernames are permissive; room names are not. Refuse anything that would
+// need quoting or could change how a Merge regex or a name-splitter reads.
+function assertUsableMember(member) {
+  if (typeof member !== 'string' || !/^[A-Za-z][A-Za-z0-9_]*$/.test(member)) {
+    throw new Error(`cannot build room names for user '${member}': expected [A-Za-z][A-Za-z0-9_]*`);
+  }
+  // The reservation lives HERE, not only in the CLI, because provision.js is the admin
+  // entry point INSTALL.md sends you to for a second member — and it went as far as
+  // creating sessions_root/messages_root/tool_calls_root before dying on the grant,
+  // leaving three orphan rooms nothing removes. Case-insensitive: Root and ROOT are the
+  // same account. `default` is deliberately NOT reserved — a poor member name, but a real
+  // one that existing houses are built on.
+  if (member.toLowerCase() === 'root') {
+    throw new Error("'root' cannot be a member: it is a container artefact, not a person");
+  }
+}
+
+/**
+ * The session rollup, as SQL text rather than a name.
+ *
+ * Two properties are load bearing: the join is a LEFT JOIN, so a session with no messages
+ * still appears with zero aggregates instead of vanishing from every count; and
+ * `join_use_nulls = 1` makes the unmatched message columns NULL so `coalesce` yields true
+ * zeros rather than counting the placeholder row.
+ *
+ * BOTH ARE NOW CARRIED BY THE TEXT ITSELF — `FINAL` on each room and a trailing
+ * `SETTINGS join_use_nulls = 1`. It used to depend on the caller passing `final=1` and
+ * `join_use_nulls=1`, on the belief that a subquery cannot carry its own SETTINGS. It can
+ * (verified on 26.7 and 25.11), and the belief was expensive: every consumer that forgot
+ * the settings silently counted each message once per undeleted ReplacingMergeTree
+ * version. Measured right after a `ship --full` — 2x, and 3x three ships later. It does
+ * not self-heal; the error grows with each pass until a merge happens to collapse the
+ * parts. `memhouse sessions-query > q.sql` lost the warning entirely, because it was
+ * printed on stderr as a SQL comment that never reached the SQL.
+ *
+ * Passing final=1 as well is harmless, so READ_SETTINGS stays as it is for direct room
+ * reads, which still need it.
+ */
+function sessionsRollup({ sessions, messages }) {
+  return `(
+    SELECT
+        s.session_id AS session_id,
+        any(s.source) AS source,
+        any(s.host) AS host,
+        any(s.name) AS name,
+        any(s.mode) AS mode,
+        any(s.folder) AS folder,
+        any(s.project) AS project,
+        any(s.git_branch) AS git_branch,
+        s.user_id AS user_id,
+        any(s.created_at) AS created_at,
+        any(s.last_updated_at) AS last_updated_at,
+        min(m.ts) AS started,
+        max(m.ts) AS ended,
+        coalesce(dateDiff('second', min(m.ts), max(m.ts)), 0) AS duration_sec,
+        count(m.seq) AS total_msgs,
+        countIf(m.role = 'user') AS user_msgs,
+        countIf(m.role = 'assistant') AS assistant_msgs,
+        countIf(m.is_subagent) AS subagent_msgs,
+        groupUniqArrayIf(m.model, m.model NOT IN ('', '<synthetic>')) AS models,
+        coalesce(sum(m.input_tokens), 0) AS input_tokens,
+        coalesce(sum(m.output_tokens), 0) AS output_tokens,
+        coalesce(sum(m.cache_read_tokens), 0) AS cache_read_tokens,
+        coalesce(sum(m.cache_write_tokens), 0) AS cache_write_tokens,
+        coalesce(sumIf(length(m.text), m.role = 'user'), 0) AS user_chars,
+        coalesce(sumIf(length(m.text), m.role = 'assistant'), 0) AS assistant_chars,
+        coalesce(substring(argMinIf(m.text, m.seq, m.role = 'user' AND m.text != ''), 1, 200), '') AS first_prompt
+    FROM ${sessions} AS s FINAL
+    LEFT JOIN ${messages} AS m FINAL ON m.session_id = s.session_id AND m.user_id = s.user_id
+    GROUP BY s.session_id, s.user_id
+    SETTINGS join_use_nulls = 1
+  )`;
+}
+
+/**
+ * The settings every read needs. `final` collapses ReplacingMergeTree versions;
+ * `join_use_nulls` is what the rollup's coalesce depends on.
+ */
+const READ_SETTINGS = { final: 1, join_use_nulls: 1 };
+
+/**
+ * Names, given the member the server reported. Shared by every caller so the two
+ * transports in the tree (@clickhouse/client and the CLI's raw fetch) cannot drift into
+ * two different naming rules.
+ *
+ * `sessions_v` is the rollup as SQL text, usable in the same `FROM ... AS c` position a
+ * view name would occupy — which is what lets the read layer treat it as just another
+ * resolved name.
+ */
+function roomNames(member, user = member) {
+  assertUsableMember(member);
+  const out = { member, user };
+  for (const t of ROOM_TYPES) out[t] = `${t}_${member}`;
+  out.sessions_v = sessionsRollup(out);
+  return out;
+}
+
+async function currentUser(client) {
+  const rs = await client.query({ query: 'SELECT currentUser() AS u', format: 'JSONEachRow' });
+  const rows = await rs.json();
+  const u = rows[0] && rows[0].u;
+  if (!u) throw new Error('could not determine currentUser()');
+  return u;
+}
+
+/**
+ * Resolve the rooms for whoever this client is connected as.
+ * Returns { sessions, messages, tool_calls, sessions_v, member, user }.
+ *
+ * `user` is the identity the server reports. Writers need the value itself, not just the
+ * name it produces — see ship.js's delete, which must BIND the user rather than call
+ * currentUser() inside a mutation, where it is not evaluated in the caller's context.
+ */
+async function resolveRooms(client) {
+  const user = await currentUser(client);
+  return roomNames(user, user);
+}
+
+/** The three Merge rooms — team-wide read paths, owner-managed. */
+function mergeRooms() {
+  return { sessions: 'all_sessions', messages: 'all_messages', tool_calls: 'all_tool_calls' };
+}
+
+module.exports = {
+  MEMBER_PRIVS, installCommand, MEMBER_PROFILE, MEMBER_PROFILE_SETTINGS,
+  ROOM_TYPES, READ_SETTINGS, assertUsableMember,
+  sessionsRollup, roomNames, currentUser, resolveRooms, mergeRooms,
+};