memhouse 0.18.12 → 0.20.1

package/memhouse/share.js

@@ -24,6 +24,8 @@ const SCOPE_COLUMNS = {
   folder: { column: () => 'folder', quote: true },
   host: { column: () => 'host', quote: true },
   source: { column: () => 'source', quote: true },
+  // Schema 3 names the editor `harness`; `source=` means the same there.
+  harness: { column: () => 'harness', quote: true },
   // `sessions` has no `ts`; its clock is `created_at`. One literal predicate cannot span
   // the rooms, so time scopes render per room.
   since: { column: (room) => (room === 'sessions' ? 'created_at' : 'ts'), op: '>=' },
@@ -61,4 +63,688 @@ function policyName(user, room) {
   return `mh_share_${user}_${room}`;
 }
 
-module.exports = { SCOPE_COLUMNS, parseScope, scopePredicate, policyName };
+// ── schema 3 (memhouse 0.20) ───────────────────────────────────────────────────────────────
+// A share is SELECT on exactly the member's six conversation tables (harness-sessions-sql's profile) —
+// never a wildcard (a 0.18 full share's `<m>_*` also reached meta, events and the stat tables) and
+// never the archive database. A scope is a row policy on each of the six. Revoking takes back the
+// grants AND the policies: a policy left behind would quietly narrow a later re-share.
+
+const V3_TABLES = ['session_parts', 'session_usage', 'session_links', 'session_lifecycle', 'calls', 'sessions'];
+// The scope columns each table has; a scope on a column a table lacks lets no row of it through
+// (fail closed): a project-scoped reader sees no usage rows (the sessions row carries the totals) and
+// a time-scoped one no links. A row whose ts is null never matches a time scope either.
+const SCOPE_HAS = {
+  project: ['session_parts', 'calls', 'sessions'], folder: ['session_parts', 'calls', 'sessions'],
+  time: { sessions: 'started', session_parts: 'ts', session_usage: 'ts', calls: 'ts', session_lifecycle: 'ts' },
+};
+const LEGACY_ROOMS = ['messages', 'tool_calls', 'sessions'];
+// The first schema-3 layout of the 0.20 development builds: a share made there granted <m>_turns
+// (with <m>_calls and <m>_sessions, which the profile reuses by name) and filtered it.
+const DEV_ROOMS = ['turns'];
+
+/** A scope's predicate for one schema-3 table. `session=` takes a ref (its store included) or a bare id. */
+function scopePredicateV3(scope, table, sqlStr, parseSessionRef) {
+  return scope.map(({ key, value }) => {
+    if (key === 'since' || key === 'until') {
+      const col = SCOPE_HAS.time[table];
+      return col ? `${col} ${key === 'since' ? '>=' : '<'} parseDateTimeBestEffort(${sqlStr(value)})` : '0';
+    }
+    if ((key === 'project' || key === 'folder') && !SCOPE_HAS[key].includes(table)) return '0';
+    if (key === 'source' || key === 'harness') return `harness = ${sqlStr(value)}`;
+    if (key === 'session') {
+      if (!value.includes(':')) return `session_id = ${sqlStr(value)}`;
+      const r = parseSessionRef(value);
+      const parts = [`harness = ${sqlStr(r.harness)}`, `session_id = ${sqlStr(r.session_id)}`];
+      if (r.host != null && r.harness_path != null) parts.push(`host = ${sqlStr(r.host)}`, `harness_path = ${sqlStr(r.harness_path)}`, `incarnation = ${sqlStr(r.incarnation || '')}`);
+      return `(${parts.join(' AND ')})`;
+    }
+    return `${SCOPE_COLUMNS[key].column(table)} = ${sqlStr(value)}`;
+  }).join(' AND ');
+}
+
+// Names reach the DDL below as identifiers. Each is checked against the one shape memhouse
+// creates (as house.assertUsableName) and then quoted, so a name read back from the server
+// (system.users, a meta record) can neither break the statement nor extend it.
+const NAME_RE = /^[A-Za-z][A-Za-z0-9_]{0,63}$/;
+function assertName(name, what) {
+  if (typeof name !== 'string' || !NAME_RE.test(name)) throw new Error(`'${name}' cannot be a ${what} — expected [A-Za-z][A-Za-z0-9_]*`);
+  return name;
+}
+/** A quoted ClickHouse identifier: backticks, with backslash and backtick escaped. */
+function ident(name) { return `\`${String(name).replace(/\\/g, '\\\\').replace(/`/g, '\\`')}\``; }
+/** A checked, quoted `db.table` (each part one memhouse makes). */
+function qual(fq) {
+  const parts = String(fq).split('.');
+  if (parts.length !== 2) throw new Error(`'${fq}' is not a db.table name`);
+  return parts.map((x) => ident(assertName(x, 'table name part'))).join('.');
+}
+
+/**
+ * The statements of a schema-3 share, in a fail-closed order: a scoped share writes its filters
+ * BEFORE any grant; the 0.18 wildcard is taken back before the table grants (it would reach past
+ * the filters, and past the six tables); a full share drops leftover filters only after it is
+ * granted (until then they narrow, never widen). Returns [{ sql, phase }], phase 'filter' | 'grant'
+ * | 'clear'. Throws on a name that is not one memhouse makes.
+ */
+function shareV3Plan({ db, member, user, scope, sqlStr, parseSessionRef }) {
+  assertName(db, 'house'); assertName(member, 'member'); assertName(user, 'user');
+  const tbl = (t) => `${ident(db)}.${ident(`${member}_${t}`)}`;
+  const steps = [];
+  if (scope) for (const t of V3_TABLES) steps.push({ phase: 'filter', sql: `CREATE ROW POLICY OR REPLACE ${ident(policyName(user, t))} ON ${tbl(t)} USING ${scopePredicateV3(scope, t, sqlStr, parseSessionRef)} TO ${ident(user)}` });
+  // Exact tables only. No REVOKE on `<m>_*` here: a prefix wildcard also matches another
+  // member's tables when that member's name starts with this one's (bob, bob_smith) and would
+  // strip the reader's grants there, or that member's own. A 0.18 wildcard grant still held is
+  // taken back by the admin's move (moveSharePlan), only when the reader holds it.
+  steps.push(...V3_TABLES.map((t) => ({ phase: 'grant', sql: `GRANT SELECT ON ${tbl(t)} TO ${ident(user)}` })));
+  if (!scope) for (const t of V3_TABLES) steps.push({ phase: 'clear', sql: `DROP ROW POLICY IF EXISTS ${ident(policyName(user, t))} ON ${tbl(t)}` });
+  return steps;
+}
+
+/**
+ * Revoking a schema-3 share: every grant first — the six tables, the 0.18 rooms a share made before
+ * the conversion still names in <db>, and the development layout's <m>_turns — then every filter,
+ * the 0.18 and development ones included. Exact
+ * names only: a 0.18 wildcard grant (`<m>_*`) is taken back by wildcardRevoke, and only when the
+ * reader holds it and it matches nothing but this member's tables (wildcardOnRevoke). (The rooms renamed into the
+ * archive are the admin's: a member holds no rights there, so `migrate --v3-shares` clears them.)
+ */
+function revokeV3Plan({ db, member, user }) {
+  assertName(db, 'house'); assertName(member, 'member'); assertName(user, 'user');
+  const tbl = (t) => `${ident(db)}.${ident(`${member}_${t}`)}`;
+  const NEW = V3_TABLES.map((t) => `${db}.${member}_${t}`);
+  const oldRooms = LEGACY_ROOMS.map((r) => `${db}.${member}_${r}`).filter((x) => !NEW.includes(x));
+  return [
+    ...V3_TABLES.map((t) => ({ phase: 'grant', sql: `REVOKE SELECT ON ${tbl(t)} FROM ${ident(user)}` })),
+    ...oldRooms.map((fq) => ({ phase: 'grant', sql: `REVOKE SELECT ON ${qual(fq)} FROM ${ident(user)}` })),
+    ...DEV_ROOMS.map((t) => ({ phase: 'grant', sql: `REVOKE SELECT ON ${tbl(t)} FROM ${ident(user)}` })),
+    ...V3_TABLES.map((t) => ({ phase: 'clear', sql: `DROP ROW POLICY IF EXISTS ${ident(policyName(user, t))} ON ${tbl(t)}` })),
+    ...legacyPolicyDrops({ db, member, user, keep: NEW }),
+    ...DEV_ROOMS.map((t) => ({ phase: 'clear', sql: `DROP ROW POLICY IF EXISTS ${ident(policyName(user, t))} ON ${tbl(t)}` })),
+  ];
+}
+
+/** Taking back a 0.18 wildcard share (`<m>_*`). Call it only for a reader who holds that grant,
+ * when it matches nothing but this member's tables (wildcardOnRevoke). */
+function wildcardRevoke({ db, member, user }) {
+  assertName(db, 'house'); assertName(member, 'member'); assertName(user, 'user');
+  return { phase: 'grant', sql: `REVOKE SELECT ON ${db}.${member}_* FROM ${ident(user)}` };
+}
+
+/**
+ * May a schema-3 share be written next to what the reader holds? `heldWildcard`: true when the
+ * reader still holds the member's 0.18 wildcard, false when they do not, null when that could
+ * not be read. Only a known false proceeds: a share beside the wildcard would not narrow it, and
+ * an unread answer is no evidence either way.
+ */
+function shareGate(heldWildcard) {
+  if (heldWildcard === false) return null;
+  return { refuse: heldWildcard === true ? 'held' : 'unknown' };
+}
+
+/**
+ * Members whose names collide with `member`'s in one house: one starts with the other's name and
+ * an underscore (bob, bob_smith). A member's grant is the prefix wildcard `<db>.<m>_*`, so the
+ * shorter name's grant also reaches the longer name's tables, to read and to write, and sometimes
+ * the other way round (wildcardOnRevoke). `tables` is the house's table names; a member is a prefix
+ * of a table ending in _meta, _session_parts, _turns or _messages.
+ */
+function memberCollisions(member, tables) {
+  const members = new Set();
+  for (const t of tables) { const m = /^(.+)_(meta|session_parts|turns|messages)$/.exec(String(t)); if (m) members.add(m[1]); }
+  return [...members].filter((x) => x !== member && (x.startsWith(`${member}_`) || member.startsWith(`${x}_`))).sort();
+}
+
+// The names memhouse gives a member's tables in the house, as the part after `<m>_`: its tables,
+// the copies migrate keeps of a 0.18 room while it moves one (`<room>__migrating`) and after
+// (`<room>_pre_epoch`), and the scratch table share's probe makes and drops (`_mh_probe_<pid>`).
+const MEMBER_TABLES = [...new Set([...V3_TABLES, ...LEGACY_ROOMS, ...DEV_ROOMS, 'meta', 'events', 'session_stats', 'session_model_stats', 'session_tool_stats',
+  ...LEGACY_ROOMS.flatMap((r) => [`${r}_pre_epoch`, `${r}__migrating`])])];
+const isMemberTable = (rest) => MEMBER_TABLES.includes(rest) || /^_mh_probe_\d+$/.test(rest);
+const startsMemberTable = (p) => [...MEMBER_TABLES, '_mh_probe_1'].some((n) => n.startsWith(`${p}_`));
+
+/**
+ * A reader's 0.18 wildcard `<db>.<member>_*` when the member revokes them. A REVOKE on it takes
+ * the reader's grant on every table it matches, whoever's table that is. Other members whose names
+ * collide with this one's come from the house's tables (memberCollisions) and from its users,
+ * since a member with grants but no tables, or whose tables this credential cannot see, has no
+ * table to find it by. The wildcard matches the tables of:
+ *   - a longer name, all of them: bob_* matches bob_smith's;
+ *   - a shorter name when the rest of `member` starts one of its table names: bob_session_*
+ *     matches bob's bob_session_parts, while bob_smith_* matches none of bob's (ClickHouse 26.7:
+ *     REVOKE ON mem.bob_smith_* leaves the rest of mem.bob_* readable).
+ * And of `tables`, the house's table names this credential sees: a table under the member's
+ * prefix that is neither one of its names nor one of a reached member's is a stray, whose owner
+ * cannot be told. The member takes the wildcard back only when it matches nothing else.
+ * collisions null (tables unlisted), or tables or users null (unread): that is unknown, and it
+ * is left. `users` is the server's users narrowed to those that may be members of this house
+ * (holdsMemberGrant), so one person's account in another house is not a collision here.
+ *   revoke: the member issues the REVOKE; left: the reader may still hold it afterwards;
+ *   colliding: every colliding name found; reaches: those whose tables it also matches, and
+ *   unseen: those of them found by their user alone; strays: other tables it matches (null: unknown).
+ */
+function wildcardOnRevoke({ member, collisions, heldWildcard, tables = null, users = null }) {
+  let colliding = null; let reaches = null; let strays = null;
+  if (collisions && tables && users) {
+    const near = (x) => x !== member && (x.startsWith(`${member}_`) || member.startsWith(`${x}_`));
+    colliding = [...new Set([...collisions, ...users.map(String).filter(near)])].sort();
+    reaches = colliding.filter((x) => x.startsWith(`${member}_`) || (member.startsWith(`${x}_`) && startsMemberTable(member.slice(x.length + 1))));
+    const holds = (m, t) => t.startsWith(`${m}_`) && isMemberTable(t.slice(m.length + 1));
+    strays = tables.map(String).filter((t) => t.startsWith(`${member}_`) && ![member, ...reaches].some((m) => holds(m, t))).sort();
+  }
+  const revoke = heldWildcard === true && !!reaches && !reaches.length && !strays.length;
+  // Found by its user alone: no table of theirs is in sight, so whether it is a member is unknown.
+  const unseen = reaches && reaches.filter((x) => !collisions.includes(x));
+  return { revoke, left: heldWildcard !== false && !revoke, colliding, reaches, unseen, strays };
+}
+
+/**
+ * May `user` be a member of house `db`, from its SHOW GRANTS lines? A member owns its tables: it
+ * holds them, `<db>.<user>_…` (or the archive's, `<db>_archive.<user>_…`), with ALL, INSERT, or a
+ * CREATE, DROP, ALTER, OPTIMIZE or TRUNCATE privilege, or with the right to grant them, none of
+ * which a share gives (a share is SELECT only). Any such word counts, so an admin's CREATE USER
+ * ON * does too: a false positive only leaves a grant for the admin. A broader target that covers them counts too (`*.*`, `<db>.*`, `<db>.b*`), since
+ * SHOW GRANTS lists only the broader line: an admin who also ships. So a reader of a colliding
+ * member, a stray SELECT on `<db>.<user>_*`, and an account in another house do not count. A user
+ * holding a role may hold a member's grant through it, so it counts.
+ */
+function holdsMemberGrant(lines, db, user) {
+  if (rolesGranted(lines).length) return true;
+  const own = `${user}_`;
+  const covers = (t) => {
+    if (t === '*' || t === '*.*') return true;
+    const dot = t.indexOf('.');
+    if (dot < 0) return false;
+    const tdb = t.slice(0, dot); const tt = t.slice(dot + 1);
+    const dbs = [db, `${db}_archive`];
+    if (!(tdb.endsWith('*') ? dbs.some((d) => d.startsWith(tdb.slice(0, -1))) : dbs.includes(tdb))) return false;
+    if (!tt.endsWith('*')) return tt.startsWith(own);
+    const p = tt.slice(0, -1);
+    return own.startsWith(p) || p.startsWith(own);
+  };
+  return lines.some((line) => {
+    const { masked, names } = maskQuoted(line);
+    const m = /^GRANT\s+(.+?)\s+ON\s+(\S+)\s+TO\b/.exec(masked);
+    if (!m || !covers(m[2].replace(/\u0000(\d+)\u0000/g, (_, i) => names[Number(i)]))) return false;
+    return /\bWITH GRANT OPTION\b/.test(masked) || /\b(ALL|INSERT|CREATE|DROP|ALTER|OPTIMIZE|TRUNCATE)\b/.test(m[1].replace(/\([^)]*\)/g, ''));
+  });
+}
+
+/**
+ * Of the server's `users`, those whose names collide with `member`'s and who may be members of
+ * house `db` (holdsMemberGrant). `read(name)` returns a user's SHOW GRANTS lines; one that cannot
+ * be read counts.
+ */
+async function collidingUsers({ users, member, db, read }) {
+  const out = [];
+  for (const x of users.map(String)) {
+    if (x === member || !(x.startsWith(`${member}_`) || member.startsWith(`${x}_`))) continue;
+    let maybe = true;
+    try { maybe = holdsMemberGrant(await read(x), db, x); } catch { /* unread: counts */ }
+    if (maybe) out.push(x);
+  }
+  return out;
+}
+
+/**
+ * Of the row policies in a member's database (system.row_policies, which can show other members'
+ * too, on tables this member cannot see), the ones on this member's own tables, by exact name.
+ *   mine    for the orphan check: any table memhouse names for the member (memberTargets: its
+ *           0.18 rooms, development and profile tables, meta, events, stats) and the share probe's
+ *           scratch table (`<m>__mh_probe_<pid>`).
+ *   grants  for describing a grantee's scope: only the tables a share filters on this layout
+ *           (schema 3: V3_TABLES and the development layout's; 0.18: its rooms), so a colliding
+ *           name's table that spells a 0.18 room (bob_tool's calls is bob's tool_calls) is never
+ *           read as this member's scope.
+ */
+/**
+ * The statements that take SHOW ROW POLICIES back from a member, one per object its grants name
+ * it on (`SHOW GRANTS FOR <member>` lines). Members made before 0.20 hold it on <db>.<m>_*; it
+ * opens all of system.row_policies, every member's scoped shares included, and nothing memhouse
+ * does needs it. [] when the member holds none.
+ */
+function showPoliciesRevokes(lines, member) {
+  const out = [];
+  for (const l of lines || []) {
+    const m = /^GRANT\s+(.+?)\s+ON\s+(\S+)\s+TO\s+(\S+?)(?:\s+WITH\s+GRANT\s+OPTION)?\s*;?\s*$/i.exec(String(l).trim());
+    if (!m || m[3].replace(/`/g, '') !== member) continue;
+    if (!/(^|,\s*)SHOW\s+(ROW\s+)?POLICIES(\s*,|$)/i.test(m[1])) continue;
+    const sql = `REVOKE SHOW ROW POLICIES ON ${m[2]} FROM ${ident(member)}`;
+    if (!out.includes(sql)) out.push(sql);
+  }
+  return out;
+}
+
+function ownPolicies(policies, { db, member, schema3 }) {
+  const known = memberTargets({ db, archive: `${db}_archive`, member, legacy: null }).known;
+  const probe = new RegExp(`^${member}__mh_probe_\\d+$`);
+  const mine = policies.filter((p) => known.has(`${db}.${p.table}`) || probe.test(String(p.table)));
+  const shared = new Set((schema3 ? [...V3_TABLES, ...DEV_ROOMS] : LEGACY_ROOMS).map((t) => `${member}_${t}`));
+  return { mine, grants: mine.filter((p) => shared.has(String(p.table))) };
+}
+
+/** What else a left wildcard matches (wildcardOnRevoke), said in one clause. */
+function wildcardReachText({ reaches, unseen = [], strays }, db) {
+  if (!reaches) return 'the house\'s tables or users could not be listed';
+  const parts = [];
+  const seen = reaches.filter((x) => !unseen.includes(x));
+  if (seen.length) parts.push(`the tables of ${seen.map((x) => `'${x}'`).join(', ')}`);
+  if (unseen.length) parts.push(`any table of ${unseen.map((x) => `'${x}'`).join(', ')} (a user whose name collides with yours and who may be a member here; no table of theirs is visible to you)`);
+  if (strays.length) parts.push(`${strays.map((t) => `${db}.${t}`).join(', ')}, which memhouse did not make for you`);
+  return `it also reaches ${parts.join(' and ')}`;
+}
+
+/**
+ * Who takes back a 0.18 wildcard the member could not, and how (`wc` from wildcardOnRevoke).
+ * Where member names collide, by hand: `migrate --v3-shares` refuses such a house. A REVOKE on the
+ * wildcard takes every table it matches, so strays are checked first. `--v3-shares` moves only a
+ * full share memhouse recorded as granted (classifyShare): `movable` says the record does (null:
+ * unread), and a revoke has just recorded it as revoked, so there it is by hand too.
+ */
+function wildcardAdminLine({ wc, movable = false, db, member, user }) {
+  // movable: true, the record says --v3-shares would move it; false, it would not; null, unread;
+  // 'check', it would only if the reader does not hold the wildcard (a scoped record, beside
+  // grants that could not be read).
+  const guide = 'docs/guides/troubleshooting.md, "Two member names that collide"';
+  const wildcard = `${db}.${member}_*`;
+  if (wc.colliding && wc.colliding.length) return `The admin settles it by hand, because member names collide in this house (${guide}).`;
+  if (wc.strays && wc.strays.length) return `The admin settles it by hand: a REVOKE on ${wildcard} would also take the reader's grants on ${wc.strays.map((t) => `${db}.${t}`).join(', ')}, so the admin checks whose they are first.`;
+  if (movable === true) {
+    return wc.colliding ? 'The admin settles it: memhouse migrate --v3-shares, or SHOW GRANTS and REVOKE by hand.'
+      : `The admin settles it: memhouse migrate --v3-shares, or by hand if member names collide, since it refuses such a house (${guide}).`;
+  }
+  const by = `REVOKE SELECT ON ${wildcard} FROM ${ident(user)}`;
+  if (movable === 'check') return `The admin checks SHOW GRANTS FOR ${ident(user)} first: if it holds ${wildcard}, ${by} by hand (memhouse migrate --v3-shares refuses a scoped share beside it); if not, memhouse migrate --v3-shares moves the recorded share${wc.colliding ? '' : `, unless member names collide, since it refuses such a house (${guide})`}.`;
+  const why = `${movable === null ? 'the share record could not be read, and ' : ''}memhouse migrate --v3-shares moves only a full share memhouse recorded as granted`;
+  return wc.colliding ? `The admin settles it by hand: ${by} (${why}).`
+    : `The admin settles it by hand: ${by} (${why}), once the house's tables and users show that no member's name collides with yours and no table under ${db}.${member}_ is one memhouse did not make for you (${guide}).`;
+}
+
+// ── moving a 0.18 share onto schema 3 (memhouse migrate --v3-shares) ───────────────────────────
+
+/**
+ * Every table of ONE member, by exact name: what a grant on this member can reach. Matching is by
+ * these names only, never by prefix: `mem.bob_` is also the start of `mem.bob_smith_turns`.
+ * `legacy` is the renamed rooms ({ messages, tool_calls, sessions } -> '<archive>.<m>_*_pre_v3').
+ */
+function memberTargets({ db, archive, member, legacy }) {
+  const t = (x) => `${db}.${member}_${x}`;
+  const wildcard = `${db}.${member}_*`;
+  const before = { full: [wildcard], scoped: LEGACY_ROOMS.map(t) };
+  const after = V3_TABLES.map(t);
+  const known = new Set([wildcard, ...before.scoped, ...after, ...DEV_ROOMS.map(t),
+    ...['meta', 'events', 'session_stats', 'session_model_stats', 'session_tool_stats'].map(t),
+    // The capture archive: the profile's two tables, and the development builds' two.
+    ...['session_units', 'session_sources', 'records', 'files'].map((x) => `${archive}.${member}_${x}`), ...Object.values(legacy || {})]);
+  return { wildcard, before, after, known };
+}
+
+/**
+ * What a user's SHOW GRANTS lines let them read of ONE member's tables (backticks dropped):
+ * an exact table of the member's, the member's wildcard, and anything broader that covers one of
+ * them — `*.*`, `<db>.*`, `<archive>.*`, or a prefix wildcard like `<db>.b*` that matches a table
+ * of the member's. `admin` is true for a server administrator (ALL, ACCESS MANAGEMENT or CREATE
+ * USER on *.*): they read everything by their own grants, which is no share.
+ */
+function selectTargets(lines, known) {
+  const on = new Set(); let admin = false;
+  const tables = [...known].filter((k) => !k.endsWith('*'));
+  const covers = (target) => {
+    if (known.has(target)) return true;
+    if (target === '*.*' || target === '*') return tables.length > 0;
+    const dot = target.indexOf('.');
+    const tdb = target.slice(0, dot); const ttab = target.slice(dot + 1);
+    if (!ttab.endsWith('*')) return false;
+    const prefix = ttab.slice(0, -1);
+    return tables.some((k) => { const i = k.indexOf('.'); return k.slice(0, i) === tdb && k.slice(i + 1).startsWith(prefix); });
+  };
+  for (const line of lines) {
+    // Read with quoted names masked (maskQuoted), so a role or user named like grammar
+    // (`ALL ON *`) is never taken for a privilege; the target's names come back unquoted.
+    const { masked, names } = maskQuoted(line);
+    const m = /^GRANT\s+(.+?)\s+ON\s+(\S+)\s+TO\b/.exec(masked);
+    if (!m) continue;
+    const target = m[2].replace(/\u0000(\d+)\u0000/g, (_, i) => names[Number(i)]).replace(/`/g, '');
+    // Global access rights print as `ON *` (CREATE USER, ROLE ADMIN) or `ON *.*` (ALL).
+    if ((target === '*' || target === '*.*') && /\bALL\b|ACCESS MANAGEMENT|CREATE USER|ROLE ADMIN/.test(m[1])) admin = true;
+    if (!/\bSELECT\b|\bALL\b/.test(m[1])) continue;
+    if (covers(target)) on.add(target);
+  }
+  return { on, admin };
+}
+
+/**
+ * One SHOW GRANTS line with each backtick-quoted name masked (\u0000<i>\u0000), so its structure
+ * (ON, TO, the commas) is read from what is outside the quotes only; the names come back
+ * unescaped, as ClickHouse escapes them (\\, \`, \n, \t, …).
+ */
+function maskQuoted(line) {
+  const names = [];
+  const ESC = { n: '\n', t: '\t', r: '\r', b: '\b', f: '\f', 0: '\0' };
+  const masked = String(line).replace(/`((?:[^`\\]|\\.)*)`/g, (_, body) => {
+    names.push(body.replace(/\\(.)/g, (m, c) => (c in ESC ? ESC[c] : c)));
+    return `\u0000${names.length - 1}\u0000`;
+  });
+  return { masked, names };
+}
+
+/**
+ * The roles one SHOW GRANTS listing grants (`GRANT r1, `r 2` TO u [WITH ADMIN OPTION]`), unquoted.
+ * A role's privileges are listed under the role, not under its grantee: a reader reaches whatever
+ * the roles granted to them reach, and the roles granted to those roles.
+ */
+function rolesGranted(lines) {
+  const out = [];
+  for (const line of lines) {
+    const { masked, names } = maskQuoted(line);
+    if (/\sON\s/.test(masked)) continue;
+    const m = /^GRANT\s+(.+?)\s+TO\s+/.exec(masked);
+    if (!m) continue;
+    for (const part of m[1].split(',')) {
+      const p = part.trim();
+      const q = /^\u0000(\d+)\u0000$/.exec(p);
+      const name = q ? names[Number(q[1])] : p;
+      if (name) out.push(name);
+    }
+  }
+  return out;
+}
+
+/**
+ * Where one recorded share stands, from the grants ClickHouse holds (`on`, this member's targets
+ * only), the user's policies on the schema-3 tables (`policies`: a Set of table names), and
+ * whether an earlier run started moving it (`started`). Returns { apply: true } or { diff }.
+ * Only two states proceed without a started mark: exactly the 0.18 share memhouse records, or
+ * exactly the schema-3 share with the filters its scope needs. Anything else is a difference,
+ * and the caller changes nothing.
+ */
+function classifyShare({ rec, on, policies, started, targets }) {
+  const set = (a) => [...a].sort().join(', ');
+  // A revoked record with grants still in place is a difference too, never a pass.
+  if (!rec.granted) return on.size ? { diff: `recorded as revoked, but holds ${set(on)}` } : { skip: true };
+  const same = (a, b) => a.length === b.size && a.every((x) => b.has(x));
+  const before = rec.scopeRaw ? targets.before.scoped : targets.before.full;
+  const allowed = new Set([...before, ...targets.after]);
+  const extra = [...on].filter((x) => !allowed.has(x));
+  if (extra.length) return { diff: `holds ${set(extra)} beyond what memhouse recorded (${rec.scopeRaw ? `scoped: ${rec.scopeRaw}` : 'full'})` };
+  if (!on.size) return { diff: 'recorded as granted, but holds nothing on these tables' };
+  // A scoped reader holding a schema-3 table must hold its filter: the move writes every filter
+  // before any grant, and a 0.18 scoped share's filter on <m>_sessions stays with that name.
+  const unfiltered = V3_TABLES.filter((t, i) => on.has(targets.after[i]) && !policies.has(t));
+  if (rec.scopeRaw && unfiltered.length) return { diff: `reads ${unfiltered.join(', ')} without the filter its scope (${rec.scopeRaw}) needs` };
+  if (started) {
+    // Only states the move itself passes through: scoped, any mix of the rooms and the filtered
+    // tables (checked above); full, the wildcard alone, or some of the tables without it. (A full
+    // move stopped between taking back the wildcard and the first grant holds nothing: that was
+    // refused above — settled by hand, never re-granted on a guess.)
+    if (!rec.scopeRaw && on.has(targets.wildcard) && on.size > 1) return { diff: `holds ${set(on)}: not a state the move passes through` };
+    return { apply: true, resume: true };
+  }
+  if (same(before, on)) return { apply: true };
+  if (same(targets.after, on)) {
+    const filtered = V3_TABLES.filter((t) => policies.has(t));
+    if (!rec.scopeRaw && filtered.length) return { diff: `recorded as a full share, but ${filtered.join(', ')} still carry a filter` };
+    return { apply: true };
+  }
+  return { diff: on.size ? `holds ${set(on)}, which is neither the recorded 0.18 share nor its schema-3 form` : 'recorded as granted, but holds nothing on these tables' };
+}
+
+/**
+ * The statements that move one recorded share onto schema 3: the schema-3 share itself
+ * (shareV3Plan: filters, then grants), then, once that is in place, the 0.18 grants it replaces —
+ * the rooms in <db> (never a name schema 3 uses too: <m>_sessions IS the new share) and the rooms
+ * renamed into the archive — and the 0.18 filters, each by exact name.
+ */
+function moveSharePlan({ db, member, user, scope, legacy, holdsWildcard, sqlStr, parseSessionRef }) {
+  const NEW = V3_TABLES.map((t) => `${db}.${member}_${t}`);
+  const oldRooms = [...LEGACY_ROOMS.map((r) => `${db}.${member}_${r}`), ...Object.values(legacy || {})].filter((x) => !NEW.includes(x));
+  const share = shareV3Plan({ db, member, user, scope, sqlStr, parseSessionRef });
+  // A 0.18 full share's wildcard goes before the table grants: in ClickHouse a REVOKE on `m_*`
+  // subtracts every table it matches, the ones just granted included.
+  if (holdsWildcard) share.splice(share.findIndex((x) => x.phase === 'grant'), 0, wildcardRevoke({ db, member, user }));
+  return [
+    ...share,
+    ...oldRooms.map((fq) => ({ phase: 'clear', sql: `REVOKE SELECT ON ${qual(fq)} FROM ${ident(user)}` })),
+    ...legacyPolicyDrops({ db, member, user, legacy, keep: NEW }),
+  ];
+}
+
+/**
+ * What `--v3-shares` decides on, read from the house: the recorded shares, the runs that started
+ * and did not finish, who holds what on this member's tables, and the filters on its schema-3
+ * tables. `q.rows(sql)` runs one query. Any read that fails REJECTS, naming what could not be
+ * read: nothing unknown is ever taken for nothing.
+ */
+async function readLiveShares(q, { db, member, meta, targets, sqlStr }) {
+  const M = qual(meta);
+  const read = async (what, sql) => {
+    try { return await q.rows(sql); } catch (e) { throw new Error(`could not read ${what}: ${String(e && e.message || e).split('\n')[0]}`); }
+  };
+  const recs = await read(meta, `SELECT substring(key, 7) AS user, argMax(value, updated_at) AS value FROM ${M}
+      WHERE key LIKE 'share:%' GROUP BY key ORDER BY key`);
+  // An earlier run that started moving a share and did not finish leaves 'started' here.
+  const marks = await read(meta, `SELECT substring(key, 9) AS user, argMax(value, updated_at) AS value FROM ${M}
+      WHERE key LIKE 'v3share:%' GROUP BY key`);
+  const users = (await read('system.users', 'SELECT name FROM system.users ORDER BY name')).map((r) => r.name).filter((u) => u !== member);
+  const live = new Map(); const admins = [];
+  // What a reader reaches through a role (and a role granted to that role), by role: memhouse
+  // never shares through a role, so any of it on this member is a grant it did not record.
+  const viaRole = new Map();
+  const roleLines = new Map();
+  const linesOfRole = async (r) => {
+    if (!roleLines.has(r)) roleLines.set(r, (await read(`the grants of role '${r}'`, `SHOW GRANTS FOR ${ident(r)}`)).map((x) => Object.values(x)[0]));
+    return roleLines.get(r);
+  };
+  for (const u of users) {
+    const text = (await read(`the grants of '${u}'`, `SHOW GRANTS FOR ${ident(u)}`)).map((r) => Object.values(r)[0]);
+    const { on, admin } = selectTargets(text, targets.known);
+    const { via, admin: roleAdmin } = await reachThroughRoles(text, targets.known, linesOfRole);
+    // An administrator reads everything by a global grant, which is no share: only that global
+    // grant is set aside, however it reached them (directly or through any role). Anything else
+    // they hold on this member counts as anyone's would.
+    if (admin || roleAdmin) {
+      admins.push(u);
+      for (const set of [on, ...via.map((v) => v.on)]) { set.delete('*.*'); set.delete('*'); }
+    }
+    if (on.size) live.set(u, on);
+    const kept = via.filter((v) => v.on.size);
+    if (kept.length) viaRole.set(u, kept);
+  }
+  const tables = (await read('the house\'s tables', `SELECT name FROM system.tables WHERE database = ${sqlStr(db)}`)).map((r) => r.name);
+  const pols = await read('system.row_policies', `SELECT short_name, table FROM system.row_policies
+      WHERE database = ${sqlStr(db)} AND table IN (${V3_TABLES.map((t) => sqlStr(`${member}_${t}`)).join(', ')})`);
+  return {
+    recorded: new Map(recs.map((r) => [r.user, parseShareRecord(r.value)])),
+    started: new Set(marks.filter((r) => /^started\b/.test(String(r.value))).map((r) => r.user)),
+    live, viaRole, admins, collisions: memberCollisions(member, tables),
+    policiesOf: (u) => new Set(V3_TABLES.filter((t) => pols.some((r) => r.short_name === policyName(u, t) && r.table === `${member}_${t}`))),
+  };
+}
+
+/**
+ * `memhouse members`: who holds what in the house and in its capture archive, directly or through a
+ * role (and a role granted to that role). `membersGrantsSQL` reads the grants of users and roles,
+ * MEMBERS_ROLE_GRANTS_SQL who holds which role, and `membersAccess` puts them together per user. A
+ * grant in the house is listed by table (`alice_*` for a wildcard), one in the archive by its full
+ * name (`mem_archive.alice_session_units`, `mem_archive.*`); one held through a role says so.
+ * `hasWild`: the server's system.grants has `is_wildcard` (26.x); before it, a wildcard grant's row
+ * carries only the bare prefix (`alice_`), so the trailing underscore is the marker.
+ */
+function membersGrantsSQL({ db, archive, hasWild, sqlStr }) {
+  const star = hasWild ? "if(is_wildcard, '*', '')" : "if(endsWith(table, '_'), '*', '')";
+  return `SELECT user_name, role_name, database, table, ${star} AS star
+    FROM system.grants WHERE database IN (${sqlStr(db)}, ${sqlStr(archive)})`;
+}
+const MEMBERS_ROLE_GRANTS_SQL = 'SELECT user_name, role_name, granted_role_name FROM system.role_grants';
+
+function membersAccess({ grants, roleGrants = [], db }) {
+  const label = (g) => (g.database === db ? (g.table == null ? null : `${g.table}${g.star || ''}`)
+    : `${g.database}.${g.table == null ? '*' : `${g.table}${g.star || ''}`}`);
+  const byUser = new Map(); const byRole = new Map();
+  const add = (m, k, g) => {
+    if (!m.has(k)) m.set(k, { dbWide: false, tables: new Set() });
+    const e = m.get(k);
+    if (g.database === db && g.table == null) e.dbWide = true;
+    const n = label(g); if (n) e.tables.add(n);
+  };
+  for (const g of grants) { if (g.user_name != null) add(byUser, g.user_name, g); else if (g.role_name != null) add(byRole, g.role_name, g); }
+  const rolesOf = new Map();
+  for (const r of roleGrants) {
+    const k = r.user_name != null ? `u:${r.user_name}` : `r:${r.role_name}`;
+    if (!rolesOf.has(k)) rolesOf.set(k, []);
+    rolesOf.get(k).push(r.granted_role_name);
+  }
+  const users = new Set([...byUser.keys(), ...roleGrants.filter((r) => r.user_name != null).map((r) => r.user_name)]);
+  const out = [];
+  for (const u of [...users].sort()) {
+    const own = byUser.get(u) || { dbWide: false, tables: new Set() };
+    let dbWide = own.dbWide; const tables = [...own.tables].sort();
+    const seen = new Set(); const queue = [...(rolesOf.get(`u:${u}`) || [])];
+    while (queue.length) {
+      const r = queue.shift();
+      if (seen.has(r)) continue;
+      seen.add(r);
+      const e = byRole.get(r);
+      if (e) {
+        if (e.dbWide) { dbWide = true; tables.push(`the whole database (through role ${r})`); }
+        for (const t of [...e.tables].sort()) tables.push(`${t} (through role ${r})`);
+      }
+      queue.push(...(rolesOf.get(`r:${r}`) || []));
+    }
+    if (dbWide || tables.length) out.push({ u, db_wide: dbWide ? 1 : 0, tables: tables.join(', '), list: tables });
+  }
+  return out;
+}
+
+/**
+ * What a user reaches of one member (`known`, memberTargets) through the roles their grant lines
+ * name, and the roles granted to those roles: [{ role, on }], cycles stopped. `linesOfRole(r)`
+ * returns a role's SHOW GRANTS lines, and rejects when they cannot be read. `admin`: a role holds
+ * an administrator's global grant (the caller sets that grant aside).
+ */
+async function reachThroughRoles(grantLines, known, linesOfRole) {
+  const via = []; let admin = false;
+  const seen = new Set(); const queue = rolesGranted(grantLines);
+  while (queue.length) {
+    const r = queue.shift();
+    if (seen.has(r)) continue;
+    seen.add(r);
+    const rt = await linesOfRole(r);
+    const got = selectTargets(rt, known);
+    if (got.admin) admin = true;
+    if (got.on.size) via.push({ role: r, on: got.on });
+    queue.push(...rolesGranted(rt));
+  }
+  return { via, admin };
+}
+
+/**
+ * `memhouse share <user> --revoke`, after the REVOKE: what the reader still reads of the member
+ * through a role. A REVOKE from the reader leaves a role's privileges, so the revoke is not done
+ * while any remain; nor while they cannot be read (`unreadable`: why). Returns the lines to print
+ * and whether the revoke may say so.
+ */
+function revokeRoleReport({ user, via, direct = [], collision = [], collisionOther = [], unlisted = [], unreadable = null }) {
+  if (unreadable) return { done: false, lines: [`'${user}' had their own grants withdrawn, but whether they still read your house through a role could not be checked: ${unreadable}. Ask the admin to check the roles '${user}' holds.`] };
+  const lines = [
+    ...(collision.length ? [`'${user}' still reaches your tables through the member grant ${collision.join(', ')}: your name and theirs collide (one is the other's plus an underscore), so no revoke closes it. Do not revoke that grant, which is their own house; see docs/guides/troubleshooting.md, "Two member names that collide"`] : []),
+    ...collisionOther.map(({ target, member }) => `'${user}' still reaches your tables through ${target}, member '${member}''s grant to them: your name and '${member}''s collide (one is the other's plus an underscore), so that grant reaches your tables too. It is '${member}''s grant, and in a house with colliding names an admin takes it back (docs/guides/troubleshooting.md, "Two member names that collide")`),
+    ...(unlisted.length ? [`'${user}' still holds ${unlisted.join(', ')}: the house's tables or users could not be listed, so whether that is another member's own house is unknown. An admin checks before revoking it`] : []),
+    ...(direct.length ? [`'${user}' still holds ${direct.join(', ')} by a grant memhouse did not make: an admin revokes it`] : []),
+    ...via.map((v) => `'${user}' can still read ${[...v.on].join(', ')} through role '${v.role}': revoke the role's grant, or remove '${user}' from '${v.role}' (an admin does either)`),
+  ];
+  return { done: !lines.length, lines };
+}
+
+/**
+ * The check a revoke ends with, once the reader's own grants are withdrawn: what they still read of
+ * the member (`known`, memberTargets). Their remaining direct grants (anything but the 0.18
+ * wildcard, which the caller handles), and what their roles reach, nested ones included. Nothing
+ * is set aside for an administrator: a REVOKE from the reader leaves a role's ALL ON *.* in place,
+ * and a direct administrator still reads everything, so either is reported. `read(name)` returns a
+ * user's or a role's SHOW GRANTS lines; a read that fails makes the check `unreadable`. `db` and
+ * `collisions` (wildcardOnRevoke's `colliding`: by table and by user; null when either could not be
+ * listed): a reader whose own member grant, `<db>.<their name>_*`, reaches
+ * this member's tables is a name collision, said as one, never "a grant memhouse did not make".
+ */
+async function revokeCheck({ read, user, known, wildcard, db = null, collisions = [] }) {
+  try {
+    const lines = await read(user);
+    // The reader's own member grant (`<db>.<reader>_*`, their own house) and another colliding
+    // member's wildcard (that member's grant to them) reach this member only through the collision.
+    // collisions null: the house's tables or users could not be listed, so a member-shaped wildcard
+    // (`<db>.<name>_*`) may be another member's own house, and is never called a stray grant.
+    const cs = collisions || [];
+    const own = cs.includes(user) ? `${db}.${user}_*` : null;
+    const others = new Map(cs.filter((c) => c !== user).map((c) => [`${db}.${c}_*`, c]));
+    const held = [...selectTargets(lines, known).on].filter((t) => t !== wildcard);
+    const memberShaped = (t) => collisions === null && t.startsWith(`${db}.`) && /^[^.*]+_\*$/.test(t.slice(db.length + 1));
+    const { via } = await reachThroughRoles(lines, known, read);
+    return revokeRoleReport({ user, via: via.filter((v) => v.on.size),
+      unlisted: held.filter(memberShaped),
+      direct: held.filter((t) => t !== own && !others.has(t) && !memberShaped(t)),
+      collision: held.filter((t) => t === own),
+      collisionOther: held.filter((t) => others.has(t)).map((t) => ({ target: t, member: others.get(t) })) });
+  } catch (e) {
+    return revokeRoleReport({ user, via: [], unreadable: String(e && e.message || e).split('\n')[0] });
+  }
+}
+
+/** --v3-shares: each reader's role-held access to the member, as the difference that stops the move. */
+function roleDifferences(viaRole) {
+  return [...viaRole].map(([u, via]) => `${u}: holds ${via.map((v) => `${[...v.on].join(', ')} through role '${v.role}'`).join('; ')} — memhouse never shares through a role; settle it by hand`);
+}
+
+/** The 0.18 filters of one user on one member, by exact name and table, wherever the rooms are now. */
+function legacyPolicyDrops({ db, member, user, legacy, keep }) {
+  assertName(db, 'house'); assertName(member, 'member'); assertName(user, 'user');
+  const q2 = (fq) => fq.split('.').map(ident).join('.');
+  const out = [];
+  for (const r of LEGACY_ROOMS) {
+    const name = ident(policyName(user, r));
+    for (const fq of [`${db}.${member}_${r}`, legacy && legacy[r]].filter(Boolean)) {
+      if (keep && keep.includes(fq)) continue;
+      out.push({ phase: 'clear', sql: `DROP ROW POLICY IF EXISTS ${name} ON ${q2(fq)}` });
+    }
+  }
+  return out;
+}
+
+/** A meta share record's value -> { granted, scopeRaw } ('granted 2026-10-01 scope=project=x', 'revoked 2026-10-02'). */
+function parseShareRecord(value) {
+  const v = String(value || '');
+  const m = /^granted\b[^]*?(?:\sscope=(.+))?$/.exec(v);
+  return m ? { granted: true, scopeRaw: m[1] ? m[1].trim() : null } : { granted: false, scopeRaw: null };
+}
+
+/**
+ * One account's grants from membersAccess, told apart for a reader: its own tables, the tables
+ * of each member it reads (a share), and anything else (a hand-made grant, a wildcard reaching
+ * past its own name). A table belongs to the member whose name is left after the longest
+ * memhouse table name (MEMBER_TABLES) is taken off its end. `policies` are the row policies the
+ * reading credential can list ([{ short_name, table }]); null when it cannot, and then a share's
+ * scope is unknown.
+ * @returns {{ own: string[], shares: {from:string, tables:string[], scoped:boolean|null}[], other: string[] }}
+ */
+function describeAccess({ u, list }, { policies = null } = {}) {
+  const own = []; const other = []; const shared = new Map();
+  for (const label of list || []) {
+    const bare = String(label).replace(/ \(through role [^)]*\)$/, '');
+    const name = bare.includes('.') ? bare.slice(bare.lastIndexOf('.') + 1) : bare;
+    if (name === `${u}_*` || name === `${u}_`) { own.push(label); continue; }
+    const type = [...MEMBER_TABLES, 'session_units', 'session_sources'].filter((t) => name.endsWith(`_${t}`) && name.length > t.length + 1).sort((a, b) => b.length - a.length)[0];
+    const owner = type ? name.slice(0, -(type.length + 1)) : null;
+    if (owner === u) own.push(label);
+    else if (owner && !bare.includes('.') && V3_TABLES.concat(LEGACY_ROOMS).includes(type)) {
+      if (!shared.has(owner)) shared.set(owner, []);
+      shared.get(owner).push(label);
+    } else other.push(label);
+  }
+  const shares = [...shared.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([from, tables]) => ({
+    from, tables,
+    scoped: policies ? policies.some((p) => String(p.short_name).startsWith(`mh_share_${u}_`) && String(p.table).startsWith(`${from}_`)) : null,
+  }));
+  return { own, shares, other };
+}
+
+module.exports = { SCOPE_COLUMNS, parseScope, scopePredicate, policyName, V3_TABLES, scopePredicateV3, shareV3Plan, revokeV3Plan, parseShareRecord,
+  assertName, ident, qual, memberTargets, moveSharePlan, wildcardRevoke, memberCollisions, wildcardOnRevoke, holdsMemberGrant, collidingUsers, ownPolicies, showPoliciesRevokes, wildcardReachText, wildcardAdminLine, shareGate, selectTargets, rolesGranted, reachThroughRoles, revokeRoleReport, revokeCheck, classifyShare, legacyPolicyDrops, readLiveShares, membersGrantsSQL, MEMBERS_ROLE_GRANTS_SQL, membersAccess, describeAccess, roleDifferences, LEGACY_ROOMS };