tinywebui 0.1.3 → 0.1.5

package/src/store/index.js

@@ -1,5 +1,5 @@
 import { DatabaseSync } from 'node:sqlite';
-import { mkdirSync } from 'node:fs';
+import { chmodSync, closeSync, existsSync, mkdirSync, openSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { SCHEMA_VERSION, migrate as migrateSchema } from './schema.js';
 import { ChatStore } from './chats.js';
@@ -11,14 +11,12 @@ import { EmbeddingStore } from './embeddings.js';
 import { TurnStore } from './turns.js';
 import { SearchStore } from './search.js';
 import { UserStore } from './users.js';
-
 export { SCHEMA_VERSION } from './schema.js';
 export { ALL_USERS } from './scope.js';
 export { PASSAGE_SIZE, PASSAGE_OVERLAP } from './documents.js';
 export { toWire, toView } from './wire.js';
 export { CORPUS } from './embeddings.js';
 export { AUX_KIND } from './usage.js';
-
 /**
  * Conversation storage.
  *
@@ -37,54 +35,102 @@ export { AUX_KIND } from './usage.js';
  * file of the same name next to this one. An area that needs another is
  * handed it here, so every dependency between areas is listed in one place.
  */
-
+/**
+ * Conversations, password hashes and session hashes: readable by the owner
+ * only, like the config. A new file is created that way before SQLite opens
+ * it, since SQLite gives its -wal and -shm files the database's own mode; an
+ * existing one is tightened. A file someone else owns keeps the mode they set.
+ */
+function ownerOnly(path) {
+    if (!existsSync(path))
+        closeSync(openSync(path, 'a', 0o600));
+    if (process.platform === 'win32')
+        return;
+    for (const p of [path, `${path}-wal`, `${path}-shm`]) {
+        try {
+            if (existsSync(p))
+                chmodSync(p, 0o600);
+        }
+        catch { /* not ours to change */ }
+    }
+}
 /** Thrown when a database is behind and migrating was not allowed. */
-export class MigrationRequiredError extends Error {}
-
+export class MigrationRequiredError extends Error {
+}
 export class Store {
-  /**
-   * `migrate: false` refuses to touch an existing database that is behind
-   * SCHEMA_VERSION instead of upgrading it on open; a brand-new file is
-   * always created at the current version.
-   */
-  constructor(path, { migrate = true } = {}) {
-    if (path !== ':memory:') mkdirSync(dirname(path), { recursive: true });
-    this.db = new DatabaseSync(path);
-    const found = this.db.prepare('PRAGMA user_version').get().user_version;
-    const fresh = !this.db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='chats'").get();
-    if (!fresh && found > SCHEMA_VERSION) {
-      this.db.close();
-      throw new MigrationRequiredError(`database is at schema ${found}, newer than this TinyWebUI (${SCHEMA_VERSION}); upgrade TinyWebUI`);
+    db;
+    migratedFrom;
+    embeddings;
+    messages;
+    automations;
+    documents;
+    chats;
+    turns;
+    usage;
+    search;
+    users;
+    /**
+     * `migrate: false` refuses to touch an existing database that is behind
+     * SCHEMA_VERSION instead of upgrading it on open; a brand-new file is
+     * always created at the current version.
+     */
+    constructor(path, { migrate = true } = {}) {
+        if (path !== ':memory:') {
+            mkdirSync(dirname(path), { recursive: true });
+            ownerOnly(path);
+        }
+        this.db = new DatabaseSync(path);
+        const found = this.db.prepare('PRAGMA user_version').get().user_version;
+        const fresh = !this.db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='chats'").get();
+        if (!fresh && found > SCHEMA_VERSION) {
+            this.db.close();
+            throw new MigrationRequiredError(`database is at schema ${found}, newer than this TinyWebUI (${SCHEMA_VERSION}); upgrade TinyWebUI`);
+        }
+        if (!fresh && found < SCHEMA_VERSION && !migrate) {
+            this.db.close();
+            throw new MigrationRequiredError(`database is at schema ${found}, needs ${SCHEMA_VERSION}: run \`tinywebui migrate\``);
+        }
+        this.migratedFrom = fresh ? null : found;
+        migrateSchema(this.db, { fresh });
+        const { db } = this;
+        this.embeddings = new EmbeddingStore(db);
+        this.messages = new MessageStore(db);
+        this.automations = new AutomationStore(db);
+        this.documents = new DocumentStore(db, { embeddings: this.embeddings });
+        this.chats = new ChatStore(db, { messages: this.messages, automations: this.automations, documents: this.documents, embeddings: this.embeddings });
+        this.turns = new TurnStore(db, { chats: this.chats });
+        this.usage = new UsageStore(db);
+        this.search = new SearchStore(db);
+        this.users = new UserStore(db);
+    }
+    schemaVersion() {
+        return this.db.prepare('PRAGMA user_version').get().user_version;
+    }
+    /** Gives pre-account, unowned data to the first local administrator. */
+    claimUnowned(userId, { removeUserId = null } = {}) {
+        this.db.exec('BEGIN');
+        try {
+            this.chats.claimUnowned(userId);
+            this.documents.claimUnowned(userId);
+            this.messages.claimUnownedArtifacts(userId);
+            this.automations.claimUnowned(userId);
+            if (removeUserId)
+                this.users.removePasswordless(removeUserId);
+            this.db.exec('COMMIT');
+        }
+        catch (err) {
+            this.db.exec('ROLLBACK');
+            throw err;
+        }
+    }
+    /** Cheap liveness probe of the database, for /readyz. */
+    ping() {
+        return this.db.prepare('SELECT 1 AS ok').get().ok === 1;
     }
-    if (!fresh && found < SCHEMA_VERSION && !migrate) {
-      this.db.close();
-      throw new MigrationRequiredError(`database is at schema ${found}, needs ${SCHEMA_VERSION}: run \`tinywebui migrate\``);
+    close() {
+        try {
+            this.db.close();
+        }
+        catch { /* already gone */ }
     }
-    this.migratedFrom = fresh ? null : found;
-    migrateSchema(this.db, { fresh });
-
-    const { db } = this;
-    this.embeddings = new EmbeddingStore(db);
-    this.messages = new MessageStore(db);
-    this.automations = new AutomationStore(db);
-    this.documents = new DocumentStore(db, { embeddings: this.embeddings });
-    this.chats = new ChatStore(db, { messages: this.messages, automations: this.automations, documents: this.documents, embeddings: this.embeddings });
-    this.turns = new TurnStore(db, { chats: this.chats });
-    this.usage = new UsageStore(db);
-    this.search = new SearchStore(db);
-    this.users = new UserStore(db);
-  }
-
-  schemaVersion() {
-    return this.db.prepare('PRAGMA user_version').get().user_version;
-  }
-
-  /** Cheap liveness probe of the database, for /readyz. */
-  ping() {
-    return this.db.prepare('SELECT 1 AS ok').get().ok === 1;
-  }
-
-  close() {
-    try { this.db.close(); } catch { /* already gone */ }
-  }
 }

package/src/store/messages.js

@@ -1,93 +1,68 @@
 import { randomBytes } from 'node:crypto';
-
 // The transcript: messages in order, and the tool-result artifacts behind them.
 // One area of the Store; see index.js.
-
 export class MessageStore {
-  constructor(db, deps = {}) {
-    this.db = db;
-    Object.assign(this, deps);
-  }
-
-  nextSeq(chatId) {
-    const row = this.db.prepare('SELECT MAX(seq) AS m FROM messages WHERE chat_id = ?').get(chatId);
-    return (row?.m ?? -1) + 1;
-  }
-
-  /** Drops a chat's messages from `seq` on (a rewind). Returns how many went. */
-  deleteFrom(chatId, seq) {
-    return this.db.prepare('DELETE FROM messages WHERE chat_id = ? AND seq >= ?').run(chatId, seq).changes;
-  }
-
-  /** Drops a chat's whole transcript and the artifacts behind it (the chat is going). */
-  deleteForChat(chatId) {
-    this.db.prepare('DELETE FROM messages WHERE chat_id = ?').run(chatId);
-    this.db.prepare('DELETE FROM artifacts WHERE chat_id = ?').run(chatId);
-  }
-
-  /** Appends one message. Append-only by design: rows are never reordered. */
-  add(chatId, msg) {
-    const seq = this.nextSeq(chatId);
-    this.db.prepare(`
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    claimUnownedArtifacts(userId) {
+        this.db.prepare('UPDATE artifacts SET user_id = ? WHERE user_id IS NULL').run(userId);
+    }
+    nextSeq(chatId) {
+        const row = this.db.prepare('SELECT MAX(seq) AS m FROM messages WHERE chat_id = ?').get(chatId);
+        return (row?.m ?? -1) + 1;
+    }
+    /** Drops a chat's messages from `seq` on (a rewind). Returns how many went. */
+    deleteFrom(chatId, seq) {
+        return this.db.prepare('DELETE FROM messages WHERE chat_id = ? AND seq >= ?').run(chatId, seq).changes;
+    }
+    /** Drops a chat's whole transcript and the artifacts behind it (the chat is going). */
+    deleteForChat(chatId) {
+        this.db.prepare('DELETE FROM messages WHERE chat_id = ?').run(chatId);
+        this.db.prepare('DELETE FROM artifacts WHERE chat_id = ?').run(chatId);
+    }
+    /** Appends one message. Append-only by design: rows are never reordered. */
+    add(chatId, msg) {
+        const seq = this.nextSeq(chatId);
+        this.db.prepare(`
       INSERT INTO messages
         (chat_id, seq, role, content, tool_call_id, tool_calls_json,
          reasoning, reasoning_details_json, artifact_id, stub_text, usage_json,
          model, created_at, images_json, origin_json)
       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-    `).run(
-      chatId, seq, msg.role,
-      msg.content ?? null,
-      msg.tool_call_id ?? null,
-      msg.tool_calls ? JSON.stringify(msg.tool_calls) : null,
-      msg.reasoning ?? null,
-      msg.reasoning_details ? JSON.stringify(msg.reasoning_details) : null,
-      msg.artifact_id ?? null,
-      msg.stub_text ?? null,
-      msg.usage ? JSON.stringify(msg.usage) : null,
-      msg.model ?? null,
-      Date.now(),
-      msg.images ? JSON.stringify(msg.images) : null,
-      msg.origin ? JSON.stringify(msg.origin) : null
-    );
-    return seq;
-  }
-
-  updateUsage(chatId, seq, usage) {
-    this.db.prepare('UPDATE messages SET usage_json = ? WHERE chat_id = ? AND seq = ?')
-      .run(JSON.stringify(usage), chatId, seq);
-  }
-
-  list(chatId) {
-    return this.db.prepare(
-      'SELECT * FROM messages WHERE chat_id = ? ORDER BY seq ASC'
-    ).all(chatId);
-  }
-
-  /**
-   * Writes a stub onto an already-stored tool message. This is the ONE place
-   * history is rewritten, and it happens only at an epoch boundary. `content`
-   * is left untouched so the human transcript keeps the full output -- only
-   * what goes to the model shrinks.
-   */
-  setStub(messageId, stubText) {
-    this.db.prepare('UPDATE messages SET stub_text = ? WHERE id = ?').run(stubText, messageId);
-  }
-
-  /** Takes a message's images off the wire at an epoch; the transcript keeps them. */
-  dropImages(messageId) {
-    this.db.prepare('UPDATE messages SET images_dropped = 1 WHERE id = ?').run(messageId);
-  }
-
-  addArtifact(chatId, { toolName, args, content }) {
-    const id = randomBytes(12).toString('hex');
-    this.db.prepare(`
+    `).run(chatId, seq, msg.role, msg.content ?? null, msg.tool_call_id ?? null, msg.tool_calls ? JSON.stringify(msg.tool_calls) : null, msg.reasoning ?? null, msg.reasoning_details ? JSON.stringify(msg.reasoning_details) : null, msg.artifact_id ?? null, msg.stub_text ?? null, msg.usage ? JSON.stringify(msg.usage) : null, msg.model ?? null, Date.now(), msg.images ? JSON.stringify(msg.images) : null, msg.origin ? JSON.stringify(msg.origin) : null);
+        return seq;
+    }
+    updateUsage(chatId, seq, usage) {
+        this.db.prepare('UPDATE messages SET usage_json = ? WHERE chat_id = ? AND seq = ?')
+            .run(JSON.stringify(usage), chatId, seq);
+    }
+    list(chatId) {
+        return this.db.prepare('SELECT * FROM messages WHERE chat_id = ? ORDER BY seq ASC').all(chatId);
+    }
+    /**
+     * Writes a stub onto an already-stored tool message. This is the ONE place
+     * history is rewritten, and it happens only at an epoch boundary. `content`
+     * is left untouched so the human transcript keeps the full output -- only
+     * what goes to the model shrinks.
+     */
+    setStub(messageId, stubText) {
+        this.db.prepare('UPDATE messages SET stub_text = ? WHERE id = ?').run(stubText, messageId);
+    }
+    /** Takes a message's images off the wire at an epoch; the transcript keeps them. */
+    dropImages(messageId) {
+        this.db.prepare('UPDATE messages SET images_dropped = 1 WHERE id = ?').run(messageId);
+    }
+    addArtifact(chatId, { toolName, args, content }) {
+        const id = randomBytes(12).toString('hex');
+        this.db.prepare(`
       INSERT INTO artifacts (id, chat_id, tool_name, args_json, content, char_len, created_at)
       VALUES (?, ?, ?, ?, ?, ?, ?)
     `).run(id, chatId, toolName, JSON.stringify(args ?? {}), content, content.length, Date.now());
-    return id;
-  }
-
-  getArtifact(id, chatId) {
-    return this.db.prepare('SELECT * FROM artifacts WHERE id = ? AND chat_id = ?').get(id, chatId) || null;
-  }
+        return id;
+    }
+    getArtifact(id, chatId) {
+        return this.db.prepare('SELECT * FROM artifacts WHERE id = ? AND chat_id = ?').get(id, chatId) || null;
+    }
 }

package/src/store/schema.js

@@ -1,8 +1,6 @@
-/* The database shape: tables, triggers, the schema version, and the migrations that reach it. */
-
 export const SCHEMA = `
--- Optional auth/RBAC (config authMode 'single'/'multiuser'). Unused and
--- empty when authMode is explicitly 'none' -- these tables cost nothing
+-- Optional auth/RBAC (config authMode 'multiuser'). Unused and
+-- empty when authMode is explicitly 'local' -- these tables cost nothing
 -- to have around.
 CREATE TABLE IF NOT EXISTS users (
   id            TEXT PRIMARY KEY,
@@ -25,6 +23,20 @@ CREATE TABLE IF NOT EXISTS sessions (
   expires_at INTEGER NOT NULL
 );
 
+-- Local multi-user enrollment. The browser receives the raw invite once;
+-- only its sha256 digest is stored, just like a session token.
+CREATE TABLE IF NOT EXISTS invitations (
+  id         TEXT PRIMARY KEY,
+  token_hash TEXT NOT NULL UNIQUE,
+  email      TEXT,
+  created_by TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  created_at INTEGER NOT NULL,
+  expires_at INTEGER NOT NULL,
+  used_at    INTEGER,
+  used_by    TEXT REFERENCES users(id) ON DELETE SET NULL
+);
+CREATE INDEX IF NOT EXISTS invitations_active ON invitations(expires_at) WHERE used_at IS NULL;
+
 -- One-time migration flags (e.g. backfilling user_id onto pre-auth rows),
 -- so a backfill never accidentally reruns and clobbers real ownership later.
 CREATE TABLE IF NOT EXISTS meta (
@@ -315,7 +327,6 @@ CREATE TRIGGER messages_fts_au AFTER UPDATE ON messages BEGIN
     SELECT new.id, coalesce(new.content, '') WHERE new.role IN ('user', 'assistant', 'system');
 END;
 `;
-
 /**
  * The bulk form of the supersede trigger above, for correcting whatever an
  * earlier shape of these triggers already left indexed: any assistant row
@@ -328,14 +339,12 @@ const SUPERSEDE_CLEANUP = `
     WHERE m.role = 'assistant' AND nxt.role IN ('assistant', 'tool')
   )
 `;
-
 /**
  * Bumped whenever the constructor's migrations change the shape of the
  * database. Stored in SQLite's user_version, so deployments can see where a
  * file stands and run migrations deliberately (`tinywebui migrate`).
  */
-export const SCHEMA_VERSION = 12;
-
+export const SCHEMA_VERSION = 13;
 /**
  * Adds a column if it isn't already there. `CREATE TABLE IF NOT EXISTS` is a
  * no-op against a live table, so a column added to a table's shape after
@@ -344,10 +353,10 @@ export const SCHEMA_VERSION = 12;
  * `messages`. `ALTER TABLE ADD COLUMN` itself has no IF NOT EXISTS form.
  */
 function ensureColumn(db, table, col, decl) {
-  const cols = db.prepare(`PRAGMA table_info(${table})`).all().map((c) => c.name);
-  if (!cols.includes(col)) db.exec(`ALTER TABLE ${table} ADD COLUMN ${col} ${decl}`);
+    const cols = db.prepare(`PRAGMA table_info(${table})`).all().map((c) => c.name);
+    if (!cols.includes(col))
+        db.exec(`ALTER TABLE ${table} ADD COLUMN ${col} ${decl}`);
 }
-
 /**
  * Schema 4 renamed "chunks" to what they are: document_chunks (FTS) and
  * its map became document_passages / document_passage_map, and the name
@@ -355,126 +364,138 @@ function ensureColumn(db, table, col, decl) {
  * would otherwise see the old FTS table under the new chunk table's name.
  */
 function renameToPassages(db) {
-  const has = (name) => Boolean(db.prepare('SELECT 1 FROM sqlite_master WHERE name = ?').get(name));
-  if (has('document_chunk_map')) {
-    db.exec('BEGIN');
-    try {
-      db.exec('ALTER TABLE document_chunks RENAME TO document_passages');
-      db.exec('ALTER TABLE document_chunk_map RENAME TO document_passage_map');
-      db.exec('ALTER TABLE document_passage_map RENAME COLUMN chunk_rowid TO passage_rowid');
-      db.exec('ALTER TABLE document_passage_map RENAME COLUMN chunk_idx TO passage_idx');
-      db.exec('DROP INDEX IF EXISTS document_chunk_map_doc');
-      db.exec('COMMIT');
-    } catch (err) { db.exec('ROLLBACK'); throw err; }
-  }
-  // Vectors from the unreleased schema 3 layout: recomputed by the backfill.
-  db.exec('DROP TABLE IF EXISTS document_chunk_embeddings');
+    const has = (name) => Boolean(db.prepare('SELECT 1 FROM sqlite_master WHERE name = ?').get(name));
+    if (has('document_chunk_map')) {
+        db.exec('BEGIN');
+        try {
+            db.exec('ALTER TABLE document_chunks RENAME TO document_passages');
+            db.exec('ALTER TABLE document_chunk_map RENAME TO document_passage_map');
+            db.exec('ALTER TABLE document_passage_map RENAME COLUMN chunk_rowid TO passage_rowid');
+            db.exec('ALTER TABLE document_passage_map RENAME COLUMN chunk_idx TO passage_idx');
+            db.exec('DROP INDEX IF EXISTS document_chunk_map_doc');
+            db.exec('COMMIT');
+        }
+        catch (err) {
+            db.exec('ROLLBACK');
+            throw err;
+        }
+    }
+    // Vectors from the unreleased schema 3 layout: recomputed by the backfill.
+    db.exec('DROP TABLE IF EXISTS document_chunk_embeddings');
 }
-
 /** Schema 7 and earlier kept document vectors in their own table; they move into `embeddings` as-is. */
 function moveDocumentVectors(db) {
-  const cols = db.prepare('PRAGMA table_info(document_chunks)').all().map((c) => c.name);
-  if (!cols.includes('vec')) return;
-  db.exec('BEGIN');
-  try {
-    db.exec(`INSERT OR IGNORE INTO embeddings (corpus, unit_id, owner_id, model_key, digest, chunk, vec)
+    const cols = db.prepare('PRAGMA table_info(document_chunks)').all().map((c) => c.name);
+    if (!cols.includes('vec'))
+        return;
+    db.exec('BEGIN');
+    try {
+        db.exec(`INSERT OR IGNORE INTO embeddings (corpus, unit_id, owner_id, model_key, digest, chunk, vec)
       SELECT 'documents', passage_rowid, doc_id, model_key, '', chunk, vec FROM document_chunks`);
-    db.exec('DROP TABLE document_chunks');
-    db.exec('COMMIT');
-  } catch (err) { db.exec('ROLLBACK'); throw err; }
+        db.exec('DROP TABLE document_chunks');
+        db.exec('COMMIT');
+    }
+    catch (err) {
+        db.exec('ROLLBACK');
+        throw err;
+    }
 }
-
 /** Brings an open database to SCHEMA_VERSION. `fresh`: it has no tables yet. */
 export function migrate(db, { fresh }) {
-  db.exec('PRAGMA journal_mode = WAL');
-  db.exec('PRAGMA foreign_keys = ON');
-  if (!fresh) renameToPassages(db);
-  db.exec(SCHEMA);
-  if (!fresh) moveDocumentVectors(db);
-  // Nullable everywhere: unused (null) when auth is off, the exact behavior
-  // installs already have; set only once per-user scoping is opted into.
-  ensureColumn(db, 'chats', 'user_id', 'TEXT');
-  ensureColumn(db, 'chats', 'folder', 'TEXT');
-  ensureColumn(db, 'chats', 'tags_json', "TEXT NOT NULL DEFAULT '[]'");
-  // First message the model still sees once the hard window has moved; -1
-  // until it ever has. See planWindow in compact.js.
-  ensureColumn(db, 'chats', 'window_seq', 'INTEGER NOT NULL DEFAULT -1');
-  // LLM summary of what the window cut off, as JSON { summary, throughSeq,
-  // scopeStart, model }; NULL when there is none. Only valid together with
-  // window_seq, so the two are always written in one statement.
-  ensureColumn(db, 'chats', 'checkpoint_json', 'TEXT');
-  // The message seq a task was added at, so a rewind past it removes it. -1
-  // for tasks from before this was tracked: no rewind reaches them.
-  ensureColumn(db, 'tasks', 'created_seq', 'INTEGER NOT NULL DEFAULT -1');
-  // Set once an epoch has taken a message's images off the wire; the images
-  // themselves stay in images_json for the transcript.
-  ensureColumn(db, 'messages', 'images_dropped', 'INTEGER NOT NULL DEFAULT 0');
-  // Where a message came from when it was not typed by the user, e.g. an
-  // automation run: the page draws it as that, not as a user bubble. The
-  // model still gets `content` as an ordinary user turn.
-  ensureColumn(db, 'messages', 'origin_json', 'TEXT');
-  ensureColumn(db, 'documents', 'user_id', 'TEXT');
-  // The passage split a document was stored with; NULL means the original
-  // 1800/200, from before it was configurable.
-  ensureColumn(db, 'documents', 'passage_size', 'INTEGER');
-  ensureColumn(db, 'documents', 'passage_overlap', 'INTEGER');
-  // Fingerprint of the uploaded bytes (see document_blobs); NULL for documents
-  // stored before originals were kept.
-  ensureColumn(db, 'documents', 'md5', 'TEXT');
-  db.exec('CREATE INDEX IF NOT EXISTS documents_md5 ON documents(md5)');
-  ensureColumn(db, 'artifacts', 'user_id', 'TEXT');
-  ensureColumn(db, 'automation_runs', 'trigger_type', "TEXT NOT NULL DEFAULT 'schedule'");
-  // Trusted-header auth: the gateway's immutable subject. Email and name are
-  // metadata reconciled from the gateway; external_id decides who owns what.
-  ensureColumn(db, 'users', 'external_id', 'TEXT');
-  ensureColumn(db, 'users', 'name', 'TEXT');
-  db.exec('CREATE UNIQUE INDEX IF NOT EXISTS users_external_id ON users(external_id)');
-  // Per-user preferences (tier 3): harmless choices like which allowed
-  // model to use. Deployment settings never live here.
-  db.exec(`CREATE TABLE IF NOT EXISTS user_prefs (
+    db.exec('PRAGMA journal_mode = WAL');
+    db.exec('PRAGMA foreign_keys = ON');
+    if (!fresh)
+        renameToPassages(db);
+    db.exec(SCHEMA);
+    if (!fresh)
+        moveDocumentVectors(db);
+    // Nullable everywhere: unused (null) when auth is off, the exact behavior
+    // installs already have; set only once per-user scoping is opted into.
+    ensureColumn(db, 'chats', 'user_id', 'TEXT');
+    ensureColumn(db, 'chats', 'folder', 'TEXT');
+    ensureColumn(db, 'chats', 'tags_json', "TEXT NOT NULL DEFAULT '[]'");
+    // First message the model still sees once the hard window has moved; -1
+    // until it ever has. See planWindow in compact.js.
+    ensureColumn(db, 'chats', 'window_seq', 'INTEGER NOT NULL DEFAULT -1');
+    // LLM summary of what the window cut off, as JSON { summary, throughSeq,
+    // scopeStart, model }; NULL when there is none. Only valid together with
+    // window_seq, so the two are always written in one statement.
+    ensureColumn(db, 'chats', 'checkpoint_json', 'TEXT');
+    // The message seq a task was added at, so a rewind past it removes it. -1
+    // for tasks from before this was tracked: no rewind reaches them.
+    ensureColumn(db, 'tasks', 'created_seq', 'INTEGER NOT NULL DEFAULT -1');
+    // Set once an epoch has taken a message's images off the wire; the images
+    // themselves stay in images_json for the transcript.
+    ensureColumn(db, 'messages', 'images_dropped', 'INTEGER NOT NULL DEFAULT 0');
+    // Where a message came from when it was not typed by the user, e.g. an
+    // automation run: the page draws it as that, not as a user bubble. The
+    // model still gets `content` as an ordinary user turn.
+    ensureColumn(db, 'messages', 'origin_json', 'TEXT');
+    ensureColumn(db, 'documents', 'user_id', 'TEXT');
+    // The passage split a document was stored with; NULL means the original
+    // 1800/200, from before it was configurable.
+    ensureColumn(db, 'documents', 'passage_size', 'INTEGER');
+    ensureColumn(db, 'documents', 'passage_overlap', 'INTEGER');
+    // Fingerprint of the uploaded bytes (see document_blobs); NULL for documents
+    // stored before originals were kept.
+    ensureColumn(db, 'documents', 'md5', 'TEXT');
+    db.exec('CREATE INDEX IF NOT EXISTS documents_md5 ON documents(md5)');
+    ensureColumn(db, 'artifacts', 'user_id', 'TEXT');
+    ensureColumn(db, 'automation_runs', 'trigger_type', "TEXT NOT NULL DEFAULT 'schedule'");
+    // Trusted-header auth: the gateway's immutable subject. Email and name are
+    // metadata reconciled from the gateway; external_id decides who owns what.
+    ensureColumn(db, 'users', 'external_id', 'TEXT');
+    ensureColumn(db, 'users', 'name', 'TEXT');
+    db.exec('CREATE UNIQUE INDEX IF NOT EXISTS users_external_id ON users(external_id)');
+    // Per-user preferences (tier 3): harmless choices like which allowed
+    // model to use. Deployment settings never live here.
+    db.exec(`CREATE TABLE IF NOT EXISTS user_prefs (
     user_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
     key     TEXT NOT NULL,
     value   TEXT,
     PRIMARY KEY (user_id, key)
   )`);
-  // `messages` may already exist from before these columns did --
-  // CREATE TABLE IF NOT EXISTS above is a no-op against a live table, so
-  // they're added here instead, self-repairing like the FTS backfill below.
-  const cols = db.prepare('PRAGMA table_info(messages)').all().map((c) => c.name);
-  if (!cols.includes('model')) db.exec('ALTER TABLE messages ADD COLUMN model TEXT');
-  if (!cols.includes('created_at')) db.exec('ALTER TABLE messages ADD COLUMN created_at INTEGER');
-  if (!cols.includes('images_json')) db.exec('ALTER TABLE messages ADD COLUMN images_json TEXT');
-  db.exec('CREATE INDEX IF NOT EXISTS messages_usage_ts ON messages(created_at) WHERE usage_json IS NOT NULL');
-  // A tool row, or an assistant note later superseded within its own turn,
-  // indexed under an earlier shape of the triggers above is corrected on
-  // open rather than left to linger -- the triggers alone only ever
-  // prevent NEW drift, not clean up old drift.
-  db.exec(`
+    // `messages` may already exist from before these columns did --
+    // CREATE TABLE IF NOT EXISTS above is a no-op against a live table, so
+    // they're added here instead, self-repairing like the FTS backfill below.
+    const cols = db.prepare('PRAGMA table_info(messages)').all().map((c) => c.name);
+    if (!cols.includes('model'))
+        db.exec('ALTER TABLE messages ADD COLUMN model TEXT');
+    if (!cols.includes('created_at'))
+        db.exec('ALTER TABLE messages ADD COLUMN created_at INTEGER');
+    if (!cols.includes('images_json'))
+        db.exec('ALTER TABLE messages ADD COLUMN images_json TEXT');
+    db.exec('CREATE INDEX IF NOT EXISTS messages_usage_ts ON messages(created_at) WHERE usage_json IS NOT NULL');
+    // A tool row, or an assistant note later superseded within its own turn,
+    // indexed under an earlier shape of the triggers above is corrected on
+    // open rather than left to linger -- the triggers alone only ever
+    // prevent NEW drift, not clean up old drift.
+    db.exec(`
     DELETE FROM messages_fts WHERE rowid IN (
       SELECT id FROM messages WHERE role NOT IN ('user', 'assistant', 'system')
     )
   `);
-  db.exec(SUPERSEDE_CLEANUP);
-  // The triggers keep the index in step with every write from here on, but
-  // they cannot backfill history that predates them -- a database from
-  // before search existed opens with a `messages_fts` that is real but
-  // empty for rows that should be in it. A count mismatch, restricted to
-  // the roles that belong in the index, is also what any other divergence
-  // would look like, so this doubles as self-repair: whatever is missing
-  // is added, nothing already correct is touched.
-  const { m, f } = db.prepare(`
+    db.exec(SUPERSEDE_CLEANUP);
+    // The triggers keep the index in step with every write from here on, but
+    // they cannot backfill history that predates them -- a database from
+    // before search existed opens with a `messages_fts` that is real but
+    // empty for rows that should be in it. A count mismatch, restricted to
+    // the roles that belong in the index, is also what any other divergence
+    // would look like, so this doubles as self-repair: whatever is missing
+    // is added, nothing already correct is touched.
+    const { m, f } = db.prepare(`
     SELECT
       (SELECT COUNT(*) FROM messages WHERE role IN ('user', 'assistant', 'system')) AS m,
       (SELECT COUNT(*) FROM messages_fts) AS f
   `).get();
-  if (m !== f) {
-    db.exec(`
+    if (m !== f) {
+        db.exec(`
       INSERT INTO messages_fts(rowid, body)
       SELECT id, coalesce(content, '')
       FROM messages
       WHERE role IN ('user', 'assistant', 'system')
         AND id NOT IN (SELECT rowid FROM messages_fts)
     `);
-  }
-  db.exec(`PRAGMA user_version = ${SCHEMA_VERSION}`);
+    }
+    db.exec(`PRAGMA user_version = ${SCHEMA_VERSION}`);
 }