memhouse 0.8.0 → 0.11.0

package/memhouse/delivery/plugin/skills/share/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: share
+description: Share your conversation memory with another user on the same ClickHouse — grant them read-only access to your house, list who can currently read it, or revoke a share. Use when the user says "share my memory with X", "let X see my sessions", "who can read my memory", "stop sharing with X". Read-only by construction — a share can never let anyone write to or delete your memory.
+user-invocable: true
+argument-hint: "[<user> | revoke <user> | (nothing: list current shares)]"
+allowed-tools: Bash
+---
+
+# /mem:share — a read-only window into your memory
+
+Three forms, decided by the arguments:
+
+- `/mem:share yigit` — let `yigit` read this house
+- `/mem:share revoke yigit` — close that window
+- `/mem:share` — who can read this house right now
+
+Sharing is a ClickHouse GRANT and nothing else — memhouse adds no layer on top, so what
+you grant is exactly what they get: `SELECT`, never write, never delete. Your own grant
+carries `WITH GRANT OPTION` on SELECT only (installs from 0.10.0 on), so you can open
+this window yourself and can hand on nothing more.
+
+## Connection
+
+**Never print this file or the variables in it.** No `cat "$MH_ENV"`, no `env | grep
+MEMHOUSE`, no `set -x` around these commands.
+
+```bash
+MH_ENV="${MEMHOUSE_HOME:-$HOME/.memhouse}/env"
+_u=${MEMHOUSE_URL-}; _s=${MEMHOUSE_USER-}; _p=${MEMHOUSE_PASSWORD-}; _d=${MEMHOUSE_DB-}
+set -a; [ -f "$MH_ENV" ] && . "$MH_ENV"; set +a
+[ -n "$_u" ] && MEMHOUSE_URL=$_u; [ -n "$_s" ] && MEMHOUSE_USER=$_s
+[ -n "$_p" ] && MEMHOUSE_PASSWORD=$_p; [ -n "$_d" ] && MEMHOUSE_DB=$_d
+if [ -z "${MEMHOUSE_URL:-}" ] || [ -z "${MEMHOUSE_USER:-}" ]; then
+  echo "no memhouse house configured — nothing in $MH_ENV and no MEMHOUSE_URL/MEMHOUSE_USER set." >&2
+  echo "Run: memhouse install" >&2
+  exit 1
+fi
+
+# NO readonly=1 on this skill's grant/revoke calls — GRANT is refused under readonly.
+# The list query below still pins it.
+curl -sS --fail-with-body --user "$MEMHOUSE_USER:${MEMHOUSE_PASSWORD:-}" \
+  --data-binary @- "$MEMHOUSE_URL/?database=${MEMHOUSE_DB:-mem}" <<'SQL'
+<the statement>
+SQL
+```
+
+## Grant — `/mem:share <user>`
+
+The user name goes into SQL unquoted: **refuse anything not matching
+`[A-Za-z][A-Za-z0-9_]*`** rather than quoting it — a name you cannot type bare is a name
+that will be gotten wrong everywhere else too.
+
+**Validate `<user>` FIRST, once, and use only the validated token — in the GRANT, the
+REVOKE, and the house_meta record alike.** The record INSERT is a quoted literal;
+anything that has not passed the name check must never reach it.
+
+**`<db>` below is the LIVE value of `$MEMHOUSE_DB` — print it with the connection
+(`echo "house: $MEMHOUSE_DB"`) and use THAT in every statement and every piece of
+advice.** Driven live, a model filled `<db>` in the admin advice with the literal
+fallback `mem` while the real house was named differently — advice the admin would have
+run against the wrong database.
+
+```sql
+GRANT SELECT ON <db>.* TO <user>
+```
+
+(`<db>` is `$MEMHOUSE_DB`.) Then RECORD it in the house's own memory — a member cannot
+read `system.grants` (measured: `Not enough privileges … SELECT ON system.grants`), so
+this record is what the list form reads back:
+
+```sql
+INSERT INTO house_meta (key, value) VALUES ('share:<user>', 'granted <today, YYYY-MM-DD>')
+```
+
+Verify the grant took by USING it if you can, or simply report the server accepted it —
+do not call `SHOW GRANTS FOR <user>` (it needs privileges a member does not hold).
+
+Two failure shapes, both to report exactly:
+
+- `There is no user ... in user directories` — the person has no ClickHouse user on this
+  server yet. Joining comes first: they run `memhouse install` against this server (or
+  the admin runs `memhouse install --print-sql --member <user> --db <their-house>`).
+  A share cannot create a user, by design.
+- `Not enough privileges` — either this house predates 0.10.0 (your own grant carries
+  no grant option), or **the configured house is not yours to share** (a team house, or
+  someone else's). Only suggest the admin remedy when the house is the user's OWN — the
+  grant-option statement hands them standing power to share it, which is the owner's
+  decision, not a fix. For their own pre-0.10 house, print for the ADMIN:
+  `GRANT SELECT ON <db>.* TO <user>` — and to make future shares self-serve:
+  `GRANT SELECT ON <db>.* TO <your-user> WITH GRANT OPTION`.
+  For a house that is not theirs, say so and stop: the owner shares it, not you.
+
+Tell the user how their friend actually reads it: qualified names —
+`SELECT … FROM <db>.messages …` — from /mem:ask, /mem:search or /mem:sql on the friend's
+side, with the same epoch filter those skills already carry.
+
+## Revoke — `/mem:share revoke <user>`
+
+```sql
+REVOKE SELECT ON <db>.* FROM <user>
+```
+```sql
+INSERT INTO house_meta (key, value) VALUES ('share:<user>', 'revoked <today, YYYY-MM-DD>')
+```
+
+Revoking a share that never existed is a no-op, not an error — say which it was (the
+`share:<user>` record answers that).
+
+## List — `/mem:share` (no arguments)
+
+From the house's own record (append `&readonly=1` to the URL for this one):
+
+```sql
+SELECT substring(key, 7) AS user, value AS state,
+       formatDateTime(updated_at, '%Y-%m-%d %H:%i') AS at
+FROM house_meta FINAL WHERE key LIKE 'share:%' ORDER BY key
+```
+
+Latest-wins per user: `granted …` rows are live shares, `revoked …` rows are closed
+ones. Be honest about the record's edge: it shows shares made THROUGH THIS SKILL — a
+grant the admin issued directly will not appear. The authoritative list is the admin's
+one query: `SELECT user_name, access_type FROM system.grants WHERE database = '<db>'`
+(members cannot run it; `system.grants` needs privileges a member does not hold).
+
+## What this never does
+
+No `GRANT ALL`, no write grants, no `WITH GRANT OPTION` onward, no user creation, no
+grants on any database but your own. If the user asks for more than read access, that is
+the shared-house model (both members in ONE database) — a decision, not a grant; point
+them at `memhouse install --db <shared>` and stop.

package/memhouse/delivery/plugin/skills/sql/SKILL.md

@@ -6,17 +6,36 @@ argument-hint: "<question or SQL>"
 allowed-tools: Bash
 ---
 
-# /memhouse:sql — ad-hoc analytics
+# /mem:sql — ad-hoc analytics
 
 If the user gives SQL, run it (append `FORMAT PrettyCompact` if no FORMAT
 given). If they give a question, write the SQL yourself from the schema below.
 
-**Read-only rule:** the shipper (`ship.js`) is the only writer. Never INSERT/ALTER/DROP
-from here. A member credential holds `SELECT, INSERT, ALTER UPDATE, ALTER DELETE, ALTER ADD
-COLUMN, OPTIMIZE` on its **own three rooms** — enough to destroy the rows, though not
-the rooms — and nothing at all on anyone else's. Reads need no scoping
-clause: the rooms you can name are already only yours, and there is no policy to work
-around.
+**Read-only rule:** the shipper (`ship.js`) is the only writer, and it is INSERT-ONLY: it
+never deletes and never mutates, because a re-parse that shrank or was rewritten is
+written under a new `epoch` instead of over the stored one. Never INSERT/ALTER/DROP from
+here. The shipping path needs `SELECT, INSERT, ALTER ADD COLUMN, OPTIMIZE` and nothing
+more — the `ALTER DELETE` this line used to list was there for the per-session clear that
+no longer exists, so no unattended process can lose you a row. `ALTER DELETE` is still
+needed by the one command that is *meant* to remove rows, `memhouse reset`, which asks
+first. Most houses grant `ALL` on the database anyway. Reads need no scoping clause: the
+house you can name is already yours, and there is no policy to work around.
+
+**One session can be in `messages` twice.** A session that Claude Code compacted, or that
+shrank for any other reason, keeps its earlier parse — that is the whole point of `epoch`,
+and it is why nothing is ever deleted. Ad-hoc SQL must filter to the current parse or it
+counts such a session twice:
+
+```sql
+WHERE origin != 'ship'
+   OR (session_id, user_id, epoch) IN (
+        SELECT session_id, user_id, max(epoch) FROM messages
+        WHERE origin = 'ship' GROUP BY session_id, user_id)
+```
+
+Drop the filter deliberately when you want the history — "what did this session say before
+it was compacted" is a question only the house can answer, because the transcript on disk
+is gone.
 
 The recipe below pins `readonly=1` on every request, so a write that slips past the rule
 is refused by the server (`Code: 164 … Cannot execute query in readonly mode`) rather
@@ -115,15 +134,19 @@ DIFFERENT memhouse version are the two ways this goes quietly wrong.
 
 | Object | Kind | Columns |
 |---|---|---|
-| `sessions` | table, 1 row/session | `session_id, source, host, name, mode, folder, project, git_branch, created_at, last_updated_at, message_count, path, extra JSON, user_id, ingested_at` |
-| `messages` | table, 1 row/message | `session_id, seq, source, host, ts, role, model, input_tokens, output_tokens, cache_read_tokens, cache_write_tokens, text, project, folder, is_subagent, extra JSON, line_hash, user_id, ingested_at` + FTS columns `text_ngram`/`text_word` (lowercased; see /memhouse:search) |
-| `tool_calls` | table, 1 row/tool call | `session_id, seq, idx, source, host, tool_name, args, ts, project, folder, user_id, ingested_at` |
+| `sessions` | table, 1 row/session | `session_id, source, host, name, mode, folder, project, git_branch, created_at, last_updated_at, message_count, path, extra JSON, origin, epoch, user_id, ingested_at` |
+| `messages` | table, 1 row/message **per parse** | `session_id, seq, source, host, ts, role, model, input_tokens, output_tokens, cache_read_tokens, cache_write_tokens, text, project, folder, is_subagent, extra JSON, line_hash, origin, epoch, user_id, ingested_at` + FTS columns `text_ngram`/`text_word` (lowercased; see /mem:search) |
+| `tool_calls` | table, 1 row/tool call **per parse** | `session_id, seq, idx, source, host, tool_name, args, ts, project, folder, origin, epoch, user_id, ingested_at` |
+| `house_meta` | table, house's own record | `key, value, updated_at, updated_by, host` — `schema_version`, per-member `client_version:<user>` |
+| `house_events` | append-only log | `event_at, kind, id, status, from_version, to_version, actor, host, rows_before, rows_after, detail` — migrations, version changes |
 | the rollup | **saved query**, not an object — `memhouse sessions-query` prints it | `session_id, source, host, name, mode, folder, project, git_branch, user_id, created_at, last_updated_at, started, ended, duration_sec, total_msgs, user_msgs, assistant_msgs, subagent_msgs, models, input_tokens, output_tokens, cache_read_tokens, cache_write_tokens, user_chars, assistant_chars, first_prompt` |
 
 Notes: `source` = editor id (`claude-code`, `codex`, `cursor`, `cursor-agent`,
 `vscode`, `zed`, `opencode`, `gemini-cli`, `windsurf`, `antigravity`, …);
 `seq` = message index within its session (0-based); `tool_calls.idx` = call
-index within the session; `user_id` is server-stamped (`currentUser()`);
+index within the session; `user_id` is server-stamped (`currentUser()`); `origin` is
+`ship` for rows the shipper wrote and anything else for imports; `epoch` is which parse
+of the session a row belongs to — see the filter above;
 `models` in the rollup is an `Array(String)`. Exclude `''` and
 `'<synthetic>'` from model aggregates.
 

package/memhouse/delivery/plugin/skills/status/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: status
+description: Show the state of the memory system — what the house holds (sessions, messages, tokens per editor), how fresh it is, its schema generation and migration state, and every machine writing into it. Use when the user asks "is my memory working", "how much is stored", "when did it last ship", "what's in the house", "which machines are shipping", or before debugging why a search found nothing.
+user-invocable: true
+argument-hint: ""
+allowed-tools: Bash
+---
+
+# /mem:status — the state of the memory system
+
+**Invoking this skill IS the request. Run the report immediately — connect, run the four
+sections below, and present the summary. There are no arguments and nothing to clarify;
+do not describe this skill or ask what to check.** (Driven live, a model did exactly
+that: it summarized the file and asked "is there something specific?" — a status command
+that answers with a question has failed.)
+
+One report, four sections: what the house holds, how fresh it is, what generation it is
+at, and who writes into it. Read-only; nothing here changes anything.
+
+## Connection
+
+**Never print this file or the variables in it.** No `cat "$MH_ENV"`, no `env | grep
+MEMHOUSE`, no `set -x` around these commands. Anything you print becomes part of a
+transcript that memhouse itself ships into the house.
+
+```bash
+MH_ENV="${MEMHOUSE_HOME:-$HOME/.memhouse}/env"
+_u=${MEMHOUSE_URL-}; _s=${MEMHOUSE_USER-}; _p=${MEMHOUSE_PASSWORD-}; _d=${MEMHOUSE_DB-}
+set -a; [ -f "$MH_ENV" ] && . "$MH_ENV"; set +a
+[ -n "$_u" ] && MEMHOUSE_URL=$_u; [ -n "$_s" ] && MEMHOUSE_USER=$_s
+[ -n "$_p" ] && MEMHOUSE_PASSWORD=$_p; [ -n "$_d" ] && MEMHOUSE_DB=$_d
+if [ -z "${MEMHOUSE_URL:-}" ] || [ -z "${MEMHOUSE_USER:-}" ]; then
+  echo "no memhouse house configured — nothing in $MH_ENV and no MEMHOUSE_URL/MEMHOUSE_USER set." >&2
+  echo "Run: memhouse install" >&2
+  exit 1
+fi
+
+curl -sS --fail-with-body --user "$MEMHOUSE_USER:${MEMHOUSE_PASSWORD:-}" \
+  --data-binary @- "$MEMHOUSE_URL/?database=${MEMHOUSE_DB:-mem}&final=1&join_use_nulls=1&readonly=1" <<'SQL'
+<the query>
+FORMAT PrettyCompact
+SQL
+```
+
+## The report — run these, then summarize
+
+**1. What the house holds** — per editor, CURRENT parses only (the rooms retain
+superseded parses; an unfiltered count over-reports on any compacted session):
+
+```sql
+SELECT source,
+       uniqExact(session_id) AS sessions,
+       count() AS messages,
+       sum(input_tokens + output_tokens + cache_read_tokens + cache_write_tokens) AS tokens
+FROM messages
+WHERE origin != 'ship'
+   OR (session_id, user_id, epoch) IN (
+        SELECT session_id, user_id, max(epoch) FROM messages
+        WHERE origin = 'ship' GROUP BY session_id, user_id)
+GROUP BY source ORDER BY sessions DESC
+```
+
+**2. Freshness and coverage** — when the archive starts, ends, and last received:
+
+```sql
+SELECT formatDateTime(min(ts), '%Y-%m-%d') AS oldest,
+       formatDateTime(max(ts), '%Y-%m-%d %H:%i') AS newest,
+       formatDateTime(max(ingested_at), '%Y-%m-%d %H:%i') AS last_ingest
+FROM messages
+```
+
+A `last_ingest` hours old with the user actively working means the shipper is not
+running — say so and point at `memhouse status` / `memhouse start` on that machine.
+
+**3. Generation and migration state** — the house's record of itself (absent on a
+pre-0.10 house; that absence is itself the answer: say the house predates the record):
+
+```sql
+SELECT key, value FROM house_meta FINAL
+WHERE key IN ('schema_version', 'min_writer_schema') ORDER BY key
+```
+```sql
+SELECT id, argMax(status, event_at) AS status,
+       formatDateTime(max(event_at), '%Y-%m-%d %H:%i') AS at
+FROM house_events WHERE kind = 'migration' GROUP BY id ORDER BY at DESC LIMIT 3
+```
+
+A `pending` here with nothing running means an interrupted migration — name
+`memhouse migrate` (it refuses stale leftovers legibly rather than clobbering them).
+
+**4. The fleet** — every machine writing into this house, from the DATA (a pre-0.10
+writer records nothing about itself, so rows-without-record is the finding):
+
+```sql
+SELECT user_id, host, count() AS rows,
+       formatDateTime(max(ingested_at), '%Y-%m-%d %H:%i') AS last_write
+FROM messages GROUP BY user_id, host ORDER BY last_write DESC
+```
+```sql
+SELECT key, value FROM house_meta FINAL
+WHERE key LIKE 'client_version:%' OR key LIKE 'client_schema:%' OR key LIKE 'last_ship:%'
+```
+
+Match `client_*:<member>@<host>` against the data rows. A `(user_id, host)` pair with
+rows but NO `client_*` record is a **pre-0.10 memhouse still writing** — flag it: its
+re-ships delete retained parses, and the fixes are upgrade it or (as admin)
+`REVOKE ALTER DELETE, ALTER UPDATE ON <db>.* FROM <member>`.
+
+## Presenting it
+
+Lead with one line of verdict ("healthy: N sessions across M editors, last ingest X
+minutes ago" — or the one thing wrong). Then the per-editor table, then anything from
+sections 3–4 that needs action. Skip empty sections; do not pad. If the house is
+unreachable, say which URL refused and stop — never guess another endpoint.

package/memhouse/delivery/plugin/skills/users/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: users
+description: Show the people around your memory — who writes into your house and from which machines, which other houses on this ClickHouse you can read, and who can read yours. Use when the user asks "who can see my memory", "whose memory can I see", "which houses are on this server", "who else ships here", or before/after sharing with /mem:share.
+user-invocable: true
+argument-hint: ""
+allowed-tools: Bash
+---
+
+# /mem:users — who is around your memory
+
+**Invoking this skill IS the request. Run the report immediately and present it; there
+are no arguments and nothing to clarify.** Read-only throughout.
+
+Throughout, `<your-db>` is the live `$MEMHOUSE_DB` and `<your-user>` the live
+`$MEMHOUSE_USER` — take both from the connection environment, never from the
+conversation or from examples.
+
+Answers three questions, best-effort by design: ClickHouse shows a credential only what
+it may see, so on someone else's server some sections legitimately come back thin — say
+what could not be seen rather than guessing.
+
+## Connection
+
+**Never print this file or the variables in it.** No `cat "$MH_ENV"`, no `env | grep
+MEMHOUSE`, no `set -x` around these commands.
+
+```bash
+MH_ENV="${MEMHOUSE_HOME:-$HOME/.memhouse}/env"
+_u=${MEMHOUSE_URL-}; _s=${MEMHOUSE_USER-}; _p=${MEMHOUSE_PASSWORD-}; _d=${MEMHOUSE_DB-}
+set -a; [ -f "$MH_ENV" ] && . "$MH_ENV"; set +a
+[ -n "$_u" ] && MEMHOUSE_URL=$_u; [ -n "$_s" ] && MEMHOUSE_USER=$_s
+[ -n "$_p" ] && MEMHOUSE_PASSWORD=$_p; [ -n "$_d" ] && MEMHOUSE_DB=$_d
+if [ -z "${MEMHOUSE_URL:-}" ] || [ -z "${MEMHOUSE_USER:-}" ]; then
+  echo "no memhouse house configured — nothing in $MH_ENV and no MEMHOUSE_URL/MEMHOUSE_USER set." >&2
+  echo "Run: memhouse install" >&2
+  exit 1
+fi
+
+curl -sS --fail-with-body --user "$MEMHOUSE_USER:${MEMHOUSE_PASSWORD:-}" \
+  --data-binary @- "$MEMHOUSE_URL/?database=${MEMHOUSE_DB:-mem}&readonly=1" <<'SQL'
+<the query>
+FORMAT PrettyCompact
+SQL
+```
+
+## The report
+
+**1. Who writes into YOUR house** — members × machines, from the data (same ground truth
+as /mem:status's fleet):
+
+```sql
+SELECT user_id AS member, host AS machine, count() AS rows,
+       formatDateTime(max(ingested_at), '%Y-%m-%d %H:%i') AS last_write
+FROM messages GROUP BY user_id, host ORDER BY last_write DESC
+```
+
+**2. Whose memory YOU can read** — every database your credential reaches is one someone
+gave you (or your own):
+
+```sql
+SHOW DATABASES
+```
+
+Drop `system`, `information_schema`, `INFORMATION_SCHEMA`, `default` unless they hold
+rooms. For each OTHER house listed, it is readable because of a grant — one line each:
+`house 'polat' — readable (shared with you); query it as polat.messages`.
+
+**3. Who can read YOURS** — from the house's own share record (`system.grants` needs
+privileges a member does not hold, so the record /mem:share keeps is the readable
+source; an admin-issued grant will not appear in it, and the report should say so):
+
+```sql
+SELECT substring(key, 7) AS user, value AS state
+FROM house_meta FINAL WHERE key LIKE 'share:%' ORDER BY key
+```
+
+`granted …` = a live read window (`/mem:share`); `revoked …` = closed. If the caller IS
+privileged, prefer the authoritative form:
+`SELECT user_name, groupUniqArray(access_type) FROM system.grants WHERE database = '<your-db>' AND user_name != '<your-user>' GROUP BY user_name`
+— try it first, fall back to the record on refusal.
+
+**4. Every user on the server** — usually admin-only; try it, and if refused say
+"(full user list needs admin — showing only what this credential can see)":
+
+```sql
+SELECT name FROM system.users ORDER BY name
+```
+
+## Presenting it
+
+Four short sections in that order, each with its one-line meaning ("2 machines ship into
+your house", "you can read polat's memory", "yigit can read yours — read-only", …).
+Empty section three means "no shares made through /mem:share" — and ONLY that. The
+record cannot see an admin-issued grant, so never promise "nobody can read your memory"
+from an empty ledger; say "no shares recorded through this skill — the authoritative
+check is the admin's system.grants query" and print it. Point at `/mem:share <user>` /
+`/mem:share revoke <user>` for changes.

package/memhouse/house/HOUSE.md

@@ -42,9 +42,9 @@ all — but when it does (the same `~/.claude` on two synced machines), both shi
 the same `(session_id, user_id)`. The keys deliberately do NOT include `host`, so the
 rows collapse to the LAST shipper's copy: one logical session stays one session, with
 `host` recording who shipped it most recently. Keying on host instead would duplicate
-every such session and double what the rollup counts. An interleaved clear+insert
-between the two shippers can transiently drop rows; the next pass's skip predicate sees
-the count mismatch and re-ships — self-healing, at the price of churn. Truly parallel
+every such session and double what the rollup counts. Two shippers interleaving can no
+longer drop rows — neither of them deletes anything — but they can disagree about the
+epoch and fork a session that did not change; the next pass settles it. Truly parallel
 shippers per user are the deferred "ephemeral fingerprint" expert feature, not today's.
 
 ## The rollup is a saved query, not an object
@@ -69,6 +69,41 @@ product does not have:
   housemates are collaborators, and groups that are not do not share a database.
 
 The origin story that survives: rows carry `origin` (in the messages/tool_calls sorting
-keys, deliberately NOT in sessions'), the shipper's clear binds
-`(session_id, user_id, origin='ship')`, and imported history survives every re-ship.
+keys, deliberately NOT in sessions'), so ReplacingMergeTree cannot collapse an imported
+row against a shipped one and imported history survives every re-ship.
+
+## One session, more than one parse
+
+`messages` and `tool_calls` also key on `epoch`. The shipper is insert-only: when a
+re-parse is SHORTER than what the house holds, or differs from it at a `seq` the house
+already has, it writes the new parse under `epoch + 1` and leaves the old one intact.
+Both are ordinary — Claude Code compacts a transcript in place and deletes it after
+`cleanupPeriodDays` (30 by default), so the house is routinely the only surviving copy.
+An unchanged re-ship reuses the epoch and costs nothing.
+
+Reads must therefore take the newest epoch per `(session_id, user_id)` for `origin='ship'`
+rows and leave every other origin alone (an import sits at epoch 0 forever). Nobody writes
+that filter by hand: `roomNames()` resolves `messages` and `tool_calls` to a subquery that
+already applies it, and hands out the bare tables only as `messages_raw` / `tool_calls_raw`
+for writes and DDL.
+
+## The house's own record
+
+Two tables that are not rooms:
+
+- `house_meta` — house-wide key/value, latest-wins: `schema_version`, and the memhouse
+  version each member last shipped with.
+- `house_events` — append-only: migrations (`pending` → `applied` | `failed`), version
+  changes, schema observations, each with actor, host and row counts. Nothing is updated
+  in place, so a migration that failed and was retried reads as exactly that.
+
+What lives there is what `system.tables` and `system.users` cannot say — intent, sequence,
+outcome. Which rooms and users exist is read live from `system.*`, never mirrored.
+
+Sorting keys cannot be altered, so a schema generation change is a room rebuild:
+`memhouse migrate-rooms` copies each room into one with the current key, swaps it in with
+a single `RENAME`, and keeps the old room as `<room>_pre_epoch`. It deletes nothing and
+carries `user_id` across explicitly, so a housemate's rows are not restamped as the
+migrator's.
+
 See the comments in `schema.sql.tpl` — they are the authority on the keys.