memhouse 0.3.2 → 0.4.3

package/mem-house/deploy.js

@@ -0,0 +1,333 @@
+// Local ClickHouse delivery — the missing first mile.
+//
+// Every install path assumes a reachable ClickHouse. This stands one up.
+//
+// Deliberately does NOT depend on compose. memhouse needs exactly one container, and a
+// compose provider is not a given: the testbed VM has podman 4.9.3 with no compose
+// provider at all (`podman compose` → "looking up compose provider failed"), and
+// podman-compose/docker-compose are absent. Everything compose bought us here — a named
+// volume, a loopback port binding, env, a restart policy — is one `run` flag each.
+// deploy/compose.yml stays for people who prefer it; nothing in the CLI needs it.
+//
+// The stock upstream server image is used as-is. Nothing bakes the memhouse checkout
+// into an image; memhouse stays on the host and connects over HTTP.
+
+const { spawnSync } = require('child_process');
+
+const CONTAINER = 'memhouse-clickhouse';
+const VOLUME = 'memhouse-data';
+const DEFAULT_TAG = '25.11';
+// Fully qualified on purpose. docker resolves a short name against Docker Hub; podman
+// refuses unless unqualified-search registries are configured, which they are not on a
+// stock Debian/Ubuntu install:
+//   short-name "clickhouse/clickhouse-server:25.11" did not resolve to an alias and no
+//   unqualified-search registries are defined in "/etc/containers/registries.conf"
+const IMAGE_REPO = 'docker.io/clickhouse/clickhouse-server';
+
+// Ownership label. `memhouse-clickhouse` and `memhouse-data` are fixed names, so without
+// a marker a name collision with somebody else's container would let `deploy --local`
+// (which replaces) or `deploy --down` (which removes) destroy an unrelated workload and
+// its data. Anything we did not create is refused, never removed.
+const OWNER_LABEL = 'com.memhouse.managed';
+
+/** Every container engine on PATH, in preference order. */
+function availableEngines() {
+  return ['docker', 'podman'].filter((e) => spawnSync(e, ['--version'], { encoding: 'utf-8' }).status === 0);
+}
+
+/**
+ * The engine that OWNS the managed resources, not merely the first one installed.
+ *
+ * Picking by executable order is wrong the moment a machine has both: a house created
+ * with podman becomes invisible when docker is installed later, so the ownership checks
+ * report the fixed names absent, and the next deploy adopts or creates a different house
+ * and overwrites the only persisted credential for a volume that is still initialised.
+ *
+ * Returns { engine, ambiguous, engines }. `ambiguous` means both engines hold something
+ * under our names, which no caller may guess its way through.
+ */
+function owningEngine() {
+  // An explicit pin wins over all of this. It is the escape hatch for the indeterminate
+  // case below, which is otherwise unresolvable from here.
+  const pinned = process.env.MEMHOUSE_ENGINE;
+  if (pinned) {
+    return { engine: pinned, ambiguous: false, engines: [pinned], pinned: true };
+  }
+  const engines = availableEngines();
+  if (!engines.length) return { engine: null, ambiguous: false, engines };
+
+  const owners = [];
+  const indeterminate = [];
+  for (const e of engines) {
+    const states = [ownership(e, 'container', CONTAINER), ownership(e, 'volume', VOLUME)];
+    if (states.includes('ours')) owners.push(e);
+    // `unknown` means this engine could not tell us — an unreachable daemon, most
+    // likely. Discarding it would let ANOTHER engine's 'ours' look unambiguous while
+    // the silent one owns the house we are about to replace or remove. It is not
+    // evidence of absence, so it cannot be dropped from the count.
+    else if (states.includes('unknown')) indeterminate.push(e);
+  }
+  if (owners.length > 1) return { engine: null, ambiguous: true, engines, owners };
+  if (indeterminate.length) return { engine: null, indeterminate, engines, owners };
+  return { engine: owners[0] || engines[0], ambiguous: false, engines };
+}
+
+/** The engine to act through, or null if there is none. Ambiguity resolves to null. */
+function engine() {
+  const o = owningEngine();
+  return o.ambiguous ? null : o.engine;
+}
+
+// The engine says "no such object" when a name is free, and says other things when it
+// cannot answer at all — an unreachable daemon being the obvious one. Both are non-zero
+// exits, and collapsing them made an unreachable daemon look like a clean slate: `--down`
+// would then report success with nothing removed, over a container that is still running.
+//
+// The pattern must name the KIND of object that is missing. A bare `/no such/` was too
+// broad in exactly the direction that matters, because an unreachable engine says
+// `Cannot connect ... stat /run/user/1000/podman/podman.sock: no such file or directory`.
+// docker says `No such object: NAME` / `No such container: NAME`, podman says
+// `no such container NAME`; no socket error names a container, volume or image.
+const NOT_FOUND = /no such (object|container|volume|image)\b/i;
+
+/** 'absent' | 'ours' | 'foreign' | 'unknown' — for a container or a volume. */
+function ownership(eng, kind, name) {
+  const args = kind === 'volume'
+    ? ['volume', 'inspect', '-f', `{{index .Labels "${OWNER_LABEL}"}}`, name]
+    : ['inspect', '-f', `{{index .Config.Labels "${OWNER_LABEL}"}}`, name];
+  const r = spawnSync(eng, args, { encoding: 'utf-8' });
+  if (r.error) return 'unknown';
+  if (r.status !== 0) {
+    return NOT_FOUND.test(`${r.stderr || ''}${r.stdout || ''}`) ? 'absent' : 'unknown';
+  }
+  // Go's template prints `<no value>` for a missing key, empty for a present-but-empty
+  // one; both mean the object exists and is not ours.
+  return (r.stdout || '').trim() === '1' ? 'ours' : 'foreign';
+}
+
+function unknownMsg(kind, name, eng) {
+  return `cannot determine whether ${kind} '${name}' exists — ${eng} answered neither `
+    + '"no such object" nor a label. Is the daemon reachable? Refusing to guess.';
+}
+
+function foreignMsg(kind, name) {
+  return `refusing to touch ${kind} '${name}': it exists but was not created by memhouse `
+    + `(no ${OWNER_LABEL} label). Remove or rename it yourself if it is disposable.`;
+}
+
+/**
+ * Start the house container. Returns { ok, url, password, engine, msg }.
+ * The password is required — an unauthenticated house on a laptop is how agent
+ * transcripts leak to anything that can reach the port. The port binds to loopback
+ * for the same reason.
+ */
+function up({ password, port = 8123, tag = DEFAULT_TAG, user = 'memhouse_root' }) {
+  const o = owningEngine();
+  if (o.ambiguous || o.indeterminate) return { ok: false, msg: ambiguousMsg(o) };
+  const eng = o.engine;
+  if (!eng) return { ok: false, msg: 'neither docker nor podman found on PATH' };
+  if (!password) return { ok: false, msg: 'refusing to start an unauthenticated house — no password given' };
+
+  const own = ownership(eng, 'container', CONTAINER);
+  if (own === 'foreign') return { ok: false, engine: eng, msg: foreignMsg('container', CONTAINER) };
+  if (own === 'unknown') return { ok: false, engine: eng, msg: unknownMsg('container', CONTAINER, eng) };
+  const volOwn = ownership(eng, 'volume', VOLUME);
+  if (volOwn === 'foreign') return { ok: false, engine: eng, msg: foreignMsg('volume', VOLUME) };
+  if (volOwn === 'unknown') return { ok: false, engine: eng, msg: unknownMsg('volume', VOLUME, eng) };
+
+  // Make sure the replacement image is actually available BEFORE removing the house it
+  // replaces. `run` discovers a bad tag or an unreachable registry only after the old
+  // container is gone, which takes a working house offline for a typo.
+  const img = ensureImage(eng, tag);
+  if (!img.ok) return { ok: false, engine: eng, msg: img.msg };
+  const image = img.image;
+
+  if (own === 'ours') spawnSync(eng, ['rm', '-f', CONTAINER], { encoding: 'utf-8' });
+
+  // Create the volume explicitly so it carries the label. `run -v name:/path` would
+  // create it unlabeled, and an unlabeled volume is one we then refuse to remove.
+  let createdVolume = false;
+  if (volOwn === 'absent') {
+    const v = spawnSync(eng, ['volume', 'create', '--label', `${OWNER_LABEL}=1`, VOLUME], { encoding: 'utf-8' });
+    if (v.status !== 0) return { ok: false, engine: eng, msg: (v.stderr || '').trim().split('\n').slice(-1)[0] };
+    createdVolume = true;
+  }
+
+  const args = [
+    'run', '-d',
+    '--name', CONTAINER,
+    '--label', `${OWNER_LABEL}=1`,
+    '--restart', 'unless-stopped',
+    '-e', `CLICKHOUSE_USER=${user}`,
+    '-e', `CLICKHOUSE_PASSWORD=${password}`,
+    // The house itself is created by `memhouse install`, not here: pre-creating it
+    // would skip the step an install is supposed to prove.
+    '-e', 'CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT=1',
+    '-p', `127.0.0.1:${port}:8123`,
+    '-v', `${VOLUME}:/var/lib/clickhouse`,
+    '--ulimit', 'nofile=262144:262144',
+    image,
+  ];
+  const r = spawnSync(eng, args, { encoding: 'utf-8' });
+  if (r.status !== 0) {
+    // The volume exists but the image never touched it — an unpullable tag, a port bind
+    // that failed. Leaving it labelled would make the NEXT deploy read an empty volume as
+    // an initialised house and refuse for a missing credential that was never set. Only
+    // remove one this call created; an existing house's data is never at stake here.
+    if (createdVolume) spawnSync(eng, ['volume', 'rm', '-f', VOLUME], { encoding: 'utf-8' });
+    return { ok: false, engine: eng, msg: (r.stderr || '').trim().split('\n').slice(-2).join(' ') };
+  }
+  return { ok: true, engine: eng, url: `http://localhost:${port}`, password };
+}
+
+/**
+ * Remove the container and its volume — but only the ones memhouse created. Needs no
+ * password: nothing is contacted. Removing an unowned object is the destructive mistake
+ * this guards, so a foreign name is an error, not a warning.
+ */
+function down() {
+  const o = owningEngine();
+  if (o.ambiguous || o.indeterminate) return { ok: false, msg: ambiguousMsg(o) };
+  const eng = o.engine;
+  if (!eng) return { ok: false, msg: 'neither docker nor podman found on PATH' };
+
+  const cOwn = ownership(eng, 'container', CONTAINER);
+  if (cOwn === 'foreign') return { ok: false, engine: eng, msg: foreignMsg('container', CONTAINER) };
+  if (cOwn === 'unknown') return { ok: false, engine: eng, msg: unknownMsg('container', CONTAINER, eng) };
+  const vOwn = ownership(eng, 'volume', VOLUME);
+  if (vOwn === 'foreign') return { ok: false, engine: eng, msg: foreignMsg('volume', VOLUME) };
+  if (vOwn === 'unknown') return { ok: false, engine: eng, msg: unknownMsg('volume', VOLUME, eng) };
+
+  // Report what actually happened, not what was attempted. The engine can fail here —
+  // the daemon going away between the ownership check and the removal is the obvious
+  // way — and announcing "removed" over a container that is still running is how a user
+  // ends up with a house they believe is gone. `containerRemoved` used to be true merely
+  // because the container was OURS, which is a statement about ownership, not removal.
+  const failures = [];
+  let containerRemoved = false;
+  if (cOwn === 'ours') {
+    const r = spawnSync(eng, ['rm', '-f', CONTAINER], { encoding: 'utf-8' });
+    containerRemoved = r.status === 0;
+    if (!containerRemoved) failures.push(`container '${CONTAINER}': ${(r.stderr || '').trim().split('\n').slice(-1)[0] || `exit ${r.status}`}`);
+  }
+  let volumeRemoved = false;
+  if (vOwn === 'ours') {
+    const v = spawnSync(eng, ['volume', 'rm', '-f', VOLUME], { encoding: 'utf-8' });
+    volumeRemoved = v.status === 0;
+    if (!volumeRemoved) failures.push(`volume '${VOLUME}': ${(v.stderr || '').trim().split('\n').slice(-1)[0] || `exit ${v.status}`}`);
+  }
+  if (failures.length) return { ok: false, engine: eng, containerRemoved, volumeRemoved, msg: `removal failed — ${failures.join('; ')}` };
+  return { ok: true, engine: eng, volumeRemoved, containerRemoved };
+}
+
+/** Poll /ping until the server answers. An install against a still-starting server
+ *  fails in a way that looks like a bad credential, so never guess with a sleep. */
+async function waitReady(url, { attempts = 60, delayMs = 2000 } = {}) {
+  for (let i = 0; i < attempts; i++) {
+    try {
+      const r = await fetch(`${url}/ping`, { signal: AbortSignal.timeout(2000) });
+      if (r.ok) return true;
+    } catch { /* still starting */ }
+    await new Promise((res) => setTimeout(res, delayMs));
+  }
+  return false;
+}
+
+/** The image tag the managed container is running, or '' if there is none to read. */
+function managedTag() {
+  const eng = engine();
+  if (!eng) return '';
+  const r = spawnSync(eng, ['inspect', '-f', '{{.Config.Image}}', CONTAINER], { encoding: 'utf-8' });
+  if (r.error || r.status !== 0) return '';
+  const image = (r.stdout || '').trim();
+  const at = image.lastIndexOf(':');
+  // A ':' in a registry host:port is not a tag separator — only one after the last '/'.
+  return at > image.lastIndexOf('/') ? image.slice(at + 1) : '';
+}
+
+/** The host port the managed container publishes, or '' if there is none to read. */
+function publishedPort() {
+  const eng = engine();
+  if (!eng) return '';
+  const r = spawnSync(eng, ['inspect', '-f', '{{range $p, $c := .NetworkSettings.Ports}}{{range $c}}{{.HostPort}}{{end}}{{end}}', CONTAINER], { encoding: 'utf-8' });
+  if (r.error || r.status !== 0) return '';
+  return (r.stdout || '').trim();
+}
+
+function ambiguousMsg(o) {
+  if (o.indeterminate) {
+    return `${o.indeterminate.join(' and ')} could not say whether it holds '${CONTAINER}' or `
+      + `'${VOLUME}' — an unreachable daemon looks the same as an empty one, and acting on the `
+      + 'other engine could replace or remove the wrong house. Start it, or pin the engine '
+      + `explicitly: MEMHOUSE_ENGINE=${(o.owners && o.owners[0]) || o.engines.find((e) => !o.indeterminate.includes(e)) || o.engines[0]}`;
+  }
+  return `both ${(o.owners || o.engines).join(' and ')} hold something named '${CONTAINER}' or `
+    + `'${VOLUME}' with the ${OWNER_LABEL} label. Refusing to guess which house is yours — `
+    + 'remove one of them, or run with only one engine on PATH.';
+}
+
+/**
+ * Everything `up()` would refuse for, asked BEFORE the caller changes anything.
+ * Returns { ok, msg, initialised }.
+ *
+ * `up()` checks ownership itself, but by the time it runs the CLI has already stopped
+ * the shipper, the dashboard and the shim — so a refusal costs the user a working
+ * pipeline in exchange for protecting them. The same questions, asked first.
+ */
+/**
+ * `tag` is OPT-IN: a caller asking only "does a local house exist here" should not fail
+ * because a registry is unreachable and the image is not cached.
+ */
+function preflight({ tag = null } = {}) {
+  const o = owningEngine();
+  if (o.ambiguous || o.indeterminate) return { ok: false, reason: 'ambiguous', msg: ambiguousMsg(o) };
+  const eng = o.engine;
+  // `reason` matters: `no-engine` means there cannot BE a local house on this machine;
+  // `unknown` means the engine is there and could not answer, which is not evidence of
+  // absence and must never be read as one.
+  if (!eng) return { ok: false, reason: 'no-engine', msg: 'neither docker nor podman found on PATH' };
+  // BOTH objects, before deciding anything. Returning on the first `foreign` hides the
+  // state that actually matters to a caller asking "is there a house here": a foreign
+  // container standing beside an initialised MANAGED volume.
+  const states = {
+    container: ownership(eng, 'container', CONTAINER),
+    volume: ownership(eng, 'volume', VOLUME),
+  };
+  for (const [kind, name] of [['container', CONTAINER], ['volume', VOLUME]]) {
+    if (states[kind] === 'unknown') return { ok: false, reason: 'unknown', engine: eng, states, msg: unknownMsg(kind, name, eng) };
+  }
+  for (const [kind, name] of [['container', CONTAINER], ['volume', VOLUME]]) {
+    if (states[kind] === 'foreign') return { ok: false, reason: 'foreign', engine: eng, states, msg: foreignMsg(kind, name) };
+  }
+  // The image, too, when the caller is actually going to run one — `up()` checks it, but
+  // by then the caller has stopped the shipper and the dashboard, so a bad tag costs a
+  // working pipeline to discover.
+  if (tag) {
+    const img = ensureImage(eng, tag);
+    if (!img.ok) return { ok: false, reason: 'image', engine: eng, msg: img.msg };
+  }
+  return { ok: true, engine: eng, states, initialised: states.volume === 'ours' };
+}
+
+/** Present locally, or pullable. Never removes anything. */
+function ensureImage(eng, tag) {
+  const image = `${IMAGE_REPO}:${tag}`;
+  if (spawnSync(eng, ['image', 'inspect', image], { encoding: 'utf-8' }).status === 0) return { ok: true, image };
+  const pull = spawnSync(eng, ['pull', image], { encoding: 'utf-8' });
+  if (pull.status !== 0) {
+    return {
+      ok: false,
+      image,
+      msg: `cannot obtain ${image} — ${(pull.stderr || '').trim().split('\n').slice(-1)[0] || `exit ${pull.status}`}. `
+        + 'The existing house was left running.',
+    };
+  }
+  return { ok: true, image };
+}
+
+module.exports = {
+  engine, owningEngine, availableEngines, ensureImage, publishedPort, managedTag, up, down, waitReady, preflight,
+  CONTAINER, VOLUME, DEFAULT_TAG,
+  // exported for the unit gate: classifying an engine message wrong is silent
+  _NOT_FOUND: NOT_FOUND,
+};

package/mem-house/envfile.js

@@ -0,0 +1,49 @@
+// ~/.memhouse/env — one reader and one writer, shared by everything that touches it.
+//
+// The file is written in shell form (single-quoted values) because the skills and docs
+// source it: `. ~/.memhouse/env`. That makes the quoting part of the format, and a second
+// parser that only strips the outer quotes silently mangles any password containing a
+// quote — `'ab'\''cd'` becomes `ab'\''cd`, so the daemon authenticates with a different
+// credential than the interactive commands, and the only symptom is an auth failure that
+// looks like a wrong password. So: one parser, here.
+
+/** Parse shell-style `KEY='value'` lines. Understands the `'\''` escape we emit. */
+function parse(text) {
+  const out = {};
+  for (const line of String(text).split('\n')) {
+    if (line.trim().startsWith('#')) continue;
+    const m = line.match(/^\s*([A-Z0-9_]+)\s*=\s*(.*?)\s*$/);
+    if (!m) continue;
+    let v = m[2];
+    if (v.startsWith("'") && v.endsWith("'") && v.length >= 2) {
+      v = v.slice(1, -1).replace(/'\\''/g, "'");
+    } else if (v.startsWith('"') && v.endsWith('"') && v.length >= 2) {
+      v = v.slice(1, -1);
+    }
+    out[m[1]] = v;
+  }
+  return out;
+}
+
+/** Shell single-quoted, safe to `source`. */
+function quoteShell(v) {
+  return `'${String(v).replace(/'/g, `'\\''`)}'`;
+}
+
+/**
+ * systemd `Environment=` value. Double-quoted with C escapes, which is what systemd's
+ * own parser expects — deliberately NOT the shell form, because systemd does not
+ * understand `'\''` and would carry the backslashes into the value.
+ */
+function quoteSystemd(v) {
+  return `"${String(v).replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+
+/** systemd cannot express a newline inside Environment=; refuse rather than truncate. */
+function assertSingleLine(env) {
+  for (const [k, v] of Object.entries(env)) {
+    if (/[\r\n]/.test(String(v))) throw new Error(`${k} contains a newline, which cannot be passed to a service`);
+  }
+}
+
+module.exports = { parse, quoteShell, quoteSystemd, assertSingleLine };

package/mem-house/per-member/INSTALL.md

@@ -0,0 +1,183 @@
+# 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: 17 statements, run over HTTP with no database selected, 17 succeeded, 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 ALL    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).
+
+**`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".
+
+Measured on 26.7.2:
+
+```
+polat grants SELECT to bob      ok
+polat grants DROP TABLE to bob  497 Not enough privileges
+polat drops their own room      ok
+bob ends up with                GRANT SELECT ON mem.sessions_polat
+```
+
+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`.