memhouse 0.7.1 → 0.8.0

package/memhouse/house/house.js

@@ -0,0 +1,165 @@
+// The house.
+//
+// A house is a ClickHouse DATABASE — any database, named whatever its people name it
+// (`polat`, `team_a`, even `default`). Its rooms are three plain tables: `sessions`,
+// `messages`, `tool_calls`. Everyone in the house writes into the SAME tables, each with
+// their own credential, and two columns say who and where every row came from:
+//
+//   user_id  String MATERIALIZED currentUser()   — stamped by the server, unforgeable by
+//                                                  clients (async_insert is pinned to 0
+//                                                  on the user so the stamp cannot be
+//                                                  skipped)
+//   host     LowCardinality(String)              — the machine's fingerprint, minted once
+//                                                  per install (../host.js)
+//
+// That pair IS the provenance model. Alice and Bob point their shippers at `team_a` and
+// both write; `WHERE user_id = 'alice'` is one person, `WHERE host = '…'` is one machine.
+// The model is collaborative — housemates trust each other with the house — and the
+// boundary between houses is the database: joining someone's ClickHouse takes a database
+// and a credential (`GRANT ALL ON team_a.* TO alice`), nothing else, because ALL on your
+// own database reaches nothing outside it.
+//
+// THIS REPLACES THE PER-MEMBER LAYOUT. Rooms were `sessions_<member>` with per-member
+// grants, Merge rooms for team reads, and isolation between members of one database.
+// All of it is gone: suffixed names made every client resolve its room names first (and
+// `FROM messages` a documented trap), the Merge rooms existed only to undo the
+// splitting, and per-member isolation inside a shared house solved an adversarial
+// problem the product does not have. Separate houses isolate; one house shares.
+//
+// `sessions_v` IS A SAVED QUERY, NOT AN OBJECT — substituted into the same `FROM … AS c`
+// position a view name would occupy, running under the caller's own credential. It was
+// briefly a stored view; that cost an object to provision and grant, and a name for the
+// old Merge selectors to swallow.
+
+const ROOM_TYPES = ['sessions', 'messages', 'tool_calls'];
+
+// The one server-side setting a member carries, applied directly on the user with
+// ADD SETTING (bare `ALTER USER … SETTINGS` REPLACES the user's whole list — measured, it
+// wiped an operator-set ceiling; ADD SETTING merges and upserts). There is no settings
+// profile: the shared object detached members on replace and its server-global name made
+// two houses on one server rewrite each other's.
+//
+// The pin is correctness, not policy. `user_id MATERIALIZED currentUser()` is computed
+// during the INSERT, and an ASYNC insert flushes outside that context — measured on
+// 25.11.9.34, `async_insert=1` stores user_id as the EMPTY STRING while a sync insert
+// stamps correctly. The shipper always passes async_insert=0; the pin guards every OTHER
+// holder of the credential. CONST refuses the override; a client that never mentions the
+// setting is held at 0 and its insert lands stamped.
+const MEMBER_PIN = 'async_insert = 0 CONST';
+
+/**
+ * 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. `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;
+}
+
+// Identifier check for anything we splice into DDL unquoted — house (database) names and
+// user names. Refuse what would need quoting rather than quote it: a name a person cannot
+// type bare into their own SQL is a name they will get wrong. `default` is deliberately
+// ALLOWED as a house name — a stock container's default database is a real place to keep
+// a house, and the pilot may pick user 'alice' with house 'default'. Only the names that
+// are not a database at all are refused.
+const RESERVED_DBS = new Set(['system', 'information_schema']);
+function assertUsableName(name, what = 'name') {
+  if (typeof name !== 'string' || !/^[A-Za-z][A-Za-z0-9_]*$/.test(name)) {
+    throw new Error(`'${name}' cannot be a ${what} — expected [A-Za-z][A-Za-z0-9_]*`);
+  }
+  if (RESERVED_DBS.has(name.toLowerCase())) {
+    throw new Error(`'${name}' cannot be a ${what} — it is ClickHouse's own`);
+  }
+}
+
+/**
+ * The session rollup as SQL text, usable in the same `FROM ... AS c` position a view name
+ * would occupy. Groups by (session_id, user_id): two housemates' rows never merge, even
+ * on a colliding session_id.
+ */
+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 };
+
+/**
+ * Room names. They are constants now — `sessions`, `messages`, `tool_calls`, resolved by
+ * the connection's database rather than by who is asking — but the shape survives from
+ * the per-member layout so every consumer keeps addressing rooms the same way, and
+ * `user` still carries the server-reported identity: writers need the VALUE, not 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.
+ */
+function roomNames(user) {
+  const out = { member: user, user };
+  for (const t of ROOM_TYPES) out[t] = t;
+  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. */
+async function resolveRooms(client) {
+  return roomNames(await currentUser(client));
+}
+
+module.exports = {
+  ROOM_TYPES, READ_SETTINGS, MEMBER_PIN,
+  installCommand, assertUsableName,
+  sessionsRollup, roomNames, currentUser, resolveRooms,
+};

package/memhouse/{per-member/schema-member.sql.tpl → house/schema.sql.tpl}

@@ -1,16 +1,13 @@
--- mem — one member's rooms. Applied per member — {{MEMBER}} is the ClickHouse username.
---
--- Room naming is TYPE-FIRST (sessions_<m>, not <m>_sessions) so the Merge rooms
--- can anchor on a fixed room type and never match themselves.
---
--- user_id MATERIALIZED currentUser() is retained even though the room names the member:
--- it keeps provenance across a share and keeps the Merge rooms meaningful. Writers must
--- use async_insert=0 or the stamp does not happen.
+-- The house's three rooms — plain, shared tables. Everyone in the house writes into
+-- these same tables with their own credential; `user_id MATERIALIZED currentUser()`
+-- (server-stamped, async_insert pinned to 0 on the user) says who, and `host` says
+-- which machine. There is no per-member table and no Merge room: the database IS the
+-- boundary, and a housemate is anyone granted on it.
 --
 -- ClickHouse >= 26.2 natively — 25.11 works because the shipper passes
 -- allow_experimental_full_text_index=1 per-query when applying this file.
 
-CREATE TABLE IF NOT EXISTS sessions_{{MEMBER}}
+CREATE TABLE IF NOT EXISTS sessions
 (
     session_id String,
     source LowCardinality(String),
@@ -47,7 +44,7 @@ CREATE TABLE IF NOT EXISTS sessions_{{MEMBER}}
 ENGINE = ReplacingMergeTree(ingested_at)
 ORDER BY (session_id, user_id);
 
-CREATE TABLE IF NOT EXISTS messages_{{MEMBER}}
+CREATE TABLE IF NOT EXISTS messages
 (
     session_id String,
     seq UInt32,
@@ -88,7 +85,7 @@ CREATE TABLE IF NOT EXISTS messages_{{MEMBER}}
 ENGINE = ReplacingMergeTree(ingested_at)
 ORDER BY (session_id, user_id, origin, seq);
 
-CREATE TABLE IF NOT EXISTS tool_calls_{{MEMBER}}
+CREATE TABLE IF NOT EXISTS tool_calls
 (
     session_id String,
     seq UInt32,

package/memhouse/resume.js

@@ -26,7 +26,7 @@
 // `source: 'claude-code'` on every chat it returns. This table was written against the
 // module names first and would have refused to resume a single Claude Code session — 508 of
 // them on the machine it was tested on. Read the values out of a real house
-// (`SELECT DISTINCT source FROM sessions_<you>`), never off the adapter's name.
+// (`SELECT DISTINCT source FROM sessions`), never off the adapter's name.
 const RESUMERS = {
   // claude --help, 2026-08-12: "-r, --resume [value]  Resume a conversation by session ID"
   'claude-code': {

package/memhouse/server/queries.js

@@ -18,13 +18,13 @@
 
 const { createClient, ClickHouseLogLevel } = require('@clickhouse/client');
 const { calculateCost, normalizeModelName } = require('../../pricing');
-const { resolveRooms, READ_SETTINGS } = require('../per-member/rooms');
+const { resolveRooms, READ_SETTINGS } = require('../house/house');
 
 const config = {
   url: process.env.MEMHOUSE_URL || 'http://localhost:8123',
   username: process.env.MEMHOUSE_USER || 'memhouse_root',
   password: process.env.MEMHOUSE_PASSWORD || '',
-  database: process.env.MEMHOUSE_DB || 'mem',
+  database: process.env.MEMHOUSE_DB || process.env.MEMHOUSE_USER, // house defaults to the user's own name
 };
 
 let _client = null;
@@ -925,6 +925,12 @@ async function rawQuery(sql) {
     // Cut the result off rather than failing a query that was legitimately large.
     result_overflow_mode: 'break',
     max_execution_time: 30,
+    // Result caps bound what LEAVES the server; this bounds what the query does inside
+    // it — a huge GROUP BY hits none of the caps above while eating the box's memory.
+    // Used to come from the member settings profile; that object is gone (it detached
+    // members on replace and its name was server-global), so the one caller that pipes
+    // arbitrary SQL carries its own ceiling.
+    max_memory_usage: 8000000000,
   });
   const columns = rows.length > 0 ? Object.keys(rows[0]) : [];
   return { columns, rows, count: rows.length, truncated: rows.length >= RAW_MAX_ROWS };

package/memhouse/shipper/ship.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 // memhouse SHIPPER — parse-on-client (bet #1 in ../DESIGN.md). Runs the 17 editor
-// adapters locally and ships TYPED rows into THE CALLER'S OWN rooms — sessions_<m> /
+// adapters locally and ships TYPED rows into the house's shared rooms — sessions /
 // messages_<m> / tool_calls_<m>, where <m> is `SELECT currentUser()` and never config
-// (../per-member/schema-member.sql.tpl, ../per-member/rooms.js). All of one member's
+// (../house/schema.sql.tpl, ../house/house.js). All of one member's
 // machines land in that member's rooms, told apart by the `host` column; no member
 // writes into another's. The typed evolution of agency/ingest.js: same host id,
 // same ts interpolation, same batching discipline — but rows land in physical
@@ -43,7 +43,7 @@ try { ({ createClient, ClickHouseLogLevel } = require('@clickhouse/client')); }
 catch {
   console.error("[memhouse] dependency '@clickhouse/client' is not installed.");
   console.error(`[memhouse] from a checkout:     npm install --prefix ${require('path').join(__dirname, '..', '..')}`);
-  console.error(`[memhouse] from an npm install: ${require('../per-member/rooms').installCommand()}`);
+  console.error(`[memhouse] from an npm install: ${require('../house/house').installCommand()}`);
   process.exit(2);
 }
 const { getAllChats, getAdapterErrors, getMessages, resetCaches } = require('../../editors');
@@ -52,7 +52,7 @@ const selfUpdate = require('../self-update');
 // Captured at require time, which is as close to "what this process booted with" as it
 // gets. Taking it later would record whatever an upgrade had already replaced.
 const selfSnap = selfUpdate.snapshot(__filename);
-const { resolveRooms, READ_SETTINGS, ROOM_TYPES } = require('../per-member/rooms');
+const { resolveRooms, READ_SETTINGS, ROOM_TYPES } = require('../house/house');
 
 const BATCH_ROWS = 2000;   // insert batch ceiling (binding)
 const TEXT_MAX = 50000;    // messages.text truncation
@@ -203,7 +203,7 @@ function makeClient() {
     url: process.env.MEMHOUSE_URL,
     username: process.env.MEMHOUSE_USER,
     password: process.env.MEMHOUSE_PASSWORD || '',
-    database: process.env.MEMHOUSE_DB || 'mem',
+    database: process.env.MEMHOUSE_DB || process.env.MEMHOUSE_USER, // house defaults to the user's own name
     request_timeout: 300000, // full re-ships move tens of MB; don't cut inserts short
     clickhouse_settings: {
       // Int64/UInt64 back as JSON numbers — our values (counts, tokens) are < 2^53.
@@ -221,7 +221,7 @@ function makeClient() {
   });
 }
 
-// Create the CALLER'S OWN rooms, from ../per-member/schema-member.sql.tpl. Comments are
+// Create the house's rooms, from ../house/schema.sql.tpl. Comments are
 // stripped BEFORE the ';' split — schema comments legitimately contain semicolons.
 //
 // This is the solo path: on a house you own, `memhouse install` mints your three rooms and
@@ -229,9 +229,8 @@ function makeClient() {
 // same identity the rooms' user_id is stamped with, so a client cannot name its way into
 // someone else's rooms.
 //
-// It does NOT issue grants or create the Merge rooms. A solo owner needs neither. Adding a
-// SECOND member — grants, Merge rooms, sharing — is owner work and lives in
-// ../per-member/provision.js.
+// It issues no grants: joining a house is the admin's two statements (CREATE USER +
+// GRANT ALL ON the house), and once granted, each member's own shipper runs this.
 /**
  * Refuse to write into rooms whose sorting key is wrong for `origin` — in EITHER
  * direction. Two different houses are broken in two opposite ways:
@@ -251,7 +250,7 @@ function makeClient() {
  * Refuse, legibly, when the caller's rooms are not there.
  *
  * Without this the first thing to touch a roomless house is loadExisting's SELECT, and the
- * user gets `Unknown table expression identifier 'sessions_x' in scope SELECT session_id,
+ * user gets `Unknown table expression identifier 'sessions' in scope SELECT session_id,
  * last_updated_at, message_count, extra FROM ...` — a raw ClickHouse identifier error with
  * no next step, from a command that may be running inside a service loop. `install` and
  * `doctor` both handle the identical situation properly; ship was the one that did not.
@@ -305,7 +304,7 @@ function templateColumns(tpl) {
  */
 async function warnMissingColumns(client, rooms) {
   let tpl;
-  try { tpl = fs.readFileSync(path.join(__dirname, '..', 'per-member', 'schema-member.sql.tpl'), 'utf-8'); }
+  try { tpl = fs.readFileSync(path.join(__dirname, '..', 'house', 'schema.sql.tpl'), 'utf-8'); }
   catch { return; }
   const want = templateColumns(tpl);
   const missing = [];
@@ -375,7 +374,7 @@ async function assertOriginKeyed(client, rooms) {
       + wrong.map((s) => `    ${s}`).join('\n')
       + '\n  ORDER BY cannot be altered in place. Rebuild each room, then re-ship:'
       + '\n    RENAME TABLE <room> TO <room>_old;'
-      + `\n    -- recreate from ${path.join(__dirname, '..', 'per-member', 'schema-member.sql.tpl')}`
+      + `\n    -- recreate from ${path.join(__dirname, '..', 'house', 'schema.sql.tpl')}`
       + '\n    INSERT INTO <room> SELECT * FROM <room>_old;'
       + '\n  (add `, \'ship\' AS origin` to the SELECT only if <room>_old has no origin column)'
       + '\n  A house with no imported rows can also just be re-shipped from scratch.');
@@ -384,18 +383,19 @@ async function assertOriginKeyed(client, rooms) {
 
 async function ensureSchema(client) {
   const rooms = await resolveRooms(client);
-  const { member } = rooms;
-  const tpl = fs.readFileSync(path.join(__dirname, '..', 'per-member', 'schema-member.sql.tpl'), 'utf-8');
-  const sql = tpl.replaceAll('{{MEMBER}}', member);
+  const tpl = fs.readFileSync(path.join(__dirname, '..', 'house', 'schema.sql.tpl'), 'utf-8');
+  const sql = tpl; // plain shared tables — nothing to render
   const stripped = sql.split('\n').map((l) => l.replace(/--.*$/, '')).join('\n');
   const stmts = stripped.split(';').map((s) => s.trim()).filter(Boolean);
-  // A MEMBER holds no CREATE TABLE — that is the point of the narrowed grant set — and
-  // ClickHouse checks the grant BEFORE it checks existence, so `IF NOT EXISTS` does not
-  // save these. Running the CREATEs in a bare loop meant `--ensure-schema` died on the
-  // FIRST statement for the very user who is told to run it, and never reached the ADD
-  // COLUMN rollout that is the whole reason to run it. Skip what we may not do and carry
-  // on; the rooms either already exist (assertRoomsExist says so) or an owner has to
-  // create them, which install already explains.
+  // Two failure shapes are survivable here and both are skipped rather than fatal:
+  //
+  //   - a permission denial. A read-only credential can still run --ensure-schema for
+  //     its ADD COLUMN rollout; ClickHouse checks the grant BEFORE existence, so IF NOT
+  //     EXISTS does not save the CREATEs. Skip what we may not do and carry on.
+  //   - a create RACE. Two housemates' first-ever ships can run these CREATEs
+  //     concurrently, and IF NOT EXISTS is not atomic against a simultaneous creator —
+  //     the loser can get TABLE_ALREADY_EXISTS or a metadata-file collision. The table
+  //     exists either way, which is the outcome this function wants.
   let denied = 0;
   for (const q of stmts) {
     try {
@@ -410,6 +410,7 @@ async function ensureSchema(client) {
     } catch (e) {
       const m = e && e.message ? e.message : String(e);
       if (/Not enough privileges|ACCESS_DENIED/i.test(m)) { denied++; continue; }
+      if (/ALREADY_EXISTS|already exists/i.test(m)) { continue; } // lost a create race — the winner made it
       throw e;
     }
   }
@@ -422,13 +423,6 @@ async function ensureSchema(client) {
   // would error. Add it in place; ReplacingMergeTree backfills the DEFAULT, so every
   // pre-existing row reads as 'ship', which is what it was.
   //
-  // Deliberately NOT applied to the Merge rooms — but not for the reason this comment used
-  // to give. It claimed they "reject ALTER"; they do not, on either 26.7 or 25.11, where
-  // `ALTER TABLE all_messages ADD COLUMN …` succeeds. The real reason is that a Merge room
-  // is a VIEW over whatever `^messages_` matches: a column added to it is cosmetic, is not
-  // backed by the underlying rooms, and drifts from them the moment a member is added. It
-  // takes its structure from a member room at CREATE time, so recreating it is the only
-  // correct way to change it — and nothing reads `origin` through it anyway.
   // EVERY column the template declares, not just `origin`.
   //
   // This used to add exactly one column, which meant any OTHER column missing from a room
@@ -807,7 +801,7 @@ function reportAdapterErrors(warned) {
   const noBinding = errors.filter((e) => e.missingBinding).map((e) => e.source);
   if (noBinding.length) {
     console.log(`[memhouse] WARNING: ${noBinding.length} adapter(s) skipped, sessions NOT shipped — better-sqlite3 has no native binding: ${noBinding.join(', ')}`);
-    console.log(`[memhouse]          fix: ${require('../per-member/rooms').installCommand()}`);
+    console.log(`[memhouse]          fix: ${require('../house/house').installCommand()}`);
   }
   for (const e of errors.filter((x) => !x.missingBinding)) {
     console.log(`[memhouse] WARNING: ${e.source} skipped — ${e.message}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memhouse",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "description": "memhouse — agent conversation memory across 17 editors: parse-on-client shippers, a typed ClickHouse store with one set of rooms per member, kernel-agency install, and the agentlytics dashboard",
   "main": "bin/memhouse.js",
   "bin": {

package/memhouse/per-member/INSTALL.md

@@ -1,228 +0,0 @@
-# INSTALL — how a house gets a member
-
-Three options. The first two are finished and measured; the third is not.
-
-| | you hold admin | who runs the SQL | admin credential |
-|---|---|---|---|
-| **1. print the SQL** | yes | you | never leaves your terminal |
-| **2. hand it over** | yes | the installer | used, then discarded |
-| **3. kernel** | no — the realm does | not finalized | — |
-
-## The identity rule, first — everything else follows from it
-
-**The ClickHouse user is the identity.** Rooms are `sessions_<member>`,
-`messages_<member>`, `tool_calls_<member>`, and `<member>` is whatever the server answers
-to `SELECT currentUser()` — never what the config file says, never what the OS says.
-
-The home directory produces a **suggestion**:
-
-```
-/Users/polat          -> polat
-/Users/ramazan.polat  -> ramazan_polat     (sanitized, and the change is printed)
-/home/JohnSmith       -> JohnSmith         (case preserved; ClickHouse is case-sensitive)
-/root                 -> refused           (a container artefact, not a person)
-```
-
-Sanitization is `[A-Za-z][A-Za-z0-9_]*`. It can collide — `ramazan.polat` and
-`ramazan-polat` both land on `ramazan_polat` — so a changed suggestion is printed, and
-`--member` overrides it.
-
-## Option 1 — print the SQL, run it yourself
-
-The common case: you installed ClickHouse, you have `default` with
-`access_management = 1`, and you would rather run four kinds of statement than hand a
-superuser credential to an installer.
-
-```
-memhouse install --print-sql [--member polat] [--db mem]
-```
-
-Prints the whole install as SQL and exits. Nothing is contacted, nothing is written. It
-generates a password and prints it inside the `CREATE USER`, or takes `--member-password`.
-The last line is the command to run afterwards, with the credential filled in.
-
-Two properties that make the block safe to paste anywhere:
-
-- **Every name is qualified and there is no `USE`.** It runs in `clickhouse-client`, the
-  play UI, `curl`, or a GUI, in any database context.
-- **The Merge engine gets the literal house name, not `currentDatabase()`.** That call is
-  evaluated at CREATE time, not read time, so a block run without the house selected would
-  otherwise build Merge rooms pointing at `default` that return zero rows forever, with no
-  error at any point.
-
-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
-
-```
-memhouse install --admin-user … --admin-password … [--member polat]
-```
-
-The same statements, applied by `provision.js` so there is one implementation of the grant
-set rather than two that drift. Then the step that makes the mode trustworthy:
-**disconnect from admin, reconnect as the member, and prove that credential reaches all
-three rooms before writing anything.** A mode that only proves the admin could do it has
-proven nothing about the credential it is about to persist.
-
-**The admin credential is never persisted** — not to the env file, not to a unit file, not
-to a log. A shipper running as the house owner would make per-member rooms decoration.
-
-## Option 3 — the kernel
-
-**Not finalized.** The realm holds the privileged credential and mints members; what the
-installer asks it for, and what it gets back, is not designed yet. Everything above about
-the room layout, the grant set and the identity rule holds regardless — what is open is
-who plays admin and how the handle is chosen.
-
-## The grant set — two statements per room, and the split is the point
-
-```sql
-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;
-```
-
-**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:
-
-```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.
-
-**`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      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.
-
-`SELECT` on the three Merge rooms is granted broadly and is safe: a Merge table reduces to
-the underlying rooms the *caller* holds grants for, so it narrows rather than denies, and
-picks up members added later with no DDL.
-
-## Refusals — the complete list
-
-Install refuses, names both sides, and creates nothing:
-
-| Case | Why |
-|---|---|
-| handle does not match `[A-Za-z][A-Za-z0-9_]*` after sanitization | it would need quoting, and a quoted room name breaks the Merge selectors |
-| handle would be `root`, or the home directory is `/root` | a container artefact, not a person |
-| **option 2: the ClickHouse user already exists** | the second human would take over the first's identity and rooms, and `user_id MATERIALIZED currentUser()` would stamp them identically. Requires `--adopt-user` AND `--member-password`, verified by reconnecting before anything is written |
-| option 2: `mem` absent and admin cannot `CREATE DATABASE` | nothing downstream can work |
-| an env file already points at a different url/db | it would orphan a running shipper. `memhouse setup` is the deliberate way to move; `--force` overrides |
-| rooms missing and you cannot create them | you are not the owner — both other options are printed |
-
-`--adopt-user` is legitimate — the same person on a new laptop — but it is
-indistinguishable from a takeover without the password, so the password is the proof.
-
-## After install — when admin is needed again
-
-- **a second member** — `provision.js --member <name> --merge`, or `--print-sql --member <name>`
-- **schema rollout** — `ADD COLUMN` on the **Merge room first**, then the member rooms;
-  Merge rejects mutations and tolerates drift, which is what makes a progressive rollout
-  possible
-- **offboarding** — `DROP USER <member>`. The rooms are deliberately left: they hold that
-  person's transcripts, and deleting someone's memory is a decision, not a cleanup step
-
-## Upgrading from 0.3.x — read this before you do
-
-**0.4.0 cannot read a 0.3.x house.** An earlier version of this document said an existing
-house "keeps working untouched". That was wrong, and it was wrong in the release notes and
-the `v0.4.0` tag message too.
-
-What is true: the DATABASE NAME survives. `MEMHOUSE_DB` sits in `~/.memhouse/env` and
-explicit config outranks the new `mem` default, so nothing repoints you at a different
-house. What does not survive is the TABLES. 0.3.x kept `sessions`, `messages`,
-`tool_calls` and a stored `sessions_v`; 0.4.0 looks for `sessions_<you>` and finds nothing.
-Measured against a real 0.3.2 house:
-
-```
-memhouse status  ->  not connected: Code: 60 ... Unknown table expression
-                     identifier 'sessions_memhouse_root'
-memhouse doctor  ->  schema: 0/3 rooms in 'memhouse'
-memhouse ship    ->  pass failed: UNKNOWN_TABLE
-```
-
-`install` and `doctor` now detect this and name it, rather than telling you to run an
-install you already ran.
-
-**Your transcripts are not lost.** memhouse ships FROM your local session stores, so the
-new rooms rebuild from disk and the old tables are left untouched:
-
-```
-memhouse install --admin-user <user> --admin-password <pw> --member <you>
-memhouse ship --full
-```
-
-The one thing that does not come back that way is a session whose transcript you have
-since deleted locally — it exists only in the old tables. Read those before dropping
-anything: `SELECT * FROM <db>.sessions`.
-
-## Where the credential lives
-
-`~/.memhouse/env`, mode 0600, `MEMHOUSE_*` keys. **Not** a `.env` in a working directory:
-the skills and docs source this path (`. ~/.memhouse/env`), and a `.env` beside a checkout
-gets committed eventually.
-
-The env file is written **last**, after everything above has proved out. Written first, a
-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.