memhouse 0.3.2 → 0.4.2

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

@@ -0,0 +1,174 @@
+# per-member rooms
+**v6 reverts one decision v5 made under review pressure.** v5 gave every member a stored
+`sessions_v`. SCHEMA v4 had already decided that the rollup is a *saved query*, and
+overriding that reactively — inside a review round, to fix a read-layer finding — cost a
+name inside the Merge selector's namespace (161 sessions counted as 322), a rename, a
+reserved prefix, a fourth grant and a fourth object to provision and roll forward. The
+query is back. SCHEMA v5 records the detour in full.
+
+**v5 corrects the grant set, adds the member's own view, and stops calling this a
+skeleton.** Four changes:
+
+1. The grant set was `SELECT, INSERT`, which is insufficient — the shipper clears a
+   session's rows before re-inserting, so every incremental pass needs both
+   `ALTER UPDATE` and `ALTER DELETE` (which of the two is demanded varies by server
+   version). The error surfaced only on the *second* ship of a *changed* session, which is
+   why four document versions carried it. See PROVISIONING v5.
+2. The delete predicate **must bind the user** rather than call `currentUser()`. A mutation
+   does not evaluate it in the caller's context, so the delete matched nothing and removed
+   nothing, silently. Measured on 25.11 and on chdb; it affected the shared layout too.
+3. The read layer resolves the rollup as **SQL text** rather than a name: the stored view
+   in the shared layout, a subquery over the caller's rooms in the per-member one. Without
+   that resolution a per-member house ships fine and reads back nothing.
+4. v1–v4 were design skeletons. This one is implemented and measured: `rooms.js`,
+   `provision.js`, the two DDL templates, and room routing through the read layer.
+
+## The model
+
+House **`mem`**. Three rooms per member:
+
+```
+mem.sessions_<member>
+mem.messages_<member>
+mem.tool_calls_<member>
+```
+
+Owner-managed Merge rooms for team-wide reads:
+
+```sql
+mem.all_sessions    = Merge('mem', '^sessions_')
+mem.all_messages    = Merge('mem', '^messages_')
+mem.all_tool_calls  = Merge('mem', '^tool_calls_')
+```
+
+Canon: house = database, room = table, member = a registered user with grants.
+
+## Why
+
+**Isolation is structural.** A grant that is absent exposes nothing; a row policy has to
+be correct on every room for every role, and one wrong predicate exposes everything. It
+fails closed.
+
+**Sharing is self-serve.** A member holding grant-option on their own rooms shares with a
+colleague directly. Under row policies the same act needs `CREATE ROW POLICY`, which the
+kernel withholds from agency owners.
+
+**Personal reads stop paying for everyone else.** The shared rooms order
+`(session_id, user_id, seq)`, so filtering by member cannot prefix-scan. At a hundred
+members every personal query and full-text lookup scans roughly 100× what it needs.
+
+**Per-member lifecycle is atomic** — delete, export, retention, and quota are per-room
+operations rather than mutations across a shared table.
+
+## Grants
+
+Two statements per room, six per member, explicit — plus SELECT on the Merge rooms.
+`PROVISIONING.md` is the authority; this is the shape:
+
+```sql
+GRANT ALL    ON mem.sessions_<m>   TO <m>;
+GRANT SELECT ON mem.sessions_<m>   TO <m> WITH GRANT OPTION;
+-- and the same pair for messages_<m> and tool_calls_<m>
+```
+
+**The split is the point.** `ALL` covers the mutation privileges the shipper's re-ship
+needs without naming them — clear-then-insert, so a growing transcript cannot leave a
+stale `seq` tail when a re-parse yields fewer rows, and which of `ALTER UPDATE` /
+`ALTER DELETE` a server demands varies by version. Grant-option is attached to the
+`SELECT` statement and **not** to the `ALL` one, so a share is read-only by construction:
+a member cannot hand a colleague `DROP TABLE` while meaning "let them read my sessions".
+Never `ON mem.*` — see PROVISIONING.
+
+## What stays
+
+- `user_id MATERIALIZED currentUser()` on every room; `async_insert=0` on writers.
+- Typed columns, `extra JSON`, `ReplacingMergeTree(ingested_at)`, `final=1` reads, both
+  full-text layers on messages.
+- Parse-on-client; the shipper runs the 17 adapters and writes typed rows.
+- `sessions_v` as a **saved query** run under the caller, not a stored view — the v1–v4
+  decision, restored. The read layer resolves it as text in the same place it resolves a
+  room name, so the rollup and the rooms travel through one substitution point.
+- The REST contract and the borrowed dashboard.
+
+## Measured facts (ClickHouse 26.7.1)
+
+1. Members **self-provision** inside their own prefix and are denied outside it.
+2. `Merge` **fails closed on permissions** — a caller sees only the underlying rooms they
+   hold grants for, with no leak and no error. This requires SELECT on the Merge room
+   ITSELF: without it the team room denies outright instead of narrowing, which is a
+   different and worse behaviour. Provisioning grants it (re-measured on 25.11).
+3. `Merge` **auto-discovers** rooms created after it exists.
+4. `Merge` **tolerates schema drift**, returning a column's default for rooms lacking it —
+   so schema rollout is progressive, not lock-step. It **rejects mutations**; use
+   `ADD COLUMN`, Merge room first.
+5. Row-policy rights are **house-scopeable** (`GRANT ACCESS MANAGEMENT ON mem.*`). Owner
+   only — the scope is the house, not a room.
+6. **`EXECUTE AS` exists**, changes `currentUser()`, and is a grantable privilege denied to
+   members by default.
+7. **The shipper needs both mutation grants** on its own rooms, or incremental passes
+   fail — 26.7 named `ALTER DELETE`, 25.11 named `ALTER UPDATE(_row_exists)`. New in v5.
+8. **`currentUser()` in a mutation predicate matches nothing.** A `DELETE` filtered on
+   `user_id = currentUser()` removed 0 rows where the same predicate with the bound value
+   removed 2000 — on ClickHouse 25.11 and on chdb alike, with no error either time. New
+   in v5.
+
+## Measured end-to-end (the implementation, not the design)
+
+On ClickHouse 25.11, two members, real local session stores:
+
+- alice ships 161 sessions / 22,413 message rows / 16,197 tool rows into her own rooms;
+  bob's rooms are untouched.
+- alice reading **or writing** bob's rooms is denied, and so is reading bob's view.
+- the whole read layer resolves: 13 of 14 dashboard query functions run green against
+  per-member rooms (the fourteenth needs a SQL argument), and `status`, `search`, `doctor`,
+  `stats` all report alice's own data. The same queries against the shared names fail with
+  `UNKNOWN_TABLE`, which is what they did before this change.
+- a planted stale `seq` tail is cleared by the next re-ship, which is what the two ALTER
+  grants exist for.
+- the whole gauntlet scenario's SQL assertions pass when run by hand against a two-member
+  house: 22,413 rows in alice's room, none unstamped, none in bob's, bob reading the team
+  Merge room sees zero of alice's, alice sees her own. Sharing round-trips: alice's
+  `GRANT` widens bob's Merge view to 22,413 and her `REVOKE` returns it to zero, with the
+  direct read denied again.
+- the shared-room layout has been removed; this is the only layout.
+
+## `user_id` — what it guarantees
+
+Unforgeable **by a member**, since members do not hold `EXECUTE AS`. Forgeable by the
+owner or any grantee. The trust boundary is the owner, not the engine — the normal
+arrangement, but do not overstate it anywhere user-facing. **Members must never hold
+`EXECUTE AS`.**
+
+## Phases
+
+1. Schema + naming — room DDL template, key order, Merge rooms. **Done.**
+2. Provisioning — kernel capability and standalone path. **Standalone done**
+   (`provision.js`); the kernel capability is not written.
+3. Query layer — the member view and room-name resolution. **Done** — `rooms.js` plus
+   templated room names through `queries.js`, `ship.js` and the CLI.
+4. Sharing — room-level self-serve; row-level via the owner. **Room-level proven**;
+   row-level not implemented.
+
+Migration is not a phase and must not shape MVP decisions.
+
+## Open questions
+
+- **May members create and drop their own rooms?** Works, safely scoped; but a member
+  could drop their own memory and schema rollout stops being central. Deferred with the
+  uninstall/drop work.
+- **Key order** — is `user_id` still worth an `ORDER BY` slot now the room is the tenant?
+- **Standalone path** — a user with no kernel is both owner and member; one credential or
+  two?
+- **Is `EXECUTE AS` scopeable** to `mem.*` rather than `*.*`? Bounds what an owner
+  credential can impersonate.
+- ~~**Should a share be `SELECT`-only?**~~ **RESOLVED.** Grant-option is attached to the
+  member's `SELECT` grant and not to their `ALL` grant, so a share can only ever be
+  read-only. Measured on 26.7.2: `GRANT SELECT … TO bob` succeeds,
+  `GRANT DROP TABLE … TO bob` is refused 497.
+
+## Out of scope
+
+- Migration. Deferred; unblocked in principle by `EXECUTE AS`.
+- `agent_id` / crew identity. Within a crew sharing one credential an agent tag is
+  client-supplied and is not a security boundary.
+- Adapters, REST contract, dashboard.

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

@@ -0,0 +1,177 @@
+# PROVISIONING — minting a member and their rooms
+
+Two statements per room, six per member, and no seventh for the rollup: the session
+rollup is a saved query over exactly these rooms, so a member who can read them can run
+it. See [INSTALL.md](INSTALL.md) for the three ways this gets applied.
+
+## A note on names before the SQL
+
+The house is `mem`. `provision.js`, the shipper, the read layer and the CLI all default to
+it, so the SQL below is what a default install actually provisions. The owner is
+`memhouse_root` — the **database** was shortened to `mem`, the owning role was not.
+
+They must agree or rooms get provisioned somewhere the product never reads. Override with
+`MEM_DB` / `MEM_USER` (or the `MEMHOUSE_*` equivalents); `provision.js` prints the
+connection it resolved so a mismatch is visible rather than silent.
+
+An install predating this default carries `MEMHOUSE_DB` in `~/.memhouse/env`, and explicit
+config outranks the default, so nothing repoints you at a different house. **That does not
+mean a 0.3.x house keeps working** — the database name survives the upgrade, the tables do
+not. See [INSTALL.md](INSTALL.md#upgrading-from-03x--read-this-before-you-do).
+
+## The grant set
+
+Two statements per room. The split is the point.
+
+```sql
+GRANT ALL    ON mem.sessions_<m>   TO <m>;
+GRANT SELECT ON mem.sessions_<m>   TO <m> WITH GRANT OPTION;
+GRANT ALL    ON mem.messages_<m>   TO <m>;
+GRANT SELECT ON mem.messages_<m>   TO <m> WITH GRANT OPTION;
+GRANT ALL    ON mem.tool_calls_<m> TO <m>;
+GRANT SELECT ON mem.tool_calls_<m> TO <m> WITH GRANT OPTION;
+```
+
+Plus `SELECT` on whichever Merge rooms exist, which is what makes the team room narrow to
+the caller's own rooms instead of denying outright.
+
+**`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
+below without naming them, which is what stops the version-dependent trap.
+
+**`SELECT`, re-grantable.** A share is read-only **by construction**. `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:
+`GRANT SELECT … TO bob` succeeds, `GRANT DROP TABLE … TO bob` is refused 497, and the
+member can still drop their own room.
+
+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.
+
+### Why the mutation grants are not optional
+
+v4 said `SELECT, INSERT`. A member provisioned that way ships **once** and then fails on
+every subsequent pass.
+
+Both `ALTER` privileges are needed, and **which one bites depends on the server version**.
+`DELETE FROM` is a *lightweight* delete, implemented as
+`ALTER TABLE ... UPDATE _row_exists = 0`: ClickHouse 26.7 refused it for want of
+`ALTER DELETE`, and 25.11 refused the same statement for want of
+`ALTER UPDATE(_row_exists)`. Granting the one you happened to test against produces a
+member who cannot ship on the other server, so grant both.
+
+The shipper is not append-only. A session file grows while the agent works, so each pass
+re-parses the whole transcript and re-ships it; to keep that idempotent it **clears the
+session's existing rows and re-inserts them**. `ReplacingMergeTree(ingested_at)` collapses
+duplicates by key eventually, but it cannot remove a row the new parse no longer produces —
+a re-parse that yields fewer rows would otherwise leave a stale `seq` tail behind forever.
+So the clear is a real `ALTER TABLE ... DELETE`, and without the privilege the first
+incremental pass dies with
+
+```
+Not enough privileges. To execute this query, it's necessary to have the grant
+ALTER UPDATE(_row_exists) ON mem.messages_<m>
+```
+
+The failure is invisible in a first-run test, which is exactly why it survived four
+document versions: provision, ship, count rows, declare victory. It only appears on the
+*second* ship of a *changed* session.
+
+### The delete predicate must bind the user, not call `currentUser()`
+
+Related, and worse, because it fails **silently**. The clear was written as
+
+```sql
+DELETE FROM messages_<m> WHERE session_id = {id:String} AND user_id = currentUser()
+```
+
+A mutation does not evaluate `currentUser()` in the caller's context. Measured on
+ClickHouse 25.11 and on chdb: the identical predicate with the literal value deleted 2000
+rows where `currentUser()` deleted **0** — no error, no warning, nothing in the log. The
+stale tail the delete exists to remove simply survives. The value is bound instead, read
+from the server over the same connection, so it is the same identity with none of the
+context dependence. This affected the **shared** layout too, and predates this fork.
+
+### What the privilege lets a member do
+
+Delete and mutate rows in their own rooms. That is their own memory, and they can already
+overwrite it by re-shipping — so this widens what a member can destroy about themselves,
+and nothing about anyone else. Grants remain per-room and explicit, so `ALTER DELETE` on
+`messages_alice` says nothing about `messages_bob`.
+
+`DROP TABLE` is included too (see below): a member can remove their own room, not just
+empty it.
+
+### Consequence of `WITH GRANT OPTION`
+
+Grant-option covers every privilege **in the statement it is attached to**, which is why
+it is attached to the `SELECT` statement and not the `ALL` one. Alice can hand bob read
+access to `messages_alice` and nothing else; she cannot hand him the mutation or drop
+rights even by mistake. The convention `SHARING` describes is now enforced by the engine
+rather than by everyone remembering it.
+
+A share is the three rooms and nothing else. The recipient runs the same rollup query over
+them under their own credential, so there is no fourth grant to forget — which is the
+concrete reason the query beat the view.
+
+`WITH GRANT OPTION` is what makes whole-room sharing self-serve. Without it every share
+becomes an operator ticket, which is most of the reason this fork exists.
+
+The owner (`memhouse_root` — the house was shortened to `mem`, the owning role was not)
+holds `ALL ON mem.* WITH GRANT OPTION`, so a second member joining
+an existing house needs no new owner setup — house, owner, and Merge rooms are already
+there.
+
+**RESOLVED:** the member does get `CREATE TABLE` / `DROP TABLE` on their own rooms — it
+is inside `ALL`. That is what lets `--ensure-schema` run as the member and makes the solo
+install one command with no owner involvement. The cost is accepted: a member can drop
+their own memory. The thing that was actually worth preventing — a member handing those
+rights to someone else — is prevented by the grant-option split above.
+
+## Kernel path
+
+**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.
+
+What is settled regardless: the room layout, the grant set above, and the identity rule
+(the ClickHouse user is the identity). What is open is only who plays admin and how the
+handle is chosen. Whatever that turns out to be, provisioning wants to be ONE idempotent
+step — three rooms plus their grants — because it is also the hook for rolling a schema
+change across rooms.
+
+Nothing touches the Merge rooms on member join: they are a regex over room names and
+**auto-discover** rooms created after them.
+
+## Standalone path
+
+No kernel, so no capability layer; the CLI performs the same steps. `provision.js` is that
+path today: it creates 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),
+then the rooms, then the grants.
+
+> **OPEN:** a standalone user is simultaneously owner and member. One credential holding
+> both roles, or two? Today's `memhouse install` assumes a single credential that owns
+> everything, which no longer maps cleanly.
+
+## Row-policy rights
+
+`GRANT ACCESS MANAGEMENT ON mem.*` expands to
+`CREATE/ALTER/DROP/SHOW ROW POLICY ON mem.*` — house-scoped, no global access management
+required. This is what lets the owner serve partial-share requests.
+
+**Owner only.** The scope is the house, not a room, so any holder could attach a policy to
+another member's rooms. Policies filter rather than grant, so it is not a data leak — but
+it is a denial of service on a colleague's own reads.
+
+## `EXECUTE AS`
+
+Owner may hold it; **members must not**. It changes `currentUser()`, so a member holding
+it could write rows stamped as someone else and defeat the provenance the schema relies
+on.
+
+## Not yet written
+
+- the capability script
+- member removal: drop the three rooms, revoke, and decide what happens to rooms they had
+  shared outward

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

@@ -0,0 +1,48 @@
+# per-member rooms
+
+**One house, a set of rooms per member.** This replaced a shared layout — three rooms
+named `sessions`/`messages`/`tool_calls` for everyone, separated by row policies — which
+has been removed. There is no switch and no fallback: this is the data model.
+
+**The design is implemented** — `rooms.js`, `provision.js`, the two DDL templates, and
+room routing through the read layer — and proven end to end on ClickHouse 26.7.1 and
+25.11.
+
+| Document | What |
+|---|---|
+| [`PLAN.md`](PLAN.md) | the model, why, phases, measured facts |
+| [`PROVISIONING.md`](PROVISIONING.md) | the grant set (three per member), kernel capability, standalone path |
+| [`SCHEMA.md`](SCHEMA.md) | room naming, shapes, sort keys, Merge rooms, and why `sessions_v` is a saved query |
+| [`SHARING.md`](SHARING.md) | whole-room self-serve (three grants), partial rows via the owner |
+
+These four documents describe the design as it stands. Earlier revisions are in
+`git log`, not in this directory — a superseded document kept beside the current one is a
+contradiction waiting to be quoted, and this directory produced two review findings that
+way before the versions were removed.
+
+## The one-paragraph version
+
+The house is **`mem`**. Each member gets `mem.sessions_<member>`, `mem.messages_<member>`,
+`mem.tool_calls_<member>`, with three grants over them —
+`SELECT, INSERT, ALTER UPDATE, ALTER DELETE`, all `WITH GRANT OPTION`. The session rollup
+is a saved query over those same rooms, not a fourth object. Isolation stops
+being a row policy that must be right everywhere and becomes a grant that is simply
+absent — it fails closed. Sharing a whole room needs no operator. Team-wide reads come
+from `Merge` rooms anchored on the room type (`^messages_`), which reduce to each caller's
+own grants, auto-discover new members, and tolerate schema drift — provided the caller
+holds `SELECT` on the Merge room itself, which provisioning issues; without it the team
+room denies instead of narrowing.
+`user_id MATERIALIZED currentUser()` stays on every room: unforgeable by members, who are
+not granted `EXECUTE AS`.
+
+## Biggest open questions
+
+1. **May members create and drop their own rooms?** It works and is safely scoped, but it
+   lets a member drop their own memory and makes schema rollout non-central.
+2. **Key order** — is `user_id` still worth an `ORDER BY` slot now the room is the tenant?
+3. **Standalone path** — a user with no kernel is both owner and member; one credential or
+   two?
+4. **Is `EXECUTE AS` scopeable** to `mem.*` rather than `*.*`?
+5. **Is a saved rollup enough for agents?** It has no name to type. `memhouse
+   sessions-query` prints it, which is a worse affordance than a name and the price of
+   having nothing to own, grant or collide.

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

@@ -0,0 +1,73 @@
+# SCHEMA — rooms, keys, Merge rooms, the rollup
+The room shapes, keys and Merge rooms are
+unchanged. What changes is that v4's decision about `sessions_v` — *a saved query, not a
+room* — is now the implemented one, after a detour through a stored view that this
+version records rather than hides.
+
+## `sessions_v` is a saved query, not a room
+
+v4 said so. Round 1 of the review campaign implemented it as a **stored view** instead —
+reactively, to fix a finding that the read layer named the shared rooms — without going
+back to this file. Everything that followed was the cost of that override:
+
+- the view needed a name, and `sessions_v_<m>` sits inside the `^sessions_` pattern the
+  Merge rooms select on. `all_sessions` silently absorbed every member's aggregate view
+  alongside their base room: **161 sessions counted as 322**.
+- so the name moved to `v_sessions_<m>`, which then needed a reserved prefix so no member
+  handle could re-create the collision;
+- and a fourth grant per member, because a recipient given the three rooms could read rows
+  and use none of the product's read paths;
+- and a fourth object to create, roll forward, check in `doctor`, and eventually drop.
+
+None of that buys anything the query does not already do. Reverted.
+
+### What it is now
+
+`rooms.js` exposes `sessions_v` as **SQL text** — a parenthesised `SELECT` over the
+caller's own rooms. It drops into the same `FROM … AS c` position a view name would have
+occupied, so the read layer treats it as just another resolved room name and the
+substitution point is one function. (The shared layout, where this key resolved to a
+stored view's *name*, is gone; the text form is the only one now.)
+
+```sql
+FROM {{sessions_v}} AS c        -- resolves to:  FROM ( SELECT … FROM sessions_alice … ) AS c
+```
+
+It runs **under the caller's credential**, substituted with the caller's own room names,
+so it inherits their grants exactly and raises no view-ownership question at all.
+
+### The two properties that had to survive
+
+- the join is a **LEFT JOIN**, so a session with no messages still appears with zero
+  aggregates instead of vanishing from every count;
+- `join_use_nulls = 1` makes the unmatched message columns NULL, so `coalesce` yields true
+  zeros rather than counting the placeholder row.
+
+The view carried the second as a trailing `SETTINGS` clause. **A subquery cannot**, so it
+moved to the caller: `READ_SETTINGS = { final: 1, join_use_nulls: 1 }`, applied by the
+dashboard client, the shipper and the CLI's raw HTTP alike. A unit check asserts the text
+carries no `SETTINGS` of its own, because putting it back would break every read that uses
+the rollup.
+
+### The cost, stated plainly
+
+An agent writing ad-hoc SQL has no name to type. `memhouse sessions-query` prints the
+rollup resolved for whoever the configured credential is, and the three delivery skills
+point at it. That is a worse affordance than a name, and it is the price of the property
+that made v4 choose a query: nothing to own, nothing to grant, nothing in a namespace.
+
+## Room naming, keys, Merge rooms
+
+Unchanged from v4. Rooms are type-first — `sessions_<m>`, `messages_<m>`,
+`tool_calls_<m>` — so the Merge rooms anchor on a fixed room type and never match
+themselves. With the view gone, `^sessions_` now matches **only** base session rooms,
+which is what it was always supposed to mean.
+
+> **OPEN** (carried from v4): is `all_sessions` a Merge over the member `sessions_*`
+> rooms, or a saved query over `all_messages`? The first is cheaper; the second guarantees
+> the aggregates match the per-member rollup exactly.
+
+## Not yet written
+
+- the kernel capability that provisions a member
+- member removal: drop the three rooms, revoke, decide what happens to rooms shared outward

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

@@ -0,0 +1,102 @@
+# SHARING — two tiers
+
+**A share is three grants**, one per room, and there is no fourth: the rollup is a saved
+query over exactly those rooms rather than a stored object, so a recipient who can read
+the rooms can run it.
+
+A share is also **read-only by construction**. `WITH GRANT OPTION` is attached to the
+member's `SELECT` grant and not to their `ALL` grant ([PROVISIONING](PROVISIONING.md)),
+so alice cannot hand bob mutation or drop rights on her room even by mistake.
+
+## Tier 1 — whole room, self-serve
+
+A member holds `WITH GRANT OPTION` on their own three rooms — there is no fourth object
+to hold anything on — so they share without an operator:
+
+```sql
+GRANT SELECT ON mem.messages_alice   TO bob;
+GRANT SELECT ON mem.sessions_alice   TO bob;
+GRANT SELECT ON mem.tool_calls_alice TO bob;
+```
+
+**Three statements.** The rollup every read path uses is a saved query over exactly these
+rooms, run under the recipient's own credential — so a recipient who can read the rooms
+can run it, and there is no fourth grant to forget. That is the concrete payoff of the
+query over the view, and it is why SCHEMA v4 chose it before the implementation briefly
+went the other way.
+
+`memhouse sessions-query` prints the rollup for whoever is connected, which is what a
+recipient pastes into a `FROM (...) AS c` when writing ad-hoc SQL.
+
+This is the tier per-member rooms exist to enable. Under a row policy the same act needs
+`CREATE ROW POLICY`, which members do not have and the kernel withholds from agency
+owners by default.
+
+Bob reading `messages_alice` sees `user_id = 'alice'` on every row. That stamp is
+unforgeable **by members**, since `EXECUTE AS` is a grantable privilege they do not hold,
+and forgeable by the owner or anyone granted it. Trust boundary is the owner, not the
+engine.
+
+Bob's Merge-room reads widen automatically once alice grants him a room — `Merge` reduces
+to the caller's actual grants, so nothing else needs changing. Measured end to end on
+25.11: alice's `GRANT` took what bob sees of her rows through `all_messages` from 0 to
+22,413, and her
+`REVOKE` returned it to 0, and his direct read was denied again.
+
+**A member must hold SELECT on the Merge rooms themselves** for any of that to work —
+provisioning issues it. Without that grant the team room does not narrow to what the
+caller can read, it denies outright, which looks identical to isolation and is not.
+
+### Grant-option covers the whole grant
+
+Alice's grant-option is over `SELECT, INSERT, ALTER UPDATE, ALTER DELETE`, so she *can*
+hand bob the mutation rights on her own rooms, not merely `SELECT`. Her data, her call —
+but a share is `SELECT`-only by convention, and nothing in the engine enforces the
+convention. A `share` verb should encode it.
+
+> **OPEN:** a `share` / `unshare` CLI verb wrapping the three grants, so a member never
+> types SQL. Mirrors memory-house's `mh-share`.
+
+## Tier 2 — some rows, owner-mediated
+
+Row policies remain the only way to share a *subset*. The member asks the owner, who
+holds house-scoped policy rights:
+
+```sql
+GRANT SELECT ON mem.messages_alice TO bob;                -- privilege
+CREATE ROW POLICY share_alice_to_bob ON mem.messages_alice
+  FOR SELECT USING <predicate> TO bob;                    -- restriction
+```
+
+Both halves are required: a policy filters, it never grants. Privilege without a policy
+shares everything; a policy without privilege shares nothing.
+
+> **OPEN:** which predicates — by project, by date range, by `source`? Free-form SQL from
+> a member is an injection surface, so this likely wants a small fixed vocabulary.
+
+> **OPEN:** what a partial recipient's rollup should show. The rollup is a saved query
+> over `sessions_alice` and `messages_alice`, so a policy on `messages_alice` filters the
+> rows it aggregates and the recipient sees totals computed over their own slice — which
+> is arguably right, and is untested. Nothing extra has to be shared for it to work,
+> which is one fewer moving part than the stored view had.
+
+## Why the tiers are asymmetric
+
+Deliberate. Whole-room sharing is the common case, is coarse, and is safe to self-serve —
+the worst outcome is oversharing your own data. Partial sharing writes a filter into the
+house's access model, so it goes through the owner.
+
+## What sharing does not do
+
+**It is not a boundary between agents sharing one credential.** A crew running under a
+single member credential reads and writes the same rooms; any per-agent tag is
+client-supplied. Enforced separation needs separate ClickHouse users, which means
+separate rooms — this design one level down. Deferred with `agent_id`.
+
+## Not yet written
+
+- `memhouse share <member>` / `unshare`
+- how the dashboard and skills list rooms a caller can read but does not own — filter
+  `system.tables` by grants (it *is* grant-filtered: alice sees exactly her own three
+  three rooms, measured), or read the Merge rooms and group by `_table`
+- revocation when a member is removed while their rooms are shared outward