memhouse 0.18.12 → 0.20.1

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

@@ -0,0 +1,213 @@
+-- memhouse schema v3, layout 3.2 (plan v4, docs/design/sessions-engine.md): a session belongs to its
+-- harness store (host, harness, harness_path, session_id, incarnation); content that left the source is
+-- kept as a removed version (removed = 1), tombstones only for duplicates.
+-- Origin: docs/design/source-identity.md, draft 5.
+-- Placeholders: {db} = the house database (e.g. mem), {m} = the member (e.g. alice).
+-- Conversation layer lives in {db}; capture layer in {db}_archive.
+-- Text indexes need SETTINGS allow_experimental_full_text_index = 1 on 25.11 (as today).
+
+CREATE TABLE IF NOT EXISTS {db}.{m}_turns (
+    harness            LowCardinality(String),
+    harness_version    LowCardinality(String),
+    harness_path       LowCardinality(String),   -- the harness's store: its data folder, absolute and symlink-resolved (~/.claude, a playbook dir, ~/.codex); for OpenCode, the DB file
+    session_id         String,
+    incarnation        String DEFAULT '',        -- '' unless the harness reuses ids inside one store
+    agent_id           String DEFAULT '',        -- '' = main conversation; else the sub-agent's id
+    message_id         String,                   -- native id (Codex: payload.id, else '@<byte offset>')
+    part_id            String DEFAULT '',        -- the part's id within the message (native, a ':call'/':result' suffix, or an index)
+    part_ord           UInt32 DEFAULT 0,         -- the part's order within the message
+    parent_id          String DEFAULT '',
+    response_id        String DEFAULT '',        -- billing unit: Claude message.id, Codex turn id
+    ts                 DateTime64(3, 'UTC'),     -- the source's own; never changes (§2)
+    ord                UInt64,                   -- display tie-break within equal ts (capture order)
+    rev                UInt64,                   -- fgen·2^40 + upto (§2)
+    is_deleted         UInt8 DEFAULT 0,          -- physical delete marker: duplicates only (dedupe, adapter upgrade)
+    removed            UInt8 DEFAULT 0,          -- 1 = left the source; kept, searchable, not current
+    state              LowCardinality(String) DEFAULT '',   -- the editor's message state: '' | current | reverted | retracted
+    role               LowCardinality(String),   -- user | assistant | system | tool
+    kind               LowCardinality(String),   -- text | thinking | tool_call | tool_result | summary | usage | none (header)
+    model              LowCardinality(String) DEFAULT '',
+    effort             LowCardinality(String) DEFAULT '',
+    input_tokens       UInt64 DEFAULT 0,         -- on exactly one row per response_id
+    output_tokens      UInt64 DEFAULT 0,
+    cache_read_tokens  UInt64 DEFAULT 0,
+    cache_write_tokens UInt64 DEFAULT 0,
+    reasoning_tokens   UInt64 DEFAULT 0,
+    text               String CODEC(ZSTD(3)),    -- full text, tool output included (layout 3.2)
+    text_len           UInt32,
+    folder             String DEFAULT '',
+    project            String DEFAULT '',
+    host               LowCardinality(String),
+    origin             LowCardinality(String) DEFAULT 'ship',   -- ship | import | legacy
+    extra              String DEFAULT '{}',
+    adapter_ver        UInt32,
+    user_id            String MATERIALIZED currentUser(),
+    ingested_at        DateTime64(3, 'UTC') DEFAULT now64(3),
+    -- Two lowercase copies, not one: ClickHouse allows ONE text index per column (measured on
+    -- 25.11.9.34 and 26.7.4.58: "Column `text_lc` must not have more than one text index").
+    -- Same names and shape as the 0.18 rooms, so the read layer's search predicates carry over.
+    text_ngram         String MATERIALIZED lower(text),
+    text_word          String MATERIALIZED lower(text),
+    INDEX idx_text_ngram text_ngram TYPE text(tokenizer = ngrams(3)) GRANULARITY 1,
+    INDEX idx_text_word  text_word  TYPE text(tokenizer = splitByNonAlpha) GRANULARITY 1,
+    INDEX idx_ts         ts      TYPE minmax GRANULARITY 1
+) ENGINE = ReplacingMergeTree(rev, is_deleted)
+-- By month: a key's versions share its ts, so they share a partition; FINAL and the tombstone
+-- cleanup work one month at a time, and a cleanup rewrites only the months that hold tombstones.
+PARTITION BY toYYYYMM(ts)
+ORDER BY (toDate(ts), harness, host, harness_path, session_id, incarnation, ts, message_id, part_id)
+-- 512, not 2048: a term that appears in many sessions still lands in only the granules that hold it
+-- (search read 30–60% fewer rows on a real house, 2026-10-16). Cleanup: tombstones are dropped by
+-- OPTIMIZE … FINAL CLEANUP (memhouse/shipper/maintenance.js).
+SETTINGS index_granularity = 512, allow_experimental_replacing_merge_with_cleanup = 1;
+
+CREATE TABLE IF NOT EXISTS {db}.{m}_calls (
+    harness        LowCardinality(String),
+    harness_path   LowCardinality(String) DEFAULT '',
+    session_id     String,
+    incarnation    String DEFAULT '',
+    agent_id       String DEFAULT '',
+    call_id        String,                       -- native: Claude tool_use.id, Codex call_id
+    message_id     String,
+    ts             DateTime64(3, 'UTC'),         -- when the call was issued; never changes
+    rev            UInt64,
+    is_deleted     UInt8 DEFAULT 0,
+    removed        UInt8 DEFAULT 0,
+    tool_name      LowCardinality(String),
+    args           String DEFAULT '{}',
+    result_ts      Nullable(DateTime64(3, 'UTC')),
+    is_error       Bool DEFAULT false,
+    result_len     UInt32 DEFAULT 0,
+    model          LowCardinality(String) DEFAULT '',
+    folder         String DEFAULT '',
+    project        String DEFAULT '',
+    host           LowCardinality(String),
+    adapter_ver    UInt32,
+    user_id        String MATERIALIZED currentUser(),
+    ingested_at    DateTime64(3, 'UTC') DEFAULT now64(3),
+    INDEX idx_tool tool_name TYPE set(1024) GRANULARITY 1,
+    INDEX idx_ts   ts        TYPE minmax    GRANULARITY 1
+) ENGINE = ReplacingMergeTree(rev, is_deleted)
+PARTITION BY toYYYYMM(ts)
+ORDER BY (toDate(ts), harness, host, harness_path, session_id, incarnation, ts, call_id)
+SETTINGS index_granularity = 2048, allow_experimental_replacing_merge_with_cleanup = 1;
+
+CREATE TABLE IF NOT EXISTS {db}.{m}_sessions (
+    harness            LowCardinality(String),
+    session_id         String,
+    incarnation        String DEFAULT '',
+    harness_version    LowCardinality(String),
+    harness_path       LowCardinality(String),
+    host               LowCardinality(String),   -- sessions-model/host/v0: from the OS machine id, never the hostname
+    host_label         LowCardinality(String) DEFAULT '',  -- the machine's short hostname, for display only; never in a key
+    name               String,
+    mode               LowCardinality(String),
+    folder             String,
+    project            String,
+    git_branch         String,
+    created_at         Nullable(DateTime64(3, 'UTC')),
+    updated_at         Nullable(DateTime64(3, 'UTC')),
+    started            DateTime64(3, 'UTC'),
+    ended              DateTime64(3, 'UTC'),
+    messages           UInt32,                   -- kind = 'text' rows only (parity with legacy counts)
+    user_messages      UInt32,
+    assistant_messages UInt32,
+    agent_messages     UInt32,
+    tool_calls         UInt32,
+    input_tokens       UInt64,
+    output_tokens      UInt64,
+    cache_read_tokens  UInt64,
+    cache_write_tokens UInt64,
+    reasoning_tokens   UInt64,
+    user_chars         UInt64,
+    assistant_chars    UInt64,
+    first_prompt       String,                   -- first user row of the main conversation
+    models             Array(LowCardinality(String)),
+    dominant_model     LowCardinality(String),
+    days               Array(Date),              -- days with activity: readSession reads only these
+    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(                               -- readable sub-agent metadata (opus)
+        agent_id    String,
+        type        LowCardinality(String),
+        description String,
+        workflow    String,
+        messages    UInt32,
+        first_ts    DateTime64(3, 'UTC')
+    ),
+    links Nested(                                -- sessions-model links stated by this session (log session record)
+        kind        LowCardinality(String),      -- fork | subagent | rewind_copy | clear
+        origin      String,                      -- the other session's native id (same store unless origin_store)
+        origin_store String,
+        evidence    LowCardinality(String),      -- explicit | inferred
+        at          String,
+        through     String
+    ),
+    usage_basis        LowCardinality(String),   -- per_response | per_record (legacy rows)
+    origin             LowCardinality(String) DEFAULT 'ship',
+    rev                UInt64,                   -- Σ files.ver of the session: rises on any change
+    is_deleted         UInt8 DEFAULT 0,          -- duplicates only
+    removed            UInt8 DEFAULT 0,          -- every source file gone; kept
+    user_id            String MATERIALIZED currentUser(),
+    ingested_at        DateTime64(3, 'UTC') DEFAULT now64(3)
+) ENGINE = ReplacingMergeTree(rev, is_deleted)
+ORDER BY (harness, host, harness_path, session_id, incarnation);
+
+CREATE TABLE IF NOT EXISTS {db}_archive.{m}_records (
+    harness     LowCardinality(String),
+    harness_path LowCardinality(String) DEFAULT '',
+    session_id  String,
+    incarnation String DEFAULT '',
+    file_key    String,                    -- path relative to the session
+    fgen        UInt32,
+    pos         UInt64,                    -- byte offset (or a first-seen ordinal for non-file sources)
+    chunk       UInt16,
+    sha         FixedString(64),           -- SHA-256 of the exact bytes, lowercase hex (JSONEachRow cannot carry raw bytes)
+    kind        LowCardinality(String),    -- record | fragment | side-file
+    enc         LowCardinality(String),    -- '' | 'b64'
+    raw         String CODEC(ZSTD(3)),
+    host        LowCardinality(String),
+    user_id     String MATERIALIZED currentUser(),
+    captured_at DateTime64(3, 'UTC') DEFAULT now64(3)
+) ENGINE = ReplacingMergeTree
+PRIMARY KEY (harness, host, harness_path, session_id, incarnation, file_key, fgen, pos)
+ORDER BY (harness, host, harness_path, session_id, incarnation, file_key, fgen, pos, chunk, sha);
+
+CREATE TABLE IF NOT EXISTS {db}_archive.{m}_files (
+    harness       LowCardinality(String),
+    harness_path  LowCardinality(String) DEFAULT '',
+    session_id    String,
+    incarnation   String DEFAULT '',
+    file_key      String,
+    agent_id      String DEFAULT '',
+    role          LowCardinality(String),  -- main | agent | side
+    agent_type    LowCardinality(String),
+    agent_desc    String,
+    fgen          UInt32,
+    upto          UInt64,
+    reparse_from  UInt64,                  -- start of the earliest open unit
+    derive_state  String CODEC(ZSTD(1)),   -- open units, their keys, contributions, fallback timestamps
+    adapter_ver   UInt32,
+    size          UInt64,
+    inode         UInt64,
+    anchor_sha    FixedString(64),         -- SHA-256, lowercase hex, as records.sha
+    prefix_sha    FixedString(64),
+    is_deleted    UInt8 DEFAULT 0,
+    contrib       String CODEC(ZSTD(1)),   -- this file's exact share of the session totals
+    first_ts      DateTime64(3, 'UTC'),
+    last_ts       DateTime64(3, 'UTC'),
+    ver           UInt64 MATERIALIZED (toUInt64(fgen) * 1099511627776) + upto,
+    host          LowCardinality(String),
+    user_id       String MATERIALIZED currentUser(),
+    committed_at  DateTime64(3, 'UTC') DEFAULT now64(3)
+) ENGINE = ReplacingMergeTree(ver)
+ORDER BY (harness, host, harness_path, session_id, incarnation, file_key);

package/memhouse/import/claude-ai.js

@@ -0,0 +1,420 @@
+'use strict';
+// claude.ai data export -> conversations, ready for a writer. Layout-free: this module knows
+// the export and nothing about tables. It computes every key a row is stored under (the session
+// id, each part's message_id and part_id, each call's call_id) once, here; a writer copies them
+// and never derives its own, so every layout stores one conversation under the same keys.
+//
+// Three inputs, one result:
+//   archive  a folder that files the export's conversations one per file, as the export holds
+//            them: projects/<slug>/chats/*.json, chats-unfiled/<year>/*.json, design-chats/*.json.
+//            The project is the folder's slug (the export itself has none).
+//   export   the folder a claude.ai export unpacks to: conversations.json and design_chats/*.json.
+//   zip      the export's .zip, read in place.
+//
+// Mapping (one part per stored block, in message order):
+//   text, thinking            one part each; an empty or whitespace-only block is skipped
+//   tool_use                  a 'tool_call' part, text `Name(args)`, plus one call. Its result is
+//                             the tool_result with its id, or — for blocks with no ids — the next
+//                             id-less tool_result after it in the same message (by order)
+//   tool_result               a 'tool_result' part, its content flattened to text
+//   attachment                with extracted text, an extra user 'text' part (part_id att:<n>)
+//   conversation summary      one 'summary' part at the time of the last message
+//   anything else             counted as skipped (block:<type>), never stored
+// A design chat's messages are one 'text' part each.
+
+const fs = require('fs');
+const path = require('path');
+const py = require('./pyjson');
+const { openZip, isZip, ZipError } = require('./zip');
+
+const HARNESS = 'claude-ai';
+// Where a claude.ai session lives: the service, not a machine. It is the session's host,
+// harness_path and host label alike.
+const STORE = 'claude.ai';
+const PROJECT_UNFILED = 'claude-ai-unfiled'; // an archive chat in no claude.ai project
+const PROJECT_DESIGN = 'claude-ai-design';   // a design chat
+const PROJECT_UNKNOWN = 'claude-ai';         // a chat read from the export, which records no project
+// The parser's version, stored as adapter_ver: raise it when a change alters any row.
+const PARSER_VERSION = 1;
+
+class ImportInputError extends Error {}
+
+const TS = /^(\d{4})-(\d{2})-(\d{2})[T ](\d{2}):(\d{2}):(\d{2})(?:\.(\d+))?(Z|[+-]\d{2}:?\d{2})?$/;
+
+/** An export timestamp (ISO 8601, any fraction, Z or an offset) as 'YYYY-MM-DD HH:MM:SS.mmm' UTC. */
+function chTs(iso) {
+  const m = TS.exec(py.pyStrip(String(iso === undefined || iso === null ? '' : iso)));
+  if (!m) throw new ImportInputError(`bad timestamp: ${JSON.stringify(iso)}`);
+  const [, y, mo, d, h, mi, s, frac, tz] = m;
+  const base = Date.UTC(Number(y), Number(mo) - 1, Number(d), Number(h), Number(mi), Number(s));
+  const check = new Date(base);
+  if (check.getUTCFullYear() !== Number(y) || check.getUTCMonth() !== Number(mo) - 1 || check.getUTCDate() !== Number(d)
+      || Number(h) > 23 || Number(mi) > 59 || Number(s) > 59) {
+    throw new ImportInputError(`bad timestamp: ${JSON.stringify(iso)}`);
+  }
+  const micro = Number(`${frac || ''}000000`.slice(0, 6));
+  let ms = base + Math.floor(micro / 1000);
+  if (tz && tz !== 'Z') {
+    const sign = tz[0] === '+' ? 1 : -1;
+    ms -= sign * (Number(tz.slice(1, 3)) * 60 + Number(tz.slice(-2))) * 60000;
+  }
+  return new Date(ms).toISOString().slice(0, 23).replace('T', ' ');
+}
+
+// Python's truthiness, for the `x or default` the mapping was first written with: an empty list
+// or dict is false there and true here.
+function truthy(v) {
+  if (!v) return false;
+  if (Array.isArray(v)) return v.length > 0;
+  if (typeof v === 'object') return Object.keys(v).length > 0;
+  return true;
+}
+const or = (v, dflt) => (truthy(v) ? v : dflt);
+const orEmpty = (v) => or(v, '');
+const hasText = (v) => typeof v === 'string' && py.pyStrip(v) !== '';
+
+/** A tool result's content as one text: text items as they are, known items described, the rest as JSON. */
+function flattenResult(content) {
+  const out = [];
+  // Always a list in the export. A bare string is taken as one text (the first importer would
+  // have split it into characters; no export has held one).
+  const items = Array.isArray(content) ? content : typeof content === 'string' && content ? [content] : [];
+  items.forEach((it, k) => {
+    if (!it || typeof it !== 'object' || Array.isArray(it)) { out.push(py.pyStr(it, py.numSource(items, k))); return; }
+    const t = it.type;
+    if (t === 'text') out.push(orEmpty(it.text));
+    else if (t === 'knowledge') {
+      const head = [it.title, it.url].filter(truthy).join(' ');
+      out.push((head ? `${head}\n` : '') + orEmpty(it.text));
+    } else if (t === 'local_resource') out.push(`[file: ${or(it.file_path, or(it.name, ''))}]`);
+    else if (t === 'image') out.push('[image]');
+    else out.push(py.dumps(it));
+  });
+  return out.filter((x) => x).join('\n\n');
+}
+
+function newSession(sessionId, name, mode, folder, project, created, updated) {
+  return { sessionId, name, mode, folder, project, created, updated, parts: [], calls: [], skipped: {} };
+}
+const skip = (s, why) => { s.skipped[why] = (s.skipped[why] || 0) + 1; };
+
+function blockType(t) {
+  if (t === null || t === undefined) return 'None';
+  return typeof t === 'string' ? t : py.pyStr(t);
+}
+
+/** One chat conversation (a conversations.json entry, or an archive chat file). */
+function fromConversation(conv, folder, project) {
+  if (!conv || typeof conv !== 'object' || !conv.uuid) throw new ImportInputError('a conversation has no uuid');
+  const s = newSession(String(conv.uuid), py.pyStrip(orEmpty(conv.name)) || '(untitled)', 'chat', folder, project,
+    chTs(conv.created_at), chTs(conv.updated_at));
+  let lastTs = null;
+  for (const m of or(conv.chat_messages, [])) {
+    if (!m || !m.uuid) throw new ImportInputError('a message has no uuid');
+    const mu = String(m.uuid);
+    const ts = chTs(m.created_at);
+    lastTs = ts;
+    const role = m.sender === 'human' ? 'user' : 'assistant';
+    const parent = orEmpty(m.parent_message_uuid);
+    const resp = role === 'assistant' ? mu : '';
+    const files = or(m.files, []).map((f) => f && f.file_name).filter(truthy);
+    let ord = 0;
+    let blocks = or(m.content, []);
+    if (!truthy(blocks) && hasText(orEmpty(m.text))) blocks = [{ type: 'text', text: m.text }];
+    const results = new Map();
+    for (const b of blocks) if (b.type === 'tool_result' && b.tool_use_id) results.set(b.tool_use_id, b);
+    // tool_use blocks without an id and tool_result blocks without a tool_use_id pair by order:
+    // the k-th id-less call takes the next id-less result after it in the same message.
+    const idless = [];
+    blocks.forEach((b, k) => { if (b.type === 'tool_result' && !b.tool_use_id) idless.push([k, b]); });
+    const resultFor = (k, b) => {
+      if (b.id) return results.get(b.id) || null;
+      while (idless.length && idless[0][0] < k) idless.shift();
+      return idless.length ? idless.shift()[1] : null;
+    };
+    // A tool call's result block, once paired: its tool_result part then carries the call's id.
+    const paired = new Map();
+    // `more`: what a layout with typed parts needs beside the text (a call's id, name and input).
+    const emit = (partId, r, kind, text, extra = null, more = null) => {
+      let ex = extra;
+      if (ord === 0 && files.length) ex = { ...(ex || {}), files };
+      s.parts.push({
+        messageId: mu, partId, partOrd: ord, parentId: parent, responseId: r === 'assistant' ? resp : '',
+        ts, role: r, kind, text, extra: ex, messageRole: role, ...(more || {}),
+      });
+      ord++;
+    };
+    blocks.forEach((b, k) => {
+      const t = b.type;
+      if (t === 'text') {
+        if (hasText(orEmpty(b.text))) emit(String(k), role, 'text', b.text); else skip(s, 'empty_text_block');
+      } else if (t === 'thinking') {
+        if (hasText(orEmpty(b.thinking))) emit(String(k), 'assistant', 'thinking', b.thinking); else skip(s, 'empty_thinking_block');
+      } else if (t === 'tool_use') {
+        const input = or(b.input, {});
+        const args = py.dumps(input, py.numSource(b, 'input'));
+        const callId = b.id ? String(b.id) : `${mu}:${k}`;
+        emit(String(k), 'assistant', 'tool_call', `${orEmpty(b.name)}(${args})`, null, { callId, toolName: orEmpty(b.name), input });
+        const r = resultFor(k, b);
+        if (r) paired.set(r, callId);
+        const rtext = r ? flattenResult(r.content) : '';
+        s.calls.push({
+          callId, messageId: mu, ts, toolName: orEmpty(b.name), args,
+          resultTs: r ? ts : null, isError: Boolean(r && r.is_error), resultLen: py.pyLen(rtext),
+        });
+      } else if (t === 'tool_result') {
+        emit(String(k), 'tool', 'tool_result', flattenResult(b.content),
+          { tool_use_id: orEmpty(b.tool_use_id), is_error: Boolean(b.is_error) },
+          { callId: paired.get(b) || orEmpty(b.tool_use_id), isError: Boolean(b.is_error) });
+      } else {
+        skip(s, `block:${blockType(t)}`);
+      }
+    });
+    or(m.attachments, []).forEach((a, j) => {
+      const body = orEmpty(a && a.extracted_content);
+      if (hasText(body)) {
+        const fname = orEmpty(a.file_name);
+        emit(`att:${j}`, 'user', 'text', `[attachment: ${fname}]\n${body}`, { attachment: fname });
+      } else skip(s, 'empty_attachment');
+    });
+  }
+  if (hasText(orEmpty(conv.summary)) && lastTs) {
+    s.parts.push({
+      messageId: `${s.sessionId}:summary`, partId: 'summary', partOrd: 0, parentId: '', responseId: '',
+      ts: lastTs, role: 'system', kind: 'summary', text: conv.summary, extra: null, messageRole: 'system',
+    });
+  }
+  return s;
+}
+
+/** One design chat (a design_chats/*.json file). */
+function fromDesignChat(d, folder, project) {
+  if (!d || typeof d !== 'object' || !d.uuid) throw new ImportInputError('a design chat has no uuid');
+  const s = newSession(String(d.uuid), py.pyStrip(orEmpty(d.title)) || '(untitled)', 'design', folder, project,
+    chTs(d.created_at), chTs(d.updated_at));
+  for (const m of or(d.messages, [])) {
+    const inner = m.content && typeof m.content === 'object' && !Array.isArray(m.content) ? m.content : {};
+    let text = or(inner.content, '');
+    const role = m.role === 'user' || m.role === 'assistant' ? m.role : 'assistant';
+    if (typeof text !== 'string') text = py.dumps(text, py.numSource(inner, 'content'));
+    if (hasText(text)) {
+      s.parts.push({
+        messageId: String(m.uuid), partId: '0', partOrd: 0, parentId: '', responseId: role === 'assistant' ? String(m.uuid) : '',
+        ts: chTs(m.created_at), role, kind: 'text', text, extra: null, messageRole: role,
+      });
+    } else skip(s, 'empty_design_message');
+  }
+  return s;
+}
+
+// ── inputs ─────────────────────────────────────────────────────────────────────────────
+
+const visible = (n) => !n.startsWith('.');
+const isDir = (p) => { try { return fs.statSync(p).isDirectory(); } catch { return false; } };
+const isFile = (p) => { try { return fs.statSync(p).isFile(); } catch { return false; } };
+const sortedNames = (dir) => (isDir(dir) ? fs.readdirSync(dir).filter(visible).sort() : []);
+// Only folders are walked into and only files are read: a stray file beside the project folders,
+// or a folder named like a .json file, is passed over.
+const sortedDirs = (dir) => sortedNames(dir).filter((n) => isDir(path.join(dir, n)));
+const jsonFiles = (dir) => sortedNames(dir).filter((n) => n.endsWith('.json')).map((n) => path.join(dir, n)).filter(isFile);
+
+function readJson(file, what) {
+  try { return py.parse(fs.readFileSync(file, 'utf-8')); } catch (e) {
+    throw new ImportInputError(`${what}: ${e.message}`);
+  }
+}
+
+const zipsIn = (dir) => sortedNames(dir).filter((n) => /\.zip$/i.test(n)).map((n) => path.join(dir, n)).filter(isFile);
+
+/**
+ * What a path is: 'zip' (a .zip file), 'export' (an unpacked export), 'archive', or 'parts' (a
+ * folder holding the export's part zips); throws when it is none.
+ */
+function inputKind(p) {
+  if (!fs.existsSync(p)) throw new ImportInputError(`no such file or folder: ${p}`);
+  if (!isDir(p)) {
+    if (isZip(p)) return 'zip';
+    throw new ImportInputError(`${p} is neither a folder nor a .zip file`);
+  }
+  if (fs.existsSync(path.join(p, 'conversations.json'))) return 'export';
+  if (['projects', 'chats-unfiled', 'design-chats'].some((d) => isDir(path.join(p, d)))) return 'archive';
+  if (zipsIn(p).length) return 'parts';
+  throw new ImportInputError(`${p} holds no claude.ai export: no conversations.json, no part zips (conversations-000.zip, …), no archive (projects/, chats-unfiled/, design-chats/)`);
+}
+
+// Files in the order a sorted glob of the full paths lists them.
+const byPath = (a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0);
+
+function fromArchive(root) {
+  const out = [];
+  const filed = [];
+  for (const slug of sortedDirs(path.join(root, 'projects'))) {
+    for (const f of jsonFiles(path.join(root, 'projects', slug, 'chats'))) filed.push([f, slug]);
+  }
+  for (const [f, slug] of filed.sort(byPath)) {
+    out.push(['project', fromConversation(readJson(f, f), path.join(root, 'projects', slug), slug)]);
+  }
+  const unfiled = path.join(root, 'chats-unfiled');
+  const loose = [];
+  for (const year of sortedDirs(unfiled)) for (const f of jsonFiles(path.join(unfiled, year))) loose.push([f]);
+  for (const [f] of loose.sort(byPath)) out.push(['unfiled', fromConversation(readJson(f, f), unfiled, PROJECT_UNFILED)]);
+  const design = path.join(root, 'design-chats');
+  for (const f of jsonFiles(design)) out.push(['design', fromDesignChat(readJson(f, f), design, PROJECT_DESIGN)]);
+  return out;
+}
+
+function parseExportJson(text, what) {
+  try { return py.parse(text); } catch (e) { throw new ImportInputError(`${what}: ${e.message}`); }
+}
+
+function conversationItems(text, what) {
+  const convs = parseExportJson(text, what);
+  if (!Array.isArray(convs)) throw new ImportInputError(`${what} is not a list`);
+  return convs.map((c) => ['chat', fromConversation(c, '', PROJECT_UNKNOWN)]);
+}
+
+function designItems(designTexts) {
+  return designTexts.map(([name, text]) => ['design', fromDesignChat(parseExportJson(text, name), '', PROJECT_DESIGN)]);
+}
+
+function fromExportDir(root) {
+  const designs = jsonFiles(path.join(root, 'design_chats')).map((f) => [path.basename(f), fs.readFileSync(f, 'utf-8')]);
+  return [...conversationItems(fs.readFileSync(path.join(root, 'conversations.json'), 'utf-8'), 'conversations.json'), ...designItems(designs)];
+}
+
+/** Run fn over an open zip. A damaged or unsupported zip is a bad input, like bad JSON: refused, not a failure. */
+function withZip(file, fn) {
+  let z = null;
+  try {
+    z = openZip(file);
+    return fn(z);
+  } catch (e) {
+    if (e instanceof ZipError) throw new ImportInputError(`${path.basename(file)}: ${e.message}`);
+    throw e;
+  } finally { if (z) z.close(); }
+}
+
+/** The zip's conversations.json: at its root, or one folder down in a re-zipped export. */
+const conversationsEntry = (z) => z.names.filter((n) => n === 'conversations.json' || n.endsWith('/conversations.json'))
+  .sort((a, b) => a.length - b.length)[0];
+
+const designEntries = (z, prefix) => z.names
+  .filter((n) => n.startsWith(`${prefix}design_chats/`) && n.endsWith('.json') && !n.slice(prefix.length + 13).includes('/')
+    && visible(path.posix.basename(n)))
+  .sort()
+  .map((n) => [path.posix.basename(n), z.read(n).toString('utf-8')]);
+
+/** The single-zip export: every file in one zip. */
+function fromWholeZip(file) {
+  return withZip(file, (z) => {
+    const conv = conversationsEntry(z);
+    if (!conv) throw new ImportInputError(`${path.basename(file)} holds no conversations.json — is it a claude.ai export?`);
+    const prefix = conv.slice(0, -'conversations.json'.length);
+    return [...conversationItems(z.read(conv).toString('utf-8'), 'conversations.json'), ...designItems(designEntries(z, prefix))];
+  });
+}
+
+// The export as it arrives now: one zip per kind and index, <kind>-<NNN>.zip — conversations-000.zip,
+// design_chats-000.zip, memories-000.zip and so on. A browser's re-download suffix (" (1)") keeps
+// the kind and index, so a second copy of a part is recognised as one.
+const PART = /^(.+?)-(\d{3,})(?: \(\d+\))?\.zip$/i;
+const PART_KINDS = ['conversations', 'design_chats'];
+
+/**
+ * Zips -> items. Each is a part (by name: conversations or design_chats, read; any other kind,
+ * ignored and named), or a whole single-zip export (it holds conversations.json). Parts are read
+ * in index order: every conversations part, then every design_chats part.
+ */
+function fromZips(files) {
+  const parts = { conversations: [], design_chats: [] };
+  const whole = [];
+  const ignored = [];
+  const seen = new Map();
+  for (const f of files) {
+    if (!isZip(f)) throw new ImportInputError(`${path.basename(f)} is not a zip file`);
+    const m = PART.exec(path.basename(f));
+    const kind = m ? m[1].toLowerCase() : null;
+    if (PART_KINDS.includes(kind)) {
+      const key = `${kind}-${Number(m[2])}`;
+      if (seen.has(key)) {
+        throw new ImportInputError(`${path.basename(seen.get(key))} and ${path.basename(f)} are the same part (${kind} ${m[2]}): keep one`);
+      }
+      seen.set(key, f);
+      parts[kind].push({ file: f, index: Number(m[2]) });
+    } else if (withZip(f, (z) => Boolean(conversationsEntry(z)))) whole.push(f);
+    else ignored.push(path.basename(f));
+  }
+  const nParts = parts.conversations.length + parts.design_chats.length;
+  if (whole.length > 1) throw new ImportInputError(`${whole.map((f) => path.basename(f)).join(' and ')} are each a whole export: import one at a time`);
+  if (whole.length && nParts) throw new ImportInputError(`${path.basename(whole[0])} is a whole export; give it alone, or give the part zips without it`);
+  if (whole.length) return { kind: 'zip', items: fromWholeZip(whole[0]), ignored, read: [path.basename(whole[0])] };
+  if (!parts.conversations.length) {
+    throw new ImportInputError(`no conversations part among the inputs: pass conversations-000.zip (and any -001, -002, …) with the other parts${ignored.length ? `; got ${ignored.join(', ')}` : ''}`);
+  }
+  const byIndex = (a, b) => a.index - b.index;
+  const items = [];
+  const read = [];
+  for (const p of parts.conversations.sort(byIndex)) {
+    const name = path.basename(p.file);
+    withZip(p.file, (z) => {
+      const e = conversationsEntry(z);
+      if (!e) throw new ImportInputError(`${name} holds no conversations.json`);
+      items.push(...conversationItems(z.read(e).toString('utf-8'), `${name}: conversations.json`));
+    });
+    read.push(name);
+  }
+  for (const p of parts.design_chats.sort(byIndex)) {
+    withZip(p.file, (z) => {
+      const e = z.names.find((n) => /(^|\/)design_chats\/[^/]+\.json$/.test(n));
+      items.push(...designItems(designEntries(z, e ? e.slice(0, e.indexOf('design_chats/')) : '')));
+    });
+    read.push(path.basename(p.file));
+  }
+  return { kind: 'parts', items, ignored, read };
+}
+
+/**
+ * Read an input: one path, or several zips. Returns { kind, sessions, duplicates, empty, skipped }:
+ *   kind        archive, export (an unpacked export), zip (a whole single-zip export), parts
+ *   sessions    one per conversation that has something to store, first occurrence kept
+ *   duplicates  conversations met again under the same id (an archive can file one twice; parts
+ *               can repeat one)
+ *   empty       conversations with nothing to store
+ *   skipped     blocks not stored, by reason
+ *   categories  sessions per category (project, unfiled, chat, design)
+ *   read        the zips read; ignored  the zips passed over (other parts of the export)
+ */
+function readInput(inputs) {
+  const list = (Array.isArray(inputs) ? inputs : [inputs]).map((p) => path.resolve(p));
+  if (!list.length) throw new ImportInputError('no input given');
+  let r;
+  if (list.length === 1) {
+    const kind = inputKind(list[0]);
+    if (kind === 'export') r = { kind, items: fromExportDir(list[0]), ignored: [], read: [] };
+    else if (kind === 'archive') r = { kind, items: fromArchive(list[0]), ignored: [], read: [] };
+    else r = fromZips(kind === 'parts' ? zipsIn(list[0]) : list);
+  } else {
+    for (const p of list) {
+      if (!fs.existsSync(p)) throw new ImportInputError(`no such file or folder: ${p}`);
+      if (isDir(p)) throw new ImportInputError(`${p} is a folder: several inputs must all be .zip files, and a folder goes alone`);
+    }
+    r = fromZips(list);
+  }
+  const seen = new Set();
+  const out = { kind: r.kind, sessions: [], duplicates: 0, empty: 0, skipped: {}, categories: {}, read: r.read, ignored: r.ignored };
+  for (const [category, s] of r.items) {
+    if (seen.has(s.sessionId)) { out.duplicates++; continue; }
+    seen.add(s.sessionId);
+    for (const [k, v] of Object.entries(s.skipped)) out.skipped[k] = (out.skipped[k] || 0) + v;
+    if (!s.parts.length) { out.empty++; continue; }
+    s.category = category;
+    out.categories[category] = (out.categories[category] || 0) + 1;
+    out.sessions.push(s);
+  }
+  return out;
+}
+
+module.exports = {
+  HARNESS, STORE, PROJECT_UNFILED, PROJECT_DESIGN, PROJECT_UNKNOWN, PARSER_VERSION, ImportInputError,
+  chTs, flattenResult, fromConversation, fromDesignChat, inputKind, readInput,
+};