memhouse 0.18.12 → 0.20.1

package/memhouse/house/schema-profile.sql.tpl

@@ -0,0 +1,398 @@
+-- memhouse's house tables as harness-sessions-sql's ClickHouse profile (step B1, tables and keys). The
+-- tables, columns, keys and engines are harness-sessions-sql's schema/clickhouse.sql (v1.0.0);
+-- memhouse adds, beside them:
+--   * the member prefix {m}_ and the archive database {db}_archive (spec §3: physical names);
+--   * on session_parts: first_seen (a first-seen time, never written into ts), folder, project,
+--     harness_version, text_len, origin, extra, and the search columns over text and output;
+--   * on sessions: the derived totals and rollups the readers use (counts, usage, tools, agents,
+--     days, links), folder/project/git_branch, started/ended, first_prompt, origin;
+--   * {m}_calls: a derived convenience (spec §3), one row per tool call;
+--   * on session_links: r_copied_usage, r_copied_messages and r_unverified, memhouse's own
+--     deployment columns (spec §4.8 leaves them out of content_sha). They are set on engine edges
+--     only (owner 'engine', profile-edges.js): a fork's usage rows that copy its origin's, which
+--     the rollup leaves out of the fork's totals (billed once, spec §4.5);
+--   * on {m}_session_sources (informative in the spec): the capture engine's bookkeeping.
+-- host: a machine (sessions-model/host/v0: 32 hex, or r- + 32 hex where no machine id can be read)
+-- or a service that holds the sessions itself (s- + 32 hex, the sessions-model v1.x service-host
+-- proposal: claude.ai's conversations); every host CHECK accepts all three forms.
+-- ts is Nullable and in no key or partition: ReplacingMergeTree replaces only inside a partition
+-- (harness-sessions-sql §3). No table is partitioned by time.
+--
+-- Rendered by schema-profile.js with {db} and {m}. Every statement is idempotent.
+
+CREATE TABLE IF NOT EXISTS {db}.{m}_session_parts (
+    host                 LowCardinality(String),
+    CONSTRAINT host_form CHECK match(host, '^([rs]-)?[0-9a-f]{32}$') OR adapter = 'legacy',
+    harness              LowCardinality(String),
+    harness_path         LowCardinality(String),
+    session_id           String,
+    incarnation          String,
+    message_id           String,
+    part_id              String,
+    part_index           UInt32,
+    parent_id            String DEFAULT '',
+    order_key            String,
+    agent_id             String DEFAULT '',
+    role                 LowCardinality(String),
+    source               LowCardinality(String) DEFAULT '',
+    to_user              Nullable(Bool),
+    to_model             Nullable(Bool),
+    status               LowCardinality(String),
+    state                LowCardinality(String),
+    on_active_branch     Nullable(Bool),
+    ts                   Nullable(DateTime64(3, 'UTC')),
+    requested_model      LowCardinality(String) DEFAULT '',
+    served_model         LowCardinality(String) DEFAULT '',
+    effort               LowCardinality(String) DEFAULT '',
+    response_id          String DEFAULT '',
+    message_aliases      Array(Tuple(id String, kind LowCardinality(String))),
+    cmp_sha              FixedString(64),
+    message_content_sha  FixedString(64),
+    kind                 LowCardinality(String),
+    text                 String DEFAULT '' CODEC(ZSTD(3)),
+    call_id              String DEFAULT '',
+    tool_name            LowCardinality(String) DEFAULT '',
+    args                 String DEFAULT '',
+    server               LowCardinality(String) DEFAULT '',
+    is_error             Nullable(Bool),
+    result_status        LowCardinality(String) DEFAULT '',
+    output               String DEFAULT '' CODEC(ZSTD(3)),
+    output_ref           String DEFAULT '',
+    output_ref_sha256    String DEFAULT '',
+    output_ref_bytes     Nullable(UInt64),
+    output_len           Nullable(UInt64),
+    truncated            Nullable(Bool),
+    exit_code            Nullable(Int32),
+    media_type           LowCardinality(String) DEFAULT '',
+    inline_b64           String DEFAULT '' CODEC(ZSTD(3)),
+    ref                  String DEFAULT '',
+    bytes_len            Nullable(UInt64),
+    opaque               Nullable(Bool),
+    signature_len        Nullable(UInt32),
+    replaces_form        LowCardinality(String) DEFAULT '',
+    replaces_value       String DEFAULT '',
+    error_kind           LowCardinality(String) DEFAULT '',
+    error_message        String DEFAULT '',
+    http_status          Nullable(UInt16),
+    level                LowCardinality(String) DEFAULT '',
+    native_type          LowCardinality(String) DEFAULT '',
+    part_source          LowCardinality(String) DEFAULT '',
+    part_state           LowCardinality(String) DEFAULT '',
+    content_sha          FixedString(64),
+    adapter              LowCardinality(String),
+    adapter_ver          LowCardinality(String),
+    model_version        LowCardinality(String),
+    rev                  UInt64,
+    is_deleted           UInt8 DEFAULT 0,
+    removed              UInt8 DEFAULT 0,
+    ingested_at          DateTime64(3, 'UTC') DEFAULT now64(3),
+    writer               String MATERIALIZED currentUser(),
+    -- memhouse's columns
+    first_seen           DateTime64(3, 'UTC'),   -- when this host first saw the message; ts stays the native time or null
+    harness_version      LowCardinality(String) DEFAULT '',
+    folder               String DEFAULT '',
+    project              String DEFAULT '',
+    text_len             UInt32 DEFAULT 0,       -- characters of text before any cap
+    origin               LowCardinality(String) DEFAULT 'ship',  -- ship | import | legacy
+    extra                String DEFAULT '{}',
+    search_ngram         String MATERIALIZED lower(concat(text, '\n', output)),   -- search reads text and output (B-Q2)
+    search_word          String MATERIALIZED lower(concat(text, '\n', output)),
+    INDEX idx_search_ngram search_ngram TYPE text(tokenizer = ngrams(3)) GRANULARITY 1,
+    INDEX idx_search_word  search_word  TYPE text(tokenizer = splitByNonAlpha) GRANULARITY 1,
+    INDEX idx_ts           ts           TYPE minmax GRANULARITY 1,
+    INDEX idx_first_seen   first_seen   TYPE minmax GRANULARITY 1
+) ENGINE = ReplacingMergeTree(rev, is_deleted)
+ORDER BY (host, harness, harness_path, session_id, incarnation, message_id, part_id)
+SETTINGS index_granularity = 512, allow_experimental_replacing_merge_with_cleanup = 1;
+
+CREATE TABLE IF NOT EXISTS {db}.{m}_sessions (
+    host             LowCardinality(String),
+    CONSTRAINT host_form CHECK match(host, '^([rs]-)?[0-9a-f]{32}$') OR adapter = 'legacy',
+    host_label       String DEFAULT '',
+    harness          LowCardinality(String),
+    harness_path     LowCardinality(String),
+    session_id       String,
+    incarnation      String,
+    engine           LowCardinality(String) DEFAULT '',
+    client           LowCardinality(String) DEFAULT '',
+    harness_version  LowCardinality(String) DEFAULT '',
+    title            String DEFAULT '',
+    title_set_by     LowCardinality(String) DEFAULT 'unknown',
+    cwd              String DEFAULT '',
+    last_cwd         String DEFAULT '',
+    created_at       Nullable(DateTime64(3, 'UTC')),
+    updated_at       Nullable(DateTime64(3, 'UTC')),
+    state            LowCardinality(String),
+    pinned           Nullable(Bool),
+    mode             LowCardinality(String) DEFAULT '',
+    kind             LowCardinality(String) DEFAULT '',
+    reuse            LowCardinality(String),
+    ts_source        LowCardinality(String),           -- a registry (spec §2, principle 7): any value is kept
+    aliases          Array(Tuple(id String, kind LowCardinality(String))),
+    fingerprint      Array(FixedString(64)),
+    setup            Nullable(String),
+    content_sha      FixedString(64),
+    adapter          LowCardinality(String),
+    adapter_ver      LowCardinality(String),
+    model_version    LowCardinality(String),
+    rev              UInt64,
+    is_deleted       UInt8 DEFAULT 0,
+    removed          UInt8 DEFAULT 0,
+    ingested_at      DateTime64(3, 'UTC') DEFAULT now64(3),
+    writer           String MATERIALIZED currentUser(),
+    -- memhouse's derived columns (from the session's parts, usage and links)
+    folder             String DEFAULT '',        -- the first cwd seen
+    project            String DEFAULT '',
+    git_branch         String DEFAULT '',
+    started            Nullable(DateTime64(3, 'UTC')),
+    ended              Nullable(DateTime64(3, 'UTC')),
+    messages           UInt32 DEFAULT 0,         -- kind = 'text' rows only
+    user_messages      UInt32 DEFAULT 0,
+    assistant_messages UInt32 DEFAULT 0,
+    agent_messages     UInt32 DEFAULT 0,
+    tool_calls         UInt32 DEFAULT 0,
+    input_tokens       UInt64 DEFAULT 0,         -- the house split, applied by the reader rules (flags, per_record once per response)
+    output_tokens      UInt64 DEFAULT 0,
+    cache_read_tokens  UInt64 DEFAULT 0,
+    cache_write_tokens UInt64 DEFAULT 0,
+    reasoning_tokens   UInt64 DEFAULT 0,
+    user_chars         UInt64 DEFAULT 0,
+    assistant_chars    UInt64 DEFAULT 0,
+    first_prompt       String DEFAULT '',
+    models             Array(LowCardinality(String)),
+    dominant_model     LowCardinality(String) DEFAULT '',
+    days               Array(Date),
+    usage Nested(
+        hour        DateTime('UTC'),
+        model       LowCardinality(String),
+        messages    UInt32,
+        input       UInt64,
+        output      UInt64,
+        cache_read  UInt64,
+        cache_write UInt64,
+        reasoning   UInt64
+    ),
+    tools Nested(name LowCardinality(String), calls UInt32, errors UInt32),
+    agents Nested(
+        agent_id    String,
+        type        LowCardinality(String),
+        description String,
+        workflow    String,
+        messages    UInt32,
+        first_ts    DateTime64(3, 'UTC')
+    ),
+    links Nested(                                -- derived from session_links, for the readers
+        kind        LowCardinality(String),
+        origin      String,
+        origin_store String,
+        evidence    LowCardinality(String),
+        at          String,
+        through     String
+    ),
+    origin             LowCardinality(String) DEFAULT 'ship'
+) ENGINE = ReplacingMergeTree(rev, is_deleted)
+ORDER BY (host, harness, harness_path, session_id, incarnation);
+
+CREATE TABLE IF NOT EXISTS {db}.{m}_session_usage (
+    host           LowCardinality(String),
+    CONSTRAINT host_form CHECK match(host, '^([rs]-)?[0-9a-f]{32}$') OR adapter = 'legacy',
+    harness        LowCardinality(String),
+    harness_path   LowCardinality(String),
+    session_id     String,
+    incarnation    String,
+    usage_id       String,
+    anchor_kind    LowCardinality(String),
+    anchor_id      String DEFAULT '',
+    input          Nullable(UInt64),
+    output         Nullable(UInt64),
+    cache_read     Nullable(UInt64),
+    cache_write    Nullable(UInt64),
+    reasoning      Nullable(UInt64),
+    tool_prompt    Nullable(UInt64),
+    cost           Nullable(Decimal(18, 9)),
+    input_includes_cache      Nullable(Bool),
+    output_includes_reasoning Nullable(Bool),
+    granularity    LowCardinality(String),
+    model          LowCardinality(String) DEFAULT '',
+    content_sha    FixedString(64),
+    adapter        LowCardinality(String),
+    adapter_ver    LowCardinality(String),
+    model_version  LowCardinality(String),
+    rev            UInt64,
+    is_deleted     UInt8 DEFAULT 0,
+    removed        UInt8 DEFAULT 0,
+    ingested_at    DateTime64(3, 'UTC') DEFAULT now64(3),
+    writer         String MATERIALIZED currentUser(),
+    -- memhouse's columns
+    ts             Nullable(DateTime64(3, 'UTC')),   -- the anchor's time, for hourly rollups
+    origin         LowCardinality(String) DEFAULT 'ship'
+) ENGINE = ReplacingMergeTree(rev, is_deleted)
+ORDER BY (host, harness, harness_path, session_id, incarnation, usage_id);
+
+CREATE TABLE IF NOT EXISTS {db}.{m}_session_links (
+    host                LowCardinality(String),
+    CONSTRAINT host_form CHECK match(host, '^([rs]-)?[0-9a-f]{32}$') OR adapter = 'legacy',
+    harness             LowCardinality(String),
+    harness_path        LowCardinality(String),
+    session_id          String,
+    incarnation         String,
+    owner               LowCardinality(String),
+    kind                LowCardinality(String),
+    other_host          LowCardinality(String) DEFAULT '',
+    CONSTRAINT other_host_form CHECK other_host = '' OR match(other_host, '^([rs]-)?[0-9a-f]{32}$') OR adapter = 'legacy',
+    other_harness_path  LowCardinality(String) DEFAULT '',
+    other_harness       LowCardinality(String),
+    other_session_id    String,
+    other_incarnation   String DEFAULT '',
+    at                  String DEFAULT '',
+    stated_on           LowCardinality(String),
+    child_host          LowCardinality(String) DEFAULT '',
+    CONSTRAINT child_host_form CHECK child_host = '' OR match(child_host, '^([rs]-)?[0-9a-f]{32}$') OR adapter = 'legacy',
+    child_harness_path  LowCardinality(String) DEFAULT '',
+    child_harness       LowCardinality(String),
+    child_session_id    String,
+    child_incarnation   Nullable(String),
+    origin_host         LowCardinality(String) DEFAULT '',
+    CONSTRAINT origin_host_form CHECK origin_host = '' OR match(origin_host, '^([rs]-)?[0-9a-f]{32}$') OR adapter = 'legacy',
+    origin_harness_path LowCardinality(String) DEFAULT '',
+    origin_harness      LowCardinality(String),
+    origin_session_id   String,
+    origin_incarnation  Nullable(String),
+    through_message_id  String DEFAULT '',
+    ids_preserved       Nullable(Bool),
+    marked              Nullable(Bool),
+    usage_copied        Nullable(Bool),
+    child_stored        Nullable(Bool),             -- null: unknown (a statement that does not say)
+    evidence            LowCardinality(String) DEFAULT 'explicit',
+    verified            Nullable(Bool),
+    statements          Array(Tuple(host String, harness String, harness_path String, session_id String, incarnation String)),
+    content_sha         FixedString(64),
+    adapter             LowCardinality(String),
+    adapter_ver         LowCardinality(String),
+    model_version       LowCardinality(String),
+    rev                 UInt64,
+    is_deleted          UInt8 DEFAULT 0,
+    removed             UInt8 DEFAULT 0,
+    ingested_at         DateTime64(3, 'UTC') DEFAULT now64(3),
+    writer              String MATERIALIZED currentUser(),
+    -- memhouse's deployment columns, on engine edges only (header)
+    r_copied_usage      Array(String) DEFAULT [],               -- the child's usage_ids that copy the origin's: not billed again
+    r_copied_messages   UInt32 DEFAULT 0,                       -- the verified copied prefix, in messages
+    r_unverified        String DEFAULT ''                       -- why the edge is not verified ('' when it is)
+) ENGINE = ReplacingMergeTree(rev, is_deleted)
+ORDER BY (host, harness, harness_path, session_id, incarnation, owner, kind, other_host, other_harness_path, other_harness, other_session_id, other_incarnation, at);
+
+CREATE TABLE IF NOT EXISTS {db}.{m}_session_lifecycle (
+    host            LowCardinality(String),
+    CONSTRAINT host_form CHECK match(host, '^([rs]-)?[0-9a-f]{32}$') OR adapter = 'legacy',
+    harness         LowCardinality(String),
+    harness_path    LowCardinality(String),
+    session_id      String,
+    incarnation     String,
+    lifecycle_id    String,
+    op              LowCardinality(String),
+    target_kind     LowCardinality(String),
+    target_id       String DEFAULT '',
+    target_from     String DEFAULT '',
+    target_through  String DEFAULT '',
+    at              String DEFAULT '',
+    ts              Nullable(DateTime64(3, 'UTC')),
+    evidence        LowCardinality(String) DEFAULT 'explicit',
+    content_sha     FixedString(64),
+    adapter         LowCardinality(String),
+    adapter_ver     LowCardinality(String),
+    model_version   LowCardinality(String),
+    rev             UInt64,
+    is_deleted      UInt8 DEFAULT 0,
+    removed         UInt8 DEFAULT 0,
+    ingested_at     DateTime64(3, 'UTC') DEFAULT now64(3),
+    writer          String MATERIALIZED currentUser()
+) ENGINE = ReplacingMergeTree(rev, is_deleted)
+ORDER BY (host, harness, harness_path, session_id, incarnation, lifecycle_id);
+
+-- memhouse's derived convenience: one row per tool call (spec §3 allows it).
+CREATE TABLE IF NOT EXISTS {db}.{m}_calls (
+    host           LowCardinality(String),
+    CONSTRAINT host_form CHECK match(host, '^([rs]-)?[0-9a-f]{32}$') OR adapter = 'legacy',
+    harness        LowCardinality(String),
+    harness_path   LowCardinality(String),
+    session_id     String,
+    incarnation    String,
+    call_id        String,
+    message_id     String,
+    agent_id       String DEFAULT '',
+    ts             Nullable(DateTime64(3, 'UTC')),
+    first_seen     DateTime64(3, 'UTC'),
+    tool_name      LowCardinality(String),
+    args           String DEFAULT '',
+    result_ts      Nullable(DateTime64(3, 'UTC')),
+    is_error       Nullable(Bool),
+    output_len     Nullable(UInt64),
+    model          LowCardinality(String) DEFAULT '',
+    folder         String DEFAULT '',
+    project        String DEFAULT '',
+    content_sha    FixedString(64),          -- the tool_call part's sha (as session_parts)
+    adapter        LowCardinality(String),
+    adapter_ver    LowCardinality(String),
+    rev            UInt64,
+    is_deleted     UInt8 DEFAULT 0,
+    removed        UInt8 DEFAULT 0,
+    ingested_at    DateTime64(3, 'UTC') DEFAULT now64(3),
+    writer         String MATERIALIZED currentUser(),
+    INDEX idx_first_seen first_seen TYPE minmax GRANULARITY 1
+) ENGINE = ReplacingMergeTree(rev, is_deleted)
+ORDER BY (host, harness, harness_path, session_id, incarnation, call_id);
+
+CREATE TABLE IF NOT EXISTS {db}_archive.{m}_session_units (
+    host          LowCardinality(String),
+    CONSTRAINT host_form CHECK match(host, '^([rs]-)?[0-9a-f]{32}$'),
+    harness       LowCardinality(String),
+    harness_path  LowCardinality(String),
+    session_id    String,
+    incarnation   String,
+    source_key    String,
+    generation    UInt32,
+    unit_key      String,
+    chunk         UInt16 DEFAULT 0,
+    sha256        FixedString(64),
+    enc           LowCardinality(String),           -- a registry (spec §2, principle 7): any value is kept
+    orig_sha256   Nullable(FixedString(64)),        -- null when the unit has none (harness-sessions-sql §4.1)
+    redacted      Bool DEFAULT false,
+    continuity    LowCardinality(String),
+    raw           String CODEC(ZSTD(3)),
+    adapter       LowCardinality(String),
+    adapter_ver   LowCardinality(String),
+    captured_at   DateTime64(3, 'UTC') DEFAULT now64(3),
+    writer        String MATERIALIZED currentUser()
+) ENGINE = ReplacingMergeTree
+ORDER BY (host, harness, harness_path, session_id, incarnation, source_key, generation, unit_key, chunk, sha256);
+
+CREATE TABLE IF NOT EXISTS {db}_archive.{m}_session_sources (
+    host               LowCardinality(String),
+    CONSTRAINT host_form CHECK match(host, '^([rs]-)?[0-9a-f]{32}$'),
+    harness            LowCardinality(String),
+    harness_path       LowCardinality(String),
+    session_id         String,
+    incarnation        String,
+    source_key         String,
+    mode               LowCardinality(String),
+    position           String DEFAULT '',
+    generation         UInt32,
+    progress           UInt64,
+    state              String DEFAULT '' CODEC(ZSTD(1)),
+    state_ver          UInt32,
+    adapter            LowCardinality(String),
+    adapter_ver        LowCardinality(String),
+    committed_at       DateTime64(3, 'UTC') DEFAULT now64(3),
+    ver                UInt64 MATERIALIZED (toUInt64(generation) * 1099511627776) + progress,
+    writer             String MATERIALIZED currentUser(),
+    -- memhouse's bookkeeping
+    role               LowCardinality(String) DEFAULT 'main',   -- main | agent | side | legacy | inherited
+    agent_id           String DEFAULT '',
+    agent_type         LowCardinality(String) DEFAULT '',
+    agent_desc         String DEFAULT '',
+    known              String DEFAULT '' CODEC(ZSTD(1)),   -- delta sources: the current unit keys and shas
+    contrib            String DEFAULT '{}' CODEC(ZSTD(1)), -- this source's exact share of the session totals
+    is_deleted         UInt8 DEFAULT 0
+) ENGINE = ReplacingMergeTree(ver)
+ORDER BY (host, harness, harness_path, session_id, incarnation, source_key);

package/memhouse/house/schema-v3.js

@@ -0,0 +1,267 @@
+// Schema v3 (source identity, docs/design/source-identity.md draft 5): the five tables of
+// one member, in two databases.
+//
+//   <db>.<m>_turns, <m>_calls, <m>_sessions     conversation layer — harness-agnostic, read
+//                                                by everything, under the member's existing
+//                                                `<db>.<m>_*` grant
+//   <db>_archive.<m>_records, <m>_files          capture layer — the shipper only; SELECT and
+//                                                INSERT for the member, no grant option, and
+//                                                nothing in <db>_archive is granted to anyone else
+//
+// The DDL lives in schema-v3.sql.tpl, rendered here with {db} and {m}. Every statement is
+// CREATE … IF NOT EXISTS, so creating a member's tables is idempotent and safe to repeat.
+//
+// Transport-free, like migrate.js: every entry point takes `q` — `sql(text, settings)` and
+// `rows(text, settings) -> object[]`. The CLI builds one over HTTP; qFromClient() below
+// builds one over @clickhouse/client for the shipper. Settings follow ensureSchema's
+// conventions: async_insert = 0 on everything (user_id is MATERIALIZED currentUser(), and an
+// async insert can land it empty), allow_experimental_full_text_index = 1 on CREATE (25.11
+// still gates the text index behind it), and the pre-25.10 text-index grammar as a fallback.
+
+const fs = require('fs');
+const path = require('path');
+const {
+  assertUsableName, legacyTextIndexDialect, isTextIndexGrammarRefusal, textIndexDialectFor,
+} = require('./house');
+
+const TEMPLATE = path.join(__dirname, 'schema-v3.sql.tpl');
+
+const CONVERSATION_TYPES = ['turns', 'calls', 'sessions'];
+const CAPTURE_TYPES = ['records', 'files'];
+const V3_TYPES = [...CONVERSATION_TYPES, ...CAPTURE_TYPES];
+// The legacy rooms, renamed into the archive database at migration (draft 5 §7 step 7) — in
+// the first build they are restored there directly from the production backup.
+const LEGACY_TYPES = ['messages', 'tool_calls', 'sessions'];
+const LEGACY_SUFFIX = 'pre_v3';
+
+/**
+ * The sorting key of each table exactly as `system.tables.sorting_key` reports it (layout 3.2:
+ * the session's store — host, harness_path, incarnation — in every key). The 3.1 keys were
+ * measured on 25.11.9.34, 26.7.4.58 and 26.8.16.41; 3.2 is checked by the house test. Canonical here so a verifier, doctor and a test
+ * all compare against one copy (the lesson of ROOM_KEYS in house.js).
+ */
+const V3_KEYS = {
+  turns: 'toDate(ts), harness, host, harness_path, session_id, incarnation, ts, message_id, part_id',
+  calls: 'toDate(ts), harness, host, harness_path, session_id, incarnation, ts, call_id',
+  sessions: 'harness, host, harness_path, session_id, incarnation',
+  records: 'harness, host, harness_path, session_id, incarnation, file_key, fgen, pos, chunk, sha',
+  files: 'harness, host, harness_path, session_id, incarnation, file_key',
+};
+
+/**
+ * Columns the server fills and a writer must never send: MATERIALIZED ones (refused, or —
+ * under insert_allow_materialized_columns — forged) and the ingest clock. The build contract's
+ * "row shape" is the template's columns minus these.
+ */
+const SERVER_COLUMNS = ['user_id', 'ingested_at', 'text_ngram', 'text_word', 'ver', 'captured_at', 'committed_at'];
+
+function archiveDb(db) { return `${db}_archive`; }
+
+/** Every fully-qualified name this schema touches for one member. The only place they are built. */
+function v3Names(db, member) {
+  assertUsableName(db, 'house');
+  assertUsableName(member, 'member');
+  const a = archiveDb(db);
+  const out = { db, archive: a, member };
+  for (const t of CONVERSATION_TYPES) out[t] = `${db}.${member}_${t}`;
+  for (const t of CAPTURE_TYPES) out[t] = `${a}.${member}_${t}`;
+  out.legacy = {};
+  for (const t of LEGACY_TYPES) out.legacy[t] = `${a}.${member}_${t}_${LEGACY_SUFFIX}`;
+  // The member's own record of itself, unchanged from 0.18 (house.js META_TYPES).
+  out.meta = `${db}.${member}_meta`;
+  out.events = `${db}.${member}_events`;
+  return out;
+}
+
+function readTemplate() { return fs.readFileSync(TEMPLATE, 'utf-8'); }
+
+/** The template with comments removed — line comments only; the template has no `--` inside strings. */
+function stripComments(tpl) {
+  return tpl.split('\n').map((l) => l.replace(/--.*$/, '')).join('\n');
+}
+
+/**
+ * The CREATE statements for one member, in template order:
+ *   [{ type: 'turns', database: 'mem', table: 'dana_turns', fq: 'mem.dana_turns', sql }]
+ * Comments are stripped BEFORE the ';' split — the template's comments may contain ';'.
+ */
+function renderStatements(tpl, { db, member }) {
+  assertUsableName(db, 'house');
+  assertUsableName(member, 'member');
+  const body = stripComments(tpl).replaceAll('{db}', db).replaceAll('{m}', member);
+  const out = [];
+  for (const raw of body.split(';')) {
+    const sql = raw.trim();
+    if (!sql) continue;
+    const m = /^CREATE TABLE IF NOT EXISTS ([A-Za-z0-9_]+)\.([A-Za-z0-9_]+)\s*\(/.exec(sql);
+    if (!m) throw new Error(`schema-v3 template: unexpected statement: ${sql.slice(0, 80)}`);
+    const type = m[2].startsWith(`${member}_`) ? m[2].slice(member.length + 1) : m[2];
+    if (!V3_TYPES.includes(type)) throw new Error(`schema-v3 template declares an unknown table '${m[2]}'`);
+    out.push({ type, database: m[1], table: m[2], fq: `${m[1]}.${m[2]}`, sql });
+  }
+  const missing = V3_TYPES.filter((t) => !out.some((s) => s.type === t));
+  if (missing.length) throw new Error(`schema-v3 template is missing: ${missing.join(', ')}`);
+  return out;
+}
+
+/**
+ * The columns each table declares, as [{ name, type }] — type text includes DEFAULT /
+ * MATERIALIZED / CODEC. A Nested column is ONE entry here (`usage`, type `Nested(…)`);
+ * on the server it becomes `usage.hour`, `usage.model`, … arrays.
+ */
+function templateColumns(tpl) {
+  const out = {};
+  for (const s of renderStatements(tpl, { db: 'db', member: 'm' })) {
+    const inner = s.sql.slice(s.sql.indexOf('(') + 1, s.sql.search(/\)\s*ENGINE\b/));
+    const cols = [];
+    let depth = 0; let buf = '';
+    for (const ch of inner + ',') {
+      if (ch === '(') depth++;
+      if (ch === ')') depth--;
+      if (ch === ',' && depth === 0) {
+        const decl = buf.replace(/\s+/g, ' ').trim();
+        buf = '';
+        if (!decl || /^(INDEX|CONSTRAINT|PROJECTION)\b/i.test(decl)) continue;
+        const sp = decl.indexOf(' ');
+        cols.push({ name: decl.slice(0, sp), type: decl.slice(sp + 1) });
+        continue;
+      }
+      buf += ch;
+    }
+    out[s.type] = cols;
+  }
+  return out;
+}
+
+/** What a writer sends for a table: the template's columns minus the server-filled ones. */
+function rowColumns(tpl, type) {
+  return (templateColumns(tpl)[type] || []).map((c) => c.name).filter((n) => !SERVER_COLUMNS.includes(n));
+}
+
+/** What is wrong with a v3 table's sorting key, or null. */
+function keyProblem(type, sortingKey) {
+  const want = V3_KEYS[type];
+  if (!want) return `'${type}' is not a v3 table`;
+  const have = String(sortingKey || '').trim();
+  if (!have) return 'not a MergeTree';
+  return have === want ? null : `(${have}) — expected (${want})`;
+}
+
+/**
+ * The capture layer's grants for a member (draft 5 §1): SELECT and INSERT on their own two
+ * tables, WITHOUT grant option — a member must not be able to hand the exact copy of their
+ * transcripts to a share. The conversation tables need nothing new: they sit inside the
+ * member's existing `<db>.<m>_*` wildcard.
+ */
+function captureGrants(db, member) {
+  const n = v3Names(db, member);
+  return CAPTURE_TYPES.map((t) => `GRANT SELECT, INSERT ON ${n[t]} TO ${member}`);
+}
+
+const DDL_SETTINGS = { async_insert: 0, allow_experimental_full_text_index: 1 };
+
+function isDenied(m) { return /Not enough privileges|ACCESS_DENIED/i.test(m); }
+function isExists(m) { return /ALREADY_EXISTS|already exists/i.test(m); }
+function msg(e) { return e && e.message ? e.message : String(e); }
+
+/**
+ * Create one member's v3 tables. Idempotent.
+ *
+ *   createDatabases  also CREATE DATABASE IF NOT EXISTS <db> and <db>_archive (admin)
+ *   grantCapture     also grant the member SELECT, INSERT on the two capture tables (admin)
+ *
+ * Mirrors ensureSchema: a privilege denial is counted and skipped (a member re-running this
+ * on tables an admin made must not fail), a lost create race is the outcome we wanted. Then
+ * the tables are VERIFIED against V3_KEYS — the rooms are the truth, not the statements.
+ *
+ * @returns {{ version, dialect, created: string[], denied: string[], grants: string[],
+ *             grant_failures: string[], tables: Object<type, {fq, exists, problem}>, ok: boolean }}
+ */
+async function ensureV3Schema(q, { db, member, createDatabases = false, grantCapture = false, tpl = null } = {}, ui = null) {
+  const n = v3Names(db, member);
+  const say = (m) => ui && ui.ok && ui.ok(m);
+  const version = String(((await q.rows('SELECT version() AS v', { final: 0 }))[0] || {}).v || '');
+  const dialect = textIndexDialectFor(version);
+  const out = { version, dialect, created: [], denied: [], grants: [], grant_failures: [], tables: {}, ok: false };
+
+  if (createDatabases) {
+    for (const d of [n.db, n.archive]) {
+      try { await q.sql(`CREATE DATABASE IF NOT EXISTS ${d}`, DDL_SETTINGS); }
+      catch (e) {
+        const m = msg(e);
+        if (isDenied(m)) out.denied.push(`CREATE DATABASE ${d}`);
+        else if (!isExists(m)) throw e;
+      }
+    }
+  }
+
+  for (const s of renderStatements(tpl || readTemplate(), { db, member })) {
+    const modern = s.sql;
+    const legacy = legacyTextIndexDialect(modern);
+    const [first, second] = dialect === 'legacy' ? [legacy, modern] : [modern, legacy];
+    try {
+      try { await q.sql(first, DDL_SETTINGS); }
+      catch (e) {
+        if (!(first !== second && isTextIndexGrammarRefusal(msg(e)))) throw e;
+        await q.sql(second, DDL_SETTINGS);
+      }
+      out.created.push(s.fq);
+    } catch (e) {
+      const m = msg(e);
+      if (isDenied(m)) { out.denied.push(`CREATE TABLE ${s.fq}`); continue; }
+      if (isExists(m)) { out.created.push(s.fq); continue; }
+      throw new Error(`${s.fq}: ${m.split('\n')[0]}`);
+    }
+  }
+
+  if (grantCapture) {
+    // Never fatal: the tables are what this function guarantees. A grant can fail for a
+    // reason that is not a privilege — the member has no ClickHouse user of that name yet —
+    // and the caller reports it.
+    for (const g of captureGrants(db, member)) {
+      try { await q.sql(g, DDL_SETTINGS); out.grants.push(g); }
+      catch (e) {
+        const m = msg(e);
+        if (isDenied(m)) out.denied.push(g);
+        else out.grant_failures.push(`${g}: ${m.split('\n')[0]}`);
+      }
+    }
+  }
+
+  const rows = await q.rows(
+    `SELECT database, name, sorting_key FROM system.tables
+     WHERE (database = '${n.db}' AND name IN (${CONVERSATION_TYPES.map((t) => `'${member}_${t}'`).join(', ')}))
+        OR (database = '${n.archive}' AND name IN (${CAPTURE_TYPES.map((t) => `'${member}_${t}'`).join(', ')}))`,
+    { final: 0 });
+  let ok = true;
+  for (const t of V3_TYPES) {
+    const fq = n[t];
+    const r = rows.find((x) => `${x.database}.${x.name}` === fq);
+    const problem = r ? keyProblem(t, r.sorting_key) : 'missing';
+    if (problem) ok = false;
+    out.tables[t] = { fq, exists: Boolean(r), problem };
+  }
+  out.ok = ok;
+  if (ok) say(`v3 tables for ${member}: ${V3_TYPES.map((t) => n[t]).join(', ')}`);
+  return out;
+}
+
+/**
+ * A `q` over @clickhouse/client — the shipper's transport. Same settings in, same rows out.
+ */
+function qFromClient(client) {
+  return {
+    sql: async (text, settings = {}) => { await client.command({ query: text, clickhouse_settings: settings }); },
+    rows: async (text, settings = {}) => {
+      const rs = await client.query({ query: text, format: 'JSONEachRow', clickhouse_settings: settings });
+      return rs.json();
+    },
+  };
+}
+
+module.exports = {
+  TEMPLATE, CONVERSATION_TYPES, CAPTURE_TYPES, V3_TYPES, LEGACY_TYPES, LEGACY_SUFFIX,
+  V3_KEYS, SERVER_COLUMNS,
+  archiveDb, v3Names, readTemplate, stripComments, renderStatements, templateColumns, rowColumns,
+  keyProblem, captureGrants, ensureV3Schema, qFromClient, DDL_SETTINGS,
+};