tinywebui 0.1.0

package/src/store/automations.js

@@ -0,0 +1,119 @@
+import { scope, ownerOf } from './scope.js';
+import { randomBytes } from 'node:crypto';
+
+// Scheduled automations and their runs.
+// One area of the Store; see index.js.
+
+function automationView(row) {
+  return {
+    id: row.id, userId: row.user_id, chatId: row.chat_id, chatTitle: row.chat_title,
+    name: row.name, prompt: row.prompt, cron: row.cron, timezone: row.timezone,
+    enabled: Boolean(row.enabled), nextRunAt: row.next_run_at, lastRunAt: row.last_run_at,
+    lastStatus: row.last_status, lastResult: row.last_result, source: row.source,
+    createdAt: row.created_at, updatedAt: row.updated_at
+  };
+}
+
+export class AutomationStore {
+  constructor(db, deps = {}) {
+    this.db = db;
+    Object.assign(this, deps);
+  }
+
+  list(userId) {
+    const s = scope(userId, 'a.user_id');
+    return this.db.prepare(`SELECT a.*, c.title AS chat_title FROM automations a JOIN chats c ON c.id=a.chat_id
+      WHERE ${s.sql} ORDER BY a.updated_at DESC`).all(...s.params).map(automationView);
+  }
+
+  listAll() {
+    return this.db.prepare(`SELECT a.*, c.title AS chat_title FROM automations a JOIN chats c ON c.id=a.chat_id
+      ORDER BY a.updated_at DESC`).all().map(automationView);
+  }
+
+  get(id, userId) {
+    const s = scope(userId, 'a.user_id');
+    const row = this.db.prepare(`SELECT a.*, c.title AS chat_title FROM automations a JOIN chats c ON c.id=a.chat_id
+      WHERE a.id=? AND ${s.sql}`).get(id, ...s.params);
+    return row ? automationView(row) : null;
+  }
+
+  create(data, userId) {
+    scope(userId);
+    const id = randomBytes(12).toString('hex');
+    const now = Date.now();
+    this.db.prepare(`INSERT INTO automations
+      (id,user_id,chat_id,name,prompt,cron,timezone,enabled,next_run_at,source,created_at,updated_at)
+      VALUES (?,?,?,?,?,?,?,?,?,?,?,?)`).run(id,ownerOf(userId),data.chatId,data.name,data.prompt,data.cron,data.timezone,
+      data.enabled === false ? 0 : 1,data.nextRunAt,data.source || 'user',now,now);
+    return this.get(id,userId);
+  }
+
+  update(id, patch, userId) {
+    const current = this.get(id,userId);
+    if (!current) return null;
+    const fields = { chatId:'chat_id', name:'name', prompt:'prompt', cron:'cron', timezone:'timezone', enabled:'enabled', nextRunAt:'next_run_at', lastRunAt:'last_run_at', lastStatus:'last_status', lastResult:'last_result' };
+    const sets = ['updated_at=?'];
+    const values = [Date.now()];
+    for (const [key,col] of Object.entries(fields)) if (patch[key] !== undefined) {
+      sets.push(`${col}=?`); values.push(key === 'enabled' ? (patch[key] ? 1 : 0) : patch[key]);
+    }
+    values.push(id);
+    this.db.prepare(`UPDATE automations SET ${sets.join(',')} WHERE id=?`).run(...values);
+    return this.get(id,userId);
+  }
+
+  delete(id, userId) {
+    const s = scope(userId);
+    return this.db.prepare(`DELETE FROM automations WHERE id=? AND ${s.sql}`).run(id, ...s.params).changes > 0;
+  }
+
+  /** Drops every automation that posts into a chat (the chat is going). */
+  deleteForChat(chatId) {
+    this.db.prepare('DELETE FROM automations WHERE chat_id = ?').run(chatId);
+  }
+
+  /** When the next enabled automation is due, or null when none is. */
+  nextDue() {
+    return this.db.prepare('SELECT MIN(next_run_at) AS due FROM automations WHERE enabled=1').get()?.due ?? null;
+  }
+
+  due(now = Date.now()) {
+    return this.db.prepare(`SELECT a.*, c.title AS chat_title FROM automations a JOIN chats c ON c.id=a.chat_id
+      WHERE a.enabled=1 AND a.next_run_at<=? ORDER BY a.next_run_at`).all(now).map(automationView);
+  }
+
+  addRun(automationId, scheduledAt, status = 'queued', triggerType = 'schedule') {
+    const id = randomBytes(12).toString('hex');
+    this.db.prepare(`INSERT INTO automation_runs(id,automation_id,scheduled_at,status,trigger_type) VALUES(?,?,?,?,?)`)
+      .run(id,automationId,scheduledAt,status,triggerType);
+    return id;
+  }
+
+  updateRun(id, patch) {
+    const fields = { status:'status', startedAt:'started_at', finishedAt:'finished_at', result:'result', error:'error' };
+    const sets = []; const values = [];
+    for (const [key,col] of Object.entries(fields)) if (patch[key] !== undefined) { sets.push(`${col}=?`); values.push(patch[key]); }
+    if (sets.length) this.db.prepare(`UPDATE automation_runs SET ${sets.join(',')} WHERE id=?`).run(...values,id);
+    const row = this.db.prepare('SELECT * FROM automation_runs WHERE id=?').get(id);
+    const owner = this.db.prepare('SELECT user_id FROM automations WHERE id=?').get(row?.automation_id)?.user_id ?? null;
+    if (row) this.update(row.automation_id, {
+      lastRunAt: row.started_at || row.scheduled_at, lastStatus: row.status,
+      ...(row.result !== null ? { lastResult: row.result.slice(0, 4000) } : {})
+    }, owner);
+  }
+
+  listRuns(automationId, userId, limit = 10) {
+    const owned = this.get(automationId,userId);
+    if (!owned) return null;
+    return this.db.prepare('SELECT id,scheduled_at,started_at,finished_at,status,trigger_type,result,error FROM automation_runs WHERE automation_id=? ORDER BY scheduled_at DESC LIMIT ?')
+      .all(automationId,Math.min(50,Math.max(1,limit)));
+  }
+
+  recoverRuns(now = Date.now()) {
+    const rows = this.db.prepare("SELECT id FROM automation_runs WHERE status IN ('queued','running')").all();
+    for (const row of rows) this.updateRun(row.id, {
+      status: 'failed', finishedAt: now, error: 'Server restarted during this run.'
+    });
+  }
+}

package/src/store/chats.js

@@ -0,0 +1,254 @@
+import { ALL_USERS, scope, ownerOf } from './scope.js';
+import { randomUUID } from 'node:crypto';
+import { CORPUS } from './embeddings.js';
+
+// Chats and what hangs off one: tasks, folders, queued input, ask_user questions, rewind and delete.
+// One area of the Store; see index.js.
+
+export class ChatStore {
+  constructor(db, deps = {}) {
+    this.db = db;
+    Object.assign(this, deps);
+  }
+
+  listTasks(chatId) {
+    return this.db.prepare('SELECT id, title, status, created_at, updated_at FROM tasks WHERE chat_id = ? ORDER BY created_at, rowid').all(chatId);
+  }
+
+  /**
+   * Task writes are stamped with the seq of the latest saved message: the
+   * assistant message that made the call, which is saved before its tools run.
+   * That seq lies inside the turn, after its question, so rewinding to the
+   * question (or retrying its answer) undoes the write -- and it holds even if
+   * the turn dies before saving anything more. See undoTasksFrom.
+   */
+  /**
+   * The checklist as the user sees it: a task finished before the latest
+   * question is done with and drops out, the rest stay. A finish is stamped
+   * inside the turn that made it, so it compares against the question's seq
+   * the same way a rewind does; a rewind that reopens a task shows it again.
+   */
+  visibleTasks(chatId) {
+    return this.db.prepare(`
+      SELECT id, title, status, created_at, updated_at FROM tasks t
+      WHERE chat_id = ? AND (status != 'completed'
+        OR COALESCE((SELECT MAX(seq) FROM task_changes c WHERE c.task_id = t.id), t.created_seq)
+           >= COALESCE((SELECT MAX(seq) FROM messages m WHERE m.chat_id = t.chat_id AND m.role = 'user'), -1))
+      ORDER BY created_at, rowid`).all(chatId);
+  }
+
+  addTask(chatId, title) {
+    const id = randomUUID();
+    const now = Date.now();
+    this.db.prepare('INSERT INTO tasks (id, chat_id, title, created_at, updated_at, created_seq) VALUES (?, ?, ?, ?, ?, ?)')
+      .run(id, chatId, title, now, now, this.#stamp(chatId));
+    return this.listTasks(chatId).find((task) => task.id === id);
+  }
+
+  updateTask(chatId, id, status) {
+    const prev = this.db.prepare('SELECT status FROM tasks WHERE chat_id = ? AND id = ?').get(chatId, id);
+    if (!prev) return null;
+    this.db.prepare('INSERT INTO task_changes (chat_id, task_id, seq, prev_status) VALUES (?, ?, ?, ?)')
+      .run(chatId, id, this.#stamp(chatId), prev.status);
+    this.db.prepare('UPDATE tasks SET status = ?, updated_at = ? WHERE chat_id = ? AND id = ?')
+      .run(status, Date.now(), chatId, id);
+    return this.listTasks(chatId).find((task) => task.id === id);
+  }
+
+  #stamp(chatId) {
+    return this.messages.nextSeq(chatId) - 1;
+  }
+
+  /** Undoes the checklist writes made from `seq` on: changes newest first, then the tasks added. */
+  undoTasksFrom(chatId, seq) {
+    const changes = this.db.prepare(
+      'SELECT rowid, task_id, prev_status FROM task_changes WHERE chat_id = ? AND seq >= ? ORDER BY rowid DESC'
+    ).all(chatId, seq);
+    const restore = this.db.prepare('UPDATE tasks SET status = ?, updated_at = ? WHERE chat_id = ? AND id = ?');
+    for (const c of changes) restore.run(c.prev_status, Date.now(), chatId, c.task_id);
+    this.db.prepare('DELETE FROM task_changes WHERE chat_id = ? AND seq >= ?').run(chatId, seq);
+    this.db.prepare('DELETE FROM tasks WHERE chat_id = ? AND created_seq >= ?').run(chatId, seq);
+  }
+
+  create({ id, title = 'New chat', createdAt = Date.now() } = {}, userId = ALL_USERS) {
+    const chatId = id || randomUUID();
+    this.db.prepare(
+      'INSERT INTO chats (id, title, created_at, updated_at, user_id) VALUES (?, ?, ?, ?, ?)'
+    ).run(chatId, title, createdAt, createdAt, ownerOf(userId));
+    return this.byId(chatId);
+  }
+
+  /** Scoped lookup for anything reached from a request. See scope(). */
+  get(id, userId) {
+    const s = scope(userId);
+    return this.db.prepare(`SELECT * FROM chats WHERE id = ? AND ${s.sql}`).get(id, ...s.params) || null;
+  }
+
+  /** Unscoped lookup for internal plumbing that already holds a chat id it
+   * got from a scoped path (the chat loop, compaction, automation runs). */
+  byId(id) {
+    return this.db.prepare('SELECT * FROM chats WHERE id = ?').get(id) || null;
+  }
+
+  list(limit, userId) {
+    const s = scope(userId);
+    return this.db.prepare(
+      `SELECT id, title, updated_at, epoch, boundary_seq, folder FROM chats WHERE ${s.sql} ORDER BY updated_at DESC LIMIT ?`
+    ).all(...s.params, limit);
+  }
+
+  organize(id, { folder = null, tags } = {}, userId) {
+    if (!this.get(id, userId)) return null;
+    const clean = (items, max) => [...new Set((Array.isArray(items) ? items : [])
+      .map((v) => String(v).trim().slice(0, max)).filter(Boolean))].slice(0, 10);
+    const cleanFolder = folder == null ? null : String(folder).trim().slice(0, 40) || null;
+    const tagsJson = tags === undefined ? null : JSON.stringify(clean(tags, 32));
+    const result = this.db.prepare('UPDATE chats SET folder = ?, tags_json = COALESCE(?, tags_json) WHERE id = ?')
+      .run(cleanFolder, tagsJson, id);
+    return result.changes ? this.byId(id) : null;
+  }
+
+  /** Names only, sorted -- the create-then-move-chats-into-it workflow needs
+   * to list folders even when nothing has been organized into them yet. */
+  listFolders(userId) {
+    const s = scope(userId);
+    return this.db.prepare(`SELECT name FROM folders WHERE ${s.sql}`).all(...s.params).map((r) => r.name).sort((a, b) => a.localeCompare(b));
+  }
+
+  createFolder(name, userId) {
+    const clean = String(name || '').trim().slice(0, 40);
+    if (!clean) return null;
+    const owner = ownerOf(userId);
+    const s = scope(owner);
+    const exists = this.db.prepare(`SELECT 1 FROM folders WHERE name = ? AND ${s.sql}`).get(clean, ...s.params);
+    if (!exists) {
+      this.db.prepare('INSERT INTO folders (name, user_id, created_at) VALUES (?, ?, ?)')
+        .run(clean, owner, Date.now());
+    }
+    return clean;
+  }
+
+  /**
+   * Rewinds a conversation, dropping everything from `seq` onward.
+   *
+   * This is the one place that breaks the append-only rule on purpose. Editing
+   * a question means the answers that followed it were answers to a question
+   * that no longer exists, so they go with it -- and the prompt cache from that
+   * point on goes too, which is correct rather than unfortunate: the model must
+   * genuinely reconsider everything after the edit.
+   *
+   * Artifacts are left behind. They are addressed by id from a message that no
+   * longer exists, so nothing can reach them, and deleting them would be the
+   * one way to lose tool output that the transcript promises to keep.
+   */
+  /**
+   * Queues input for a running turn. Returns false when that id is already
+   * queued (a retry), true when it was added.
+   */
+  addQueued(chatId, { id, kind, content }) {
+    return this.db.prepare(
+      'INSERT OR IGNORE INTO queued_messages (id, chat_id, kind, content, created_at) VALUES (?, ?, ?, ?, ?)'
+    ).run(String(id), chatId, kind, String(content), Date.now()).changes > 0;
+  }
+
+  /** A chat's queue, oldest first. */
+  listQueued(chatId) {
+    return this.db.prepare(
+      'SELECT id, kind, content, created_at FROM queued_messages WHERE chat_id = ? ORDER BY pos'
+    ).all(chatId);
+  }
+
+  /**
+   * Removes and returns queued items for delivery, oldest first: every item
+   * of `kind`, or with `first` only the oldest item of any kind.
+   */
+  takeQueued(chatId, { kind = null, first = false } = {}) {
+    const rows = this.db.prepare(
+      `SELECT pos, id, kind, content FROM queued_messages WHERE chat_id = ?${kind ? ' AND kind = ?' : ''} ORDER BY pos${first ? ' LIMIT 1' : ''}`
+    ).all(...(kind ? [chatId, kind] : [chatId]));
+    const drop = this.db.prepare('DELETE FROM queued_messages WHERE pos = ?');
+    for (const r of rows) drop.run(r.pos);
+    return rows.map(({ id, kind: k, content }) => ({ id, kind: k, content }));
+  }
+
+  /** Withdraws one queued item before it is delivered. */
+  deleteQueued(chatId, id) {
+    return this.db.prepare('DELETE FROM queued_messages WHERE chat_id = ? AND id = ?').run(chatId, String(id)).changes > 0;
+  }
+
+  /** Records a question as pending. `deadline` is epoch ms, or null for no timeout. */
+  addQuestion(chatId, { id, question, choices = [], allowFreeText = true, deadline = null }) {
+    this.db.prepare(
+      'INSERT INTO questions (id, chat_id, question, choices_json, allow_free_text, created_at, deadline) VALUES (?, ?, ?, ?, ?, ?, ?)'
+    ).run(String(id), chatId, question, JSON.stringify(choices), allowFreeText ? 1 : 0, Date.now(), deadline);
+  }
+
+  getQuestion(id) {
+    const row = this.db.prepare('SELECT * FROM questions WHERE id = ?').get(String(id));
+    return row && {
+      id: row.id, chatId: row.chat_id, question: row.question, choices: JSON.parse(row.choices_json),
+      allowFreeText: Boolean(row.allow_free_text), status: row.status, answer: row.answer,
+      createdAt: row.created_at, deadline: row.deadline, settledAt: row.settled_at
+    };
+  }
+
+  /**
+   * Settles a pending question. True for the one caller that settled it;
+   * false when it was already settled (or never existed).
+   */
+  settleQuestion(id, status, answer = null) {
+    return this.db.prepare(
+      "UPDATE questions SET status = ?, answer = ?, settled_at = ? WHERE id = ? AND status = 'pending'"
+    ).run(status, answer, Date.now(), String(id)).changes > 0;
+  }
+
+  /** Expires every pending question: at startup no run is left to answer one. */
+  expireQuestions() {
+    return this.db.prepare(
+      "UPDATE questions SET status = 'expired', settled_at = ? WHERE status = 'pending'"
+    ).run(Date.now()).changes;
+  }
+
+  truncateFrom(chatId, seq) {
+    // One transaction: a crash midway must not leave messages cut but their
+    // task writes (or cache markers) still standing.
+    this.db.exec('BEGIN');
+    try {
+      const removed = this.messages.deleteFrom(chatId, seq);
+      this.undoTasksFrom(chatId, seq);
+      // A frozen compaction boundary inside the cut no longer describes anything,
+      // so the pinned cache breakpoint it drives has to go with it.
+      const chat = this.byId(chatId);
+      if (chat && chat.boundary_seq >= seq) this.touch(chatId, { boundary_seq: -1 });
+      // Same for the hard window: a cut at or past the rewind point would hide
+      // the very question being asked again. A checkpoint summarises what that
+      // window cut off, so it goes too.
+      if (chat && chat.window_seq >= seq) this.touch(chatId, { window_seq: -1, checkpoint_json: null });
+      this.db.exec('COMMIT');
+      return removed;
+    } catch (err) { this.db.exec('ROLLBACK'); throw err; }
+  }
+
+  delete(id, userId) {
+    if (!this.get(id, userId)) return false;
+    // Each area drops its own part of the chat; tasks go by foreign key.
+    this.automations.deleteForChat(id);
+    this.messages.deleteForChat(id);
+    this.documents.deleteForChat(id);
+    this.embeddings.deleteOwner(CORPUS.CHATS, id);
+    this.db.prepare('DELETE FROM queued_messages WHERE chat_id = ?').run(id);
+    this.db.prepare('DELETE FROM questions WHERE chat_id = ?').run(id);
+    this.db.prepare('DELETE FROM chats WHERE id = ?').run(id);
+    return true;
+  }
+
+  touch(id, patch = {}) {
+    const sets = ['updated_at = ?'];
+    const vals = [Date.now()];
+    for (const key of ['title', 'epoch', 'boundary_seq', 'window_seq', 'checkpoint_json']) {
+      if (patch[key] !== undefined) { sets.push(`${key} = ?`); vals.push(patch[key]); }
+    }
+    vals.push(id);
+    this.db.prepare(`UPDATE chats SET ${sets.join(', ')} WHERE id = ?`).run(...vals);
+  }
+}

package/src/store/documents.js

@@ -0,0 +1,256 @@
+import { scope, ftsQuery } from './scope.js';
+import { createHash, randomBytes } from 'node:crypto';
+import { CORPUS } from './embeddings.js';
+
+// Attached documents, split into passages for read_document (BM25 and dense retrieval).
+// One area of the Store; see index.js.
+
+/** Default passage split: characters per passage, and how much neighbours overlap. */
+export const PASSAGE_SIZE = 1800;
+export const PASSAGE_OVERLAP = 200;
+
+/**
+ * Splits text into overlapping passages -- the unit read_document returns.
+ * Character-based on purpose: passages are for reading and BM25, and the
+ * embedding side cuts its own model-sized chunks out of them. Breaks are
+ * nudged onto a paragraph or line boundary when one is nearby, so a
+ * passage doesn't open or close mid-sentence more than it has to.
+ */
+export function splitPassages(text, size = PASSAGE_SIZE, overlap = PASSAGE_OVERLAP) {
+  const passages = [];
+  let start = 0;
+  while (start < text.length) {
+    let end = Math.min(start + size, text.length);
+    if (end < text.length) {
+      const para = text.lastIndexOf('\n\n', end);
+      const line = text.lastIndexOf('\n', end);
+      const boundary = para > start + size * 0.5 ? para : (line > start + size * 0.5 ? line : -1);
+      if (boundary !== -1) end = boundary;
+    }
+    passages.push({ start, text: text.slice(start, end) });
+    if (end >= text.length) break;
+    start = Math.max(end - overlap, start + 1);
+  }
+  return passages;
+}
+
+const md5Of = (bytes) => createHash('md5').update(bytes).digest('hex');
+
+function insertPassages(db, docId, chatId, content, size, overlap) {
+  const passages = splitPassages(content, size, overlap);
+  const insertPassage = db.prepare('INSERT INTO document_passages (body) VALUES (?)');
+  const insertMap = db.prepare(`
+    INSERT INTO document_passage_map (passage_rowid, doc_id, chat_id, passage_idx, char_start)
+    VALUES (?, ?, ?, ?, ?)
+  `);
+  passages.forEach((passage, idx) => {
+    const { lastInsertRowid } = insertPassage.run(passage.text);
+    insertMap.run(lastInsertRowid, docId, chatId, idx, passage.start);
+  });
+  return passages.length;
+}
+
+export class DocumentStore {
+  constructor(db, deps = {}) {
+    this.db = db;
+    Object.assign(this, deps);
+  }
+
+  /**
+   * `original`: the uploaded bytes, kept (once per distinct file) so the file
+   * itself can be opened later. `md5` names them when the caller already has
+   * the fingerprint, e.g. copying a document into another chat.
+   */
+  add(chatId, { filename, mime, content, original = null, md5 = null }, { passageSize = PASSAGE_SIZE, passageOverlap = PASSAGE_OVERLAP } = {}) {
+    const id = randomBytes(12).toString('hex');
+    const createdAt = Date.now();
+    const hash = original ? md5Of(original) : md5;
+    this.db.exec('BEGIN');
+    try {
+      if (original) this.db.prepare('INSERT OR IGNORE INTO document_blobs (md5, data) VALUES (?, ?)').run(hash, original);
+      this.db.prepare(`
+        INSERT INTO documents (id, chat_id, filename, mime, char_len, created_at, content, passage_size, passage_overlap, md5)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `).run(id, chatId, filename, mime ?? null, content.length, createdAt, content, passageSize, passageOverlap, hash);
+      const passages = insertPassages(this.db, id, chatId, content, passageSize, passageOverlap);
+      this.db.exec('COMMIT');
+      return { id, filename, mime: mime ?? null, char_len: content.length, created_at: createdAt, passages };
+    } catch (err) { this.db.exec('ROLLBACK'); throw err; }
+  }
+
+  /** The chat's document with these bytes, if it already has one -- a file is attached to a chat once. */
+  findInChat(chatId, original) {
+    return this.#inChat(chatId, md5Of(original));
+  }
+
+  #inChat(chatId, md5) {
+    return this.db.prepare('SELECT id, filename, mime, char_len, created_at FROM documents WHERE chat_id = ? AND md5 = ?')
+      .get(chatId, md5) || null;
+  }
+
+  /** The uploaded bytes as a Buffer, or null (no such document, not yours, or stored before originals were kept). */
+  original(id, userId) {
+    const doc = this.get(id, userId);
+    if (!doc?.md5) return null;
+    const row = this.db.prepare('SELECT data FROM document_blobs WHERE md5 = ?').get(doc.md5);
+    return row ? Buffer.from(row.data) : null;
+  }
+
+  /**
+   * What the user has attached before, across all their chats, newest first --
+   * for picking a file again without uploading it. One entry per distinct file:
+   * the same bytes in ten chats is one line, and it names the latest chat.
+   */
+  library(userId, limit = 200) {
+    const s = scope(userId, 'c.user_id');
+    const inner = scope(userId, 'c2.user_id'); // the "latest" must be the user's own copy, not someone else's
+    return this.db.prepare(`
+      SELECT d.id, d.filename, d.mime, d.char_len, d.created_at, c.title AS chatTitle
+      FROM documents d JOIN chats c ON c.id = d.chat_id
+      WHERE ${s.sql}
+        AND d.id = (
+          SELECT d2.id FROM documents d2 JOIN chats c2 ON c2.id = d2.chat_id
+          WHERE ${inner.sql} AND COALESCE(d2.md5, d2.id) = COALESCE(d.md5, d.id)
+          ORDER BY d2.created_at DESC, d2.rowid DESC LIMIT 1
+        )
+      ORDER BY d.created_at DESC
+      LIMIT ?
+    `).all(...s.params, ...inner.params, limit);
+  }
+
+  /**
+   * Puts a copy of one of the user's documents into another chat of theirs.
+   * Documents are chat-scoped (the chat's deletion takes them, its passages
+   * carry its id), so this is a new row: same text, same file blob, its own
+   * passages. Null when the source is not theirs; the chat's existing copy
+   * when it already has this file.
+   */
+  copyToChat(sourceId, chatId, userId, passageSettings) {
+    const src = this.get(sourceId, userId);
+    if (!src) return null;
+    if (src.md5) {
+      const have = this.#inChat(chatId, src.md5);
+      if (have) return { ...have, existing: true };
+    }
+    return this.add(chatId, { filename: src.filename, mime: src.mime, content: src.content, md5: src.md5 }, passageSettings);
+  }
+
+  /** Documents split with other passage settings than these (NULL = the original 1800/200). */
+  withOtherPassages(size, overlap) {
+    return this.db.prepare(`
+      SELECT id FROM documents
+      WHERE COALESCE(passage_size, ${PASSAGE_SIZE}) != ? OR COALESCE(passage_overlap, ${PASSAGE_OVERLAP}) != ?
+    `).all(size, overlap).map((r) => r.id);
+  }
+
+  /** Re-splits a stored document with new passage settings; its old vectors go with the old passages. */
+  repassage(docId, size, overlap) {
+    const doc = this.db.prepare('SELECT id, chat_id, content FROM documents WHERE id = ?').get(docId);
+    if (!doc) return 0;
+    this.db.exec('BEGIN');
+    try {
+      this.#deletePassages(docId);
+      const n = insertPassages(this.db, doc.id, doc.chat_id, doc.content, size, overlap);
+      this.db.prepare('UPDATE documents SET passage_size = ?, passage_overlap = ? WHERE id = ?').run(size, overlap, docId);
+      this.db.exec('COMMIT');
+      return n;
+    } catch (err) { this.db.exec('ROLLBACK'); throw err; }
+  }
+
+  /** Scoped through the owning chat: a document is its chat's user's. */
+  get(id, userId) {
+    const s = scope(userId, 'c.user_id');
+    return this.db.prepare(
+      `SELECT d.* FROM documents d JOIN chats c ON c.id = d.chat_id WHERE d.id = ? AND ${s.sql}`
+    ).get(id, ...s.params) || null;
+  }
+
+  list(chatId) {
+    return this.db.prepare(`
+      SELECT id, filename, mime, char_len, created_at
+      FROM documents WHERE chat_id = ? ORDER BY created_at ASC
+    `).all(chatId);
+  }
+
+  /** Drops one document, its passages and their chunk vectors. The rest of the chat is untouched. */
+  delete(id, userId) {
+    if (!this.get(id, userId)) return false;
+    this.#deletePassages(id);
+    const gone = this.db.prepare('DELETE FROM documents WHERE id = ?').run(id).changes > 0;
+    this.#dropOrphanBlobs();
+    return gone;
+  }
+
+  /** Drops every document of a chat, with its passages and vectors (the chat is going). */
+  deleteForChat(chatId) {
+    for (const { id } of this.db.prepare('SELECT id FROM documents WHERE chat_id = ?').all(chatId)) this.#deletePassages(id);
+    this.db.prepare('DELETE FROM documents WHERE chat_id = ?').run(chatId);
+    this.#dropOrphanBlobs();
+  }
+
+  /** A stored file goes when the last document naming it does. */
+  #dropOrphanBlobs() {
+    this.db.exec('DELETE FROM document_blobs WHERE md5 NOT IN (SELECT md5 FROM documents WHERE md5 IS NOT NULL)');
+  }
+
+  // FTS5 has no foreign keys of its own, so passage rows are dropped by rowid
+  // before the map that names them.
+  #deletePassages(docId) {
+    this.db.prepare(`
+      DELETE FROM document_passages WHERE rowid IN (
+        SELECT passage_rowid FROM document_passage_map WHERE doc_id = ?
+      )
+    `).run(docId);
+    this.embeddings.deleteOwner(CORPUS.DOCUMENTS, docId);
+    this.db.prepare('DELETE FROM document_passage_map WHERE doc_id = ?').run(docId);
+  }
+
+  /** Ranked passage search within one document, via FTS5 bm25() (lexical mode). */
+  searchPassages(docId, query, limit = 5) {
+    const q = ftsQuery(query);
+    if (!q) return [];
+    return this.db.prepare(`
+      SELECT m.passage_idx AS passageIdx, m.char_start AS charStart,
+             document_passages.body AS body, bm25(document_passages) AS rank
+      FROM document_passages
+      JOIN document_passage_map m ON m.passage_rowid = document_passages.rowid
+      WHERE document_passages MATCH ? AND m.doc_id = ?
+      ORDER BY rank
+      LIMIT ?
+    `).all(q, docId, limit);
+  }
+
+  /** Every passage of a document, in order -- the candidate set for dense and hybrid ranking. */
+  passages(docId) {
+    return this.db.prepare(`
+      SELECT m.passage_rowid AS rowid, m.passage_idx AS passageIdx, m.char_start AS charStart, document_passages.body AS body
+      FROM document_passage_map m JOIN document_passages ON document_passages.rowid = m.passage_rowid
+      WHERE m.doc_id = ? ORDER BY m.passage_idx
+    `).all(docId);
+  }
+
+  /**
+   * BM25 scores per passage, higher is better. `any`: any query word may
+   * match (the hybrid's lexical side, so partial matches still rank above
+   * none -- dense ranking handles the rest); otherwise all of them must.
+   */
+  lexicalScores(docId, query, { any = true } = {}) {
+    const q = ftsQuery(query, { any });
+    if (!q) return new Map();
+    const rows = this.db.prepare(`
+      SELECT m.passage_rowid AS rowid, bm25(document_passages) AS rank
+      FROM document_passages JOIN document_passage_map m ON m.passage_rowid = document_passages.rowid
+      WHERE document_passages MATCH ? AND m.doc_id = ?
+    `).all(q, docId);
+    return new Map(rows.map((r) => [r.rowid, -r.rank]));
+  }
+
+  /** Documents with passages not yet embedded under this model (for backfill). */
+  missingVectors(modelKey) {
+    return this.db.prepare(`
+      SELECT DISTINCT m.doc_id AS id FROM document_passage_map m
+      LEFT JOIN embeddings e ON e.corpus = ? AND e.unit_id = m.passage_rowid AND e.model_key = ? AND e.chunk = 0
+      WHERE e.unit_id IS NULL
+    `).all(CORPUS.DOCUMENTS, modelKey).map((r) => r.id);
+  }
+}