crewly 1.6.1 → 1.6.3

package/dist/backend/backend/src/services/chat-v2/sqlite/channel.store.js

@@ -0,0 +1,194 @@
+/**
+ * ChannelStore — CRUD for `chat_channels`.
+ *
+ * All authorization is handled at a higher layer (`ChatV2Service`);
+ * this store only enforces DB-level invariants (FKs, unique indexes).
+ *
+ * @module services/chat-v2/sqlite/channel.store
+ */
+import { randomUUID } from 'crypto';
+import { CHAT_ERROR_CODES, ChatError, } from '../types.js';
+// ---------------------------------------------------------------------------
+// Constants — shared SELECT column list, single source of truth
+// ---------------------------------------------------------------------------
+/**
+ * Canonical column list for `chat_channels` SELECTs. Including all Phase A
+ * columns (type / team_id / project_id / target_member_id) here keeps every
+ * read path in this store mapping to a fully-populated `ChatChannelRow`.
+ */
+const CHANNEL_SELECT_COLUMNS = `
+  id, agent_session, owner_user_id, name, purpose,
+  created_at, archived_at, last_message_at,
+  type, team_id, project_id, target_member_id
+`;
+// ---------------------------------------------------------------------------
+// Store
+// ---------------------------------------------------------------------------
+/** SQLite-backed store for chat channels. */
+export class ChannelStore {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    /**
+     * Create a new channel. Enforces the 1:1 agent-binding by catching
+     * the SQLite unique-constraint error and surfacing it as a
+     * `ChatError(agent_already_bound, 409)`.
+     *
+     * @param input - The channel creation payload
+     * @returns The inserted channel row
+     * @throws {ChatError} `agent_already_bound` (409) if the agent is already bound
+     *   to another active channel.
+     */
+    create(input) {
+        const id = input.id ?? randomUUID();
+        const createdAt = input.nowMs ?? Date.now();
+        const purpose = input.purpose ?? null;
+        const channelType = input.type ?? 'dm';
+        const teamId = input.teamId ?? null;
+        const projectId = input.projectId ?? null;
+        const targetMemberId = input.targetMemberId ?? null;
+        const stmt = this.db.prepare(`INSERT INTO chat_channels
+         (id, agent_session, owner_user_id, name, purpose, created_at,
+          type, team_id, project_id, target_member_id)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+        try {
+            stmt.run(id, input.agentSession, input.ownerUserId, input.name, purpose, createdAt, channelType, teamId, projectId, targetMemberId);
+        }
+        catch (err) {
+            // Unique constraint means either the partial index on agent_session fired
+            // (the common case — 1:1 binding violated) or we raced an id collision.
+            // In either case it's safer to check `findActiveByAgentSession` before
+            // surfacing a typed error.
+            const msg = err instanceof Error ? err.message : String(err);
+            if (msg.includes('UNIQUE')) {
+                const existing = this.findActiveByAgentSession(input.agentSession);
+                if (existing) {
+                    throw new ChatError(CHAT_ERROR_CODES.AGENT_ALREADY_BOUND, 409, `Agent "${input.agentSession}" is already bound to another active channel.`, { existingChannelId: existing.id });
+                }
+            }
+            throw err;
+        }
+        const created = this.getById(id);
+        // Row must exist — insert just succeeded. This branch is for type-narrowing.
+        if (!created) {
+            throw new ChatError(CHAT_ERROR_CODES.INTERNAL, 500, 'Channel disappeared immediately after insert');
+        }
+        return created;
+    }
+    /**
+     * Look up a channel by its id (active or archived).
+     *
+     * @param id - The channel id
+     * @returns The row, or null if not found
+     */
+    getById(id) {
+        const row = this.db
+            .prepare(`SELECT ${CHANNEL_SELECT_COLUMNS}
+         FROM chat_channels
+         WHERE id = ?`)
+            .get(id);
+        return row ?? null;
+    }
+    /**
+     * Find the single active channel bound to an agent session, if any.
+     * Uses the partial unique index, so at most one row is returned.
+     *
+     * @param agentSession - The agent session id
+     * @returns The active channel row, or null
+     */
+    findActiveByAgentSession(agentSession) {
+        // Phase A: scope to type='dm' so this method's contract matches the
+        // post-migration `uq_channel_agent_dm_active` partial unique index.
+        // type='channel' rows can share the empty agent_session sentinel; we
+        // never want this lookup to surface those.
+        const row = this.db
+            .prepare(`SELECT ${CHANNEL_SELECT_COLUMNS}
+         FROM chat_channels
+         WHERE agent_session = ? AND archived_at IS NULL AND type = 'dm'
+         LIMIT 1`)
+            .get(agentSession);
+        return row ?? null;
+    }
+    /**
+     * List channels owned by a user.
+     *
+     * Phase C — extended with `type` + `teamId` filter options so the
+     * `GET /api/chat/channels` endpoint can serve the channel-rail's
+     * grouped/workspace-scoped views without shipping every row to the
+     * client. Filters compose with AND; passing `undefined` for either is
+     * a no-op (the existing all-channels behavior).
+     *
+     * @param ownerUserId - The user_id whose channels to return
+     * @param options - Listing options
+     * @param options.includeArchived - When false (default), filter out archived rows
+     * @param options.limit - Max rows to return (capped at 100)
+     * @param options.type - Phase C: when set, filter rows to this channel type
+     *   (`'dm'` or `'channel'`). Useful for the channel-rail's "DMs only" /
+     *   "Channels only" views.
+     * @param options.teamId - Phase C: when set, filter rows whose `team_id`
+     *   matches. Used by the workspace-scoped Channels group; empty / null
+     *   `team_id` rows are excluded by this filter on purpose (DMs and
+     *   workspace-less rows belong to no team).
+     * @returns Channel rows sorted by `last_message_at DESC, created_at DESC`
+     */
+    listByOwner(ownerUserId, options) {
+        const includeArchived = options?.includeArchived ?? false;
+        const limit = Math.min(options?.limit ?? 50, 100);
+        // Build WHERE clauses + bound params positionally so the filter set
+        // composes cleanly. Each branch is independent — no implicit coupling.
+        const where = ['owner_user_id = ?'];
+        const params = [ownerUserId];
+        if (!includeArchived) {
+            where.push('archived_at IS NULL');
+        }
+        if (options?.type !== undefined) {
+            where.push('type = ?');
+            params.push(options.type);
+        }
+        if (options?.teamId !== undefined) {
+            where.push('team_id = ?');
+            params.push(options.teamId);
+        }
+        const sql = `
+      SELECT ${CHANNEL_SELECT_COLUMNS}
+      FROM chat_channels
+      WHERE ${where.join(' AND ')}
+      ORDER BY COALESCE(last_message_at, created_at) DESC
+      LIMIT ?
+    `;
+        params.push(limit);
+        return this.db.prepare(sql).all(...params);
+    }
+    /**
+     * Mark a channel as archived (soft-delete). No-op if already archived.
+     *
+     * @param id - The channel id
+     * @param nowMs - Optional override for the archive timestamp
+     * @returns True if a row was updated (was active), false otherwise
+     */
+    archive(id, nowMs) {
+        const result = this.db
+            .prepare(`UPDATE chat_channels
+         SET archived_at = ?
+         WHERE id = ? AND archived_at IS NULL`)
+            .run(nowMs ?? Date.now(), id);
+        return result.changes > 0;
+    }
+    /**
+     * Bump `last_message_at` to a provided timestamp if it is greater than
+     * the current value. Safe to call many times.
+     *
+     * @param id - The channel id
+     * @param timestampMs - The timestamp to record
+     */
+    touchLastMessageAt(id, timestampMs) {
+        this.db
+            .prepare(`UPDATE chat_channels
+         SET last_message_at = ?
+         WHERE id = ?
+           AND (last_message_at IS NULL OR last_message_at < ?)`)
+            .run(timestampMs, id, timestampMs);
+    }
+}
+//# sourceMappingURL=channel.store.js.map

package/dist/backend/backend/src/services/chat-v2/sqlite/channel.store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel.store.js","sourceRoot":"","sources":["../../../../../../../backend/src/services/chat-v2/sqlite/channel.store.ts"],"names":[],"mappings":"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"}

package/dist/backend/backend/src/services/chat-v2/sqlite/chat-db.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Chat V2 SQLite bootstrap.
+ *
+ * Opens (or creates) the chat database at the configured path, applies
+ * the Phase 1 migration idempotently, and returns a ready-to-use
+ * `better-sqlite3` Database instance.
+ *
+ * Schema matches tech-spec §3.2. All tables use `INTEGER ms-since-epoch (UTC)`
+ * for timestamps and raw UUID strings for IDs.
+ *
+ * @module services/chat-v2/sqlite/chat-db
+ */
+import { type ComponentLogger } from '../../core/logger.service.js';
+/** Type alias for a `better-sqlite3` Database instance. */
+export type ChatDatabase = import('better-sqlite3').Database;
+/**
+ * Idempotent base DDL — Phase 1 schema with Phase A column additions baked in.
+ *
+ * Safe to run every boot.
+ *
+ * Differences vs. the literal spec §3.2:
+ * - Added `IF NOT EXISTS` on every CREATE so reboots don't fail.
+ * - PRAGMAs set outside the transaction (SQLite disallows PRAGMA in txn).
+ *
+ * Phase A additions (SEALED design 2026-04-25 §3.1 + §3.2) are reflected
+ * directly in the CREATE TABLE bodies so a fresh-install database lands on
+ * the new schema in one shot. Pre-existing databases (created under the
+ * Phase 1 schema) get the same columns added by `applyPhaseAColumnUpgrades`
+ * below, which uses `ALTER TABLE ADD COLUMN` guarded by `PRAGMA table_info`.
+ */
+export declare const CHAT_V2_MIGRATION_SQL = "\nCREATE TABLE IF NOT EXISTS chat_channels (\n  id                TEXT PRIMARY KEY,\n  agent_session     TEXT NOT NULL,\n  owner_user_id     TEXT NOT NULL,\n  name              TEXT NOT NULL,\n  purpose           TEXT,\n  created_at        INTEGER NOT NULL,\n  archived_at       INTEGER,\n  last_message_at   INTEGER,\n  -- Phase A (SEALED \u00A73.1): channel-type discriminator. 'dm' preserves the\n  -- Phase 1 1:1 user\u2194agent contract; 'channel' is the Slack-like team\n  -- surface. Existing rows backfill to 'dm' via applyPhaseAColumnUpgrades.\n  type              TEXT NOT NULL DEFAULT 'dm' CHECK(type IN ('dm','channel')),\n  -- Phase A (SEALED \u00A73.1): team workspace link. Required at the service\n  -- layer when type='channel'; null for type='dm'.\n  team_id           TEXT,\n  -- Phase A (SEALED \u00A73.1): optional project link for project-scoped channels.\n  project_id        TEXT,\n  -- Phase A (SEALED \u00A73.1): for type='dm', the resolved member-ID being DM'd\n  -- (distinct from agent_session which is the wire-level binding key).\n  target_member_id  TEXT\n);\n\nCREATE INDEX IF NOT EXISTS ix_channels_owner\n  ON chat_channels(owner_user_id, archived_at);\n\n-- Phase A indexes that reference the new columns (type, team_id, thread_id)\n-- live in CHAT_V2_PHASE_A_INDEX_SQL below \u2014 they must be created AFTER\n-- applyPhaseAColumnUpgrades runs so the columns exist on legacy DBs.\n\nCREATE TABLE IF NOT EXISTS chat_messages (\n  id           TEXT PRIMARY KEY,\n  channel_id   TEXT NOT NULL REFERENCES chat_channels(id) ON DELETE CASCADE,\n  seq          INTEGER NOT NULL,\n  sender_type  TEXT NOT NULL CHECK(sender_type IN ('user','agent','system')),\n  sender_id    TEXT NOT NULL,\n  content      TEXT NOT NULL,\n  content_type TEXT NOT NULL CHECK(content_type IN ('text','markdown','image_ref','system_note'))\n               DEFAULT 'markdown',\n  created_at   INTEGER NOT NULL,\n  metadata     TEXT,\n  -- Phase A (SEALED \u00A73.2): JSON-encoded array of mention IDs (member or\n  -- team) referenced inline in the content field. Stored as a JSON string;\n  -- service layer treats null as []. Bounded at insert time; see types.ts.\n  mentions     TEXT,\n  -- Phase A (SEALED \u00A73.2): optional Slack-style thread root. When set,\n  -- this message is a reply within the thread rooted at thread_id.\n  thread_id    TEXT\n);\n\nCREATE UNIQUE INDEX IF NOT EXISTS uq_messages_channel_seq\n  ON chat_messages(channel_id, seq);\n\nCREATE INDEX IF NOT EXISTS ix_messages_channel_created\n  ON chat_messages(channel_id, created_at DESC);\n\n-- Phase 1: partial unique index for clientMessageId-based idempotency (spec \u00A74.4)\nCREATE UNIQUE INDEX IF NOT EXISTS uq_messages_client_id\n  ON chat_messages(channel_id, json_extract(metadata, '$.clientMessageId'))\n  WHERE json_extract(metadata, '$.clientMessageId') IS NOT NULL;\n\nCREATE TABLE IF NOT EXISTS chat_attachments (\n  id            TEXT PRIMARY KEY,\n  message_id    TEXT NOT NULL REFERENCES chat_messages(id) ON DELETE CASCADE,\n  kind          TEXT NOT NULL CHECK(kind IN ('image')),\n  mime_type     TEXT NOT NULL,\n  size_bytes    INTEGER NOT NULL,\n  local_path    TEXT NOT NULL,\n  original_name TEXT,\n  created_at    INTEGER NOT NULL\n);\n\nCREATE INDEX IF NOT EXISTS ix_attachments_message\n  ON chat_attachments(message_id);\n\nCREATE TABLE IF NOT EXISTS chat_offline_queue (\n  id            INTEGER PRIMARY KEY AUTOINCREMENT,\n  channel_id    TEXT NOT NULL,\n  agent_session TEXT NOT NULL,\n  message_id    TEXT NOT NULL REFERENCES chat_messages(id) ON DELETE CASCADE,\n  queued_at     INTEGER NOT NULL,\n  delivered_at  INTEGER,\n  attempts      INTEGER NOT NULL DEFAULT 0\n);\n\nCREATE INDEX IF NOT EXISTS ix_queue_pending\n  ON chat_offline_queue(agent_session, delivered_at)\n  WHERE delivered_at IS NULL;\n";
+/**
+ * Phase A indexes that reference Phase A columns. Must run AFTER
+ * `applyPhaseAColumnUpgrades` adds those columns on pre-Phase-A databases —
+ * otherwise the partial-index `WHERE` clauses fail with "no such column".
+ *
+ * On a fresh database this runs after `CHAT_V2_MIGRATION_SQL` has already
+ * baked the columns into the CREATE TABLE bodies, so each step is a
+ * harmless no-op (`CREATE INDEX IF NOT EXISTS`).
+ */
+export declare const CHAT_V2_PHASE_A_INDEX_SQL = "\n-- Phase A (SEALED \u00A73.1): the 1:1 agent-binding only applies to type='dm'\n-- channels. type='channel' rows have agent_session='' and many such rows\n-- can coexist for the same team; the partial index intentionally excludes\n-- them so the unique constraint doesn't fire on multi-agent channels.\nCREATE UNIQUE INDEX IF NOT EXISTS uq_channel_agent_dm_active\n  ON chat_channels(agent_session)\n  WHERE archived_at IS NULL AND type = 'dm';\n\n-- Phase A (SEALED \u00A73.1): scoped lookup for \"all channels in team T\" and\n-- \"project P channels\". Indexes by team first because team-scoped reads\n-- are the dominant Phase B+ access pattern.\nCREATE INDEX IF NOT EXISTS ix_channels_team\n  ON chat_channels(team_id, archived_at)\n  WHERE team_id IS NOT NULL;\n\n-- Phase A (SEALED \u00A73.2): thread-pane lookup. Filtered to non-null so the\n-- (smaller) index only covers actual threaded replies.\nCREATE INDEX IF NOT EXISTS ix_messages_thread\n  ON chat_messages(thread_id, seq)\n  WHERE thread_id IS NOT NULL;\n";
+/**
+ * Bring a pre-existing chat database up to Phase A's schema by adding
+ * any missing columns and the new indexes / dropping the superseded ones.
+ *
+ * Safe to run on a fresh database too — every step is no-op idempotent.
+ * Specifically:
+ *   - `ensureColumn` is a no-op when the column is already present (the
+ *     fresh-install case, since the columns are baked into the CREATE
+ *     TABLE in `CHAT_V2_MIGRATION_SQL`).
+ *   - `DROP INDEX IF EXISTS uq_channel_agent_active` removes the legacy
+ *     unconditional partial index so the new dm-scoped one isn't shadowed.
+ *     The DROP is metadata-only — no row data is affected.
+ *
+ * Exported (separately from `openChatDatabase`) so tests can simulate the
+ * pre-Phase-A → Phase A migration path explicitly.
+ *
+ * @param db - The chat database handle
+ * @returns A small report describing what changed (for logging)
+ */
+export declare function applyPhaseAColumnUpgrades(db: ChatDatabase): {
+    channelsAdded: string[];
+    messagesAdded: string[];
+    legacyIndexDropped: boolean;
+};
+/**
+ * Options accepted by `openChatDatabase`.
+ */
+export interface OpenChatDatabaseOptions {
+    /** Absolute path to the SQLite file. Parent dirs will be created. */
+    dbPath: string;
+    /**
+     * When true, uses SQLite `:memory:` regardless of `dbPath`.
+     * Intended for unit tests. Defaults to false.
+     */
+    inMemory?: boolean;
+    /**
+     * When true, suppress the integrity-check warning on open. Tests use this
+     * to avoid noisy logs. Defaults to false.
+     */
+    skipIntegrityCheck?: boolean;
+    /** Optional logger override — defaults to LoggerService. */
+    logger?: ComponentLogger;
+}
+/**
+ * Open (or create) the chat database, apply PRAGMAs, run the Phase 1
+ * migration idempotently, and run a boot-time integrity check.
+ *
+ * @param options - Opener options
+ * @returns A ready-to-use better-sqlite3 Database handle
+ *
+ * @example
+ * ```ts
+ * const db = openChatDatabase({ dbPath: '/tmp/chat.db' });
+ * // ... use db ...
+ * db.close();
+ * ```
+ */
+export declare function openChatDatabase(options: OpenChatDatabaseOptions): ChatDatabase;
+//# sourceMappingURL=chat-db.d.ts.map

package/dist/backend/backend/src/services/chat-v2/sqlite/chat-db.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-db.d.ts","sourceRoot":"","sources":["../../../../../../../backend/src/services/chat-v2/sqlite/chat-db.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH,OAAO,EAAiB,KAAK,eAAe,EAAE,MAAM,8BAA8B,CAAC;AA+CnF,2DAA2D;AAC3D,MAAM,MAAM,YAAY,GAAG,OAAO,gBAAgB,EAAE,QAAQ,CAAC;AAM7D;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,qBAAqB,ovHAyFjC,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,yBAAyB,qgCAqBrC,CAAC;AA2DF;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,yBAAyB,CAAC,EAAE,EAAE,YAAY,GAAG;IAC3D,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,kBAAkB,EAAE,OAAO,CAAC;CAC7B,CA0CA;AAMD;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,qEAAqE;IACrE,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;OAGG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,4DAA4D;IAC5D,MAAM,CAAC,EAAE,eAAe,CAAC;CAC1B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,YAAY,CAwD/E"}

package/dist/backend/backend/src/services/chat-v2/sqlite/chat-db.js

@@ -0,0 +1,351 @@
+/**
+ * Chat V2 SQLite bootstrap.
+ *
+ * Opens (or creates) the chat database at the configured path, applies
+ * the Phase 1 migration idempotently, and returns a ready-to-use
+ * `better-sqlite3` Database instance.
+ *
+ * Schema matches tech-spec §3.2. All tables use `INTEGER ms-since-epoch (UTC)`
+ * for timestamps and raw UUID strings for IDs.
+ *
+ * @module services/chat-v2/sqlite/chat-db
+ */
+import * as path from 'path';
+import { existsSync, mkdirSync } from 'fs';
+import { createRequire } from 'module';
+import { pathToFileURL } from 'url';
+import { LoggerService } from '../../core/logger.service.js';
+// ---------------------------------------------------------------------------
+// Lazy better-sqlite3 loader — avoids a hard native-module dep at import time
+// ---------------------------------------------------------------------------
+/**
+ * CJS-style `require` scoped to this module. `better-sqlite3` is a native
+ * addon and must be loaded via CJS `require`, but this module compiles to
+ * ESM where the bare `require` global is undefined.
+ *
+ * Anchor `createRequire` to `process.argv[1]` (entry script) instead of
+ * `import.meta.url`. We previously used `new Function('return import.meta.url')()`
+ * to dodge ts-jest's TS1343 (CJS test compile rejects literal `import.meta`),
+ * but that trick fails at RUNTIME under ESM because `new Function(...)`
+ * evaluates in non-module scope where `import.meta` is a SyntaxError.
+ * `process.argv[1]` is always inside the project tree and lets Node's
+ * resolver walk up to find `node_modules`.
+ */
+const nodeRequire = typeof require === 'function'
+    ? require
+    : createRequire(pathToFileURL(process.argv[1] || process.cwd()).href);
+/** Cached reference to the better-sqlite3 module after first successful load. */
+let _BetterSqlite3 = null;
+/**
+ * Load `better-sqlite3` on demand. Throws a clear error if the native
+ * addon cannot be loaded (a common symptom after Node upgrades).
+ *
+ * @returns The lazily-imported better-sqlite3 module
+ */
+function getBetterSqlite3() {
+    if (!_BetterSqlite3) {
+        try {
+            _BetterSqlite3 = nodeRequire('better-sqlite3');
+        }
+        catch (err) {
+            throw new Error('better-sqlite3 native module failed to load. Run `npm rebuild better-sqlite3` to fix. ' +
+                `Original error: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    return _BetterSqlite3;
+}
+// ---------------------------------------------------------------------------
+// Migration DDL (Phase 1 base + Phase A Slack-like extensions)
+// ---------------------------------------------------------------------------
+/**
+ * Idempotent base DDL — Phase 1 schema with Phase A column additions baked in.
+ *
+ * Safe to run every boot.
+ *
+ * Differences vs. the literal spec §3.2:
+ * - Added `IF NOT EXISTS` on every CREATE so reboots don't fail.
+ * - PRAGMAs set outside the transaction (SQLite disallows PRAGMA in txn).
+ *
+ * Phase A additions (SEALED design 2026-04-25 §3.1 + §3.2) are reflected
+ * directly in the CREATE TABLE bodies so a fresh-install database lands on
+ * the new schema in one shot. Pre-existing databases (created under the
+ * Phase 1 schema) get the same columns added by `applyPhaseAColumnUpgrades`
+ * below, which uses `ALTER TABLE ADD COLUMN` guarded by `PRAGMA table_info`.
+ */
+export const CHAT_V2_MIGRATION_SQL = `
+CREATE TABLE IF NOT EXISTS chat_channels (
+  id                TEXT PRIMARY KEY,
+  agent_session     TEXT NOT NULL,
+  owner_user_id     TEXT NOT NULL,
+  name              TEXT NOT NULL,
+  purpose           TEXT,
+  created_at        INTEGER NOT NULL,
+  archived_at       INTEGER,
+  last_message_at   INTEGER,
+  -- Phase A (SEALED §3.1): channel-type discriminator. 'dm' preserves the
+  -- Phase 1 1:1 user↔agent contract; 'channel' is the Slack-like team
+  -- surface. Existing rows backfill to 'dm' via applyPhaseAColumnUpgrades.
+  type              TEXT NOT NULL DEFAULT 'dm' CHECK(type IN ('dm','channel')),
+  -- Phase A (SEALED §3.1): team workspace link. Required at the service
+  -- layer when type='channel'; null for type='dm'.
+  team_id           TEXT,
+  -- Phase A (SEALED §3.1): optional project link for project-scoped channels.
+  project_id        TEXT,
+  -- Phase A (SEALED §3.1): for type='dm', the resolved member-ID being DM'd
+  -- (distinct from agent_session which is the wire-level binding key).
+  target_member_id  TEXT
+);
+
+CREATE INDEX IF NOT EXISTS ix_channels_owner
+  ON chat_channels(owner_user_id, archived_at);
+
+-- Phase A indexes that reference the new columns (type, team_id, thread_id)
+-- live in CHAT_V2_PHASE_A_INDEX_SQL below — they must be created AFTER
+-- applyPhaseAColumnUpgrades runs so the columns exist on legacy DBs.
+
+CREATE TABLE IF NOT EXISTS chat_messages (
+  id           TEXT PRIMARY KEY,
+  channel_id   TEXT NOT NULL REFERENCES chat_channels(id) ON DELETE CASCADE,
+  seq          INTEGER NOT NULL,
+  sender_type  TEXT NOT NULL CHECK(sender_type IN ('user','agent','system')),
+  sender_id    TEXT NOT NULL,
+  content      TEXT NOT NULL,
+  content_type TEXT NOT NULL CHECK(content_type IN ('text','markdown','image_ref','system_note'))
+               DEFAULT 'markdown',
+  created_at   INTEGER NOT NULL,
+  metadata     TEXT,
+  -- Phase A (SEALED §3.2): JSON-encoded array of mention IDs (member or
+  -- team) referenced inline in the content field. Stored as a JSON string;
+  -- service layer treats null as []. Bounded at insert time; see types.ts.
+  mentions     TEXT,
+  -- Phase A (SEALED §3.2): optional Slack-style thread root. When set,
+  -- this message is a reply within the thread rooted at thread_id.
+  thread_id    TEXT
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS uq_messages_channel_seq
+  ON chat_messages(channel_id, seq);
+
+CREATE INDEX IF NOT EXISTS ix_messages_channel_created
+  ON chat_messages(channel_id, created_at DESC);
+
+-- Phase 1: partial unique index for clientMessageId-based idempotency (spec §4.4)
+CREATE UNIQUE INDEX IF NOT EXISTS uq_messages_client_id
+  ON chat_messages(channel_id, json_extract(metadata, '$.clientMessageId'))
+  WHERE json_extract(metadata, '$.clientMessageId') IS NOT NULL;
+
+CREATE TABLE IF NOT EXISTS chat_attachments (
+  id            TEXT PRIMARY KEY,
+  message_id    TEXT NOT NULL REFERENCES chat_messages(id) ON DELETE CASCADE,
+  kind          TEXT NOT NULL CHECK(kind IN ('image')),
+  mime_type     TEXT NOT NULL,
+  size_bytes    INTEGER NOT NULL,
+  local_path    TEXT NOT NULL,
+  original_name TEXT,
+  created_at    INTEGER NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS ix_attachments_message
+  ON chat_attachments(message_id);
+
+CREATE TABLE IF NOT EXISTS chat_offline_queue (
+  id            INTEGER PRIMARY KEY AUTOINCREMENT,
+  channel_id    TEXT NOT NULL,
+  agent_session TEXT NOT NULL,
+  message_id    TEXT NOT NULL REFERENCES chat_messages(id) ON DELETE CASCADE,
+  queued_at     INTEGER NOT NULL,
+  delivered_at  INTEGER,
+  attempts      INTEGER NOT NULL DEFAULT 0
+);
+
+CREATE INDEX IF NOT EXISTS ix_queue_pending
+  ON chat_offline_queue(agent_session, delivered_at)
+  WHERE delivered_at IS NULL;
+`;
+/**
+ * Phase A indexes that reference Phase A columns. Must run AFTER
+ * `applyPhaseAColumnUpgrades` adds those columns on pre-Phase-A databases —
+ * otherwise the partial-index `WHERE` clauses fail with "no such column".
+ *
+ * On a fresh database this runs after `CHAT_V2_MIGRATION_SQL` has already
+ * baked the columns into the CREATE TABLE bodies, so each step is a
+ * harmless no-op (`CREATE INDEX IF NOT EXISTS`).
+ */
+export const CHAT_V2_PHASE_A_INDEX_SQL = `
+-- Phase A (SEALED §3.1): the 1:1 agent-binding only applies to type='dm'
+-- channels. type='channel' rows have agent_session='' and many such rows
+-- can coexist for the same team; the partial index intentionally excludes
+-- them so the unique constraint doesn't fire on multi-agent channels.
+CREATE UNIQUE INDEX IF NOT EXISTS uq_channel_agent_dm_active
+  ON chat_channels(agent_session)
+  WHERE archived_at IS NULL AND type = 'dm';
+
+-- Phase A (SEALED §3.1): scoped lookup for "all channels in team T" and
+-- "project P channels". Indexes by team first because team-scoped reads
+-- are the dominant Phase B+ access pattern.
+CREATE INDEX IF NOT EXISTS ix_channels_team
+  ON chat_channels(team_id, archived_at)
+  WHERE team_id IS NOT NULL;
+
+-- Phase A (SEALED §3.2): thread-pane lookup. Filtered to non-null so the
+-- (smaller) index only covers actual threaded replies.
+CREATE INDEX IF NOT EXISTS ix_messages_thread
+  ON chat_messages(thread_id, seq)
+  WHERE thread_id IS NOT NULL;
+`;
+/** Phase A column additions for `chat_channels`. */
+const CHAT_CHANNELS_PHASE_A_COLUMNS = [
+    // NOT NULL DEFAULT 'dm' lets ALTER TABLE backfill existing rows in one shot.
+    { name: 'type', addClause: "type TEXT NOT NULL DEFAULT 'dm'" },
+    { name: 'team_id', addClause: 'team_id TEXT' },
+    { name: 'project_id', addClause: 'project_id TEXT' },
+    { name: 'target_member_id', addClause: 'target_member_id TEXT' },
+];
+/** Phase A column additions for `chat_messages`. */
+const CHAT_MESSAGES_PHASE_A_COLUMNS = [
+    { name: 'mentions', addClause: 'mentions TEXT' },
+    { name: 'thread_id', addClause: 'thread_id TEXT' },
+];
+/**
+ * Add a column to `table` if (and only if) it isn't already present.
+ *
+ * Uses `PRAGMA table_info(<table>)` to enumerate existing columns. SQLite
+ * does not have an `ADD COLUMN IF NOT EXISTS` form, so this guarded
+ * approach is the standard idempotent shape.
+ *
+ * @param db - The chat database handle
+ * @param table - Target table
+ * @param spec - Column to ensure
+ * @returns `true` if a column was added, `false` if it already existed
+ */
+function ensureColumn(db, table, spec) {
+    // PRAGMA cannot be parameterized; the table name is inlined. Callers
+    // supply only literal table names from the constants above — never
+    // user input — so SQL injection is not a concern here.
+    const cols = db.pragma(`table_info(${table})`);
+    if (cols.some((c) => c.name === spec.name)) {
+        return false;
+    }
+    db.exec(`ALTER TABLE ${table} ADD COLUMN ${spec.addClause}`);
+    return true;
+}
+/**
+ * Bring a pre-existing chat database up to Phase A's schema by adding
+ * any missing columns and the new indexes / dropping the superseded ones.
+ *
+ * Safe to run on a fresh database too — every step is no-op idempotent.
+ * Specifically:
+ *   - `ensureColumn` is a no-op when the column is already present (the
+ *     fresh-install case, since the columns are baked into the CREATE
+ *     TABLE in `CHAT_V2_MIGRATION_SQL`).
+ *   - `DROP INDEX IF EXISTS uq_channel_agent_active` removes the legacy
+ *     unconditional partial index so the new dm-scoped one isn't shadowed.
+ *     The DROP is metadata-only — no row data is affected.
+ *
+ * Exported (separately from `openChatDatabase`) so tests can simulate the
+ * pre-Phase-A → Phase A migration path explicitly.
+ *
+ * @param db - The chat database handle
+ * @returns A small report describing what changed (for logging)
+ */
+export function applyPhaseAColumnUpgrades(db) {
+    const channelsAdded = [];
+    for (const spec of CHAT_CHANNELS_PHASE_A_COLUMNS) {
+        if (ensureColumn(db, 'chat_channels', spec)) {
+            channelsAdded.push(spec.name);
+        }
+    }
+    const messagesAdded = [];
+    for (const spec of CHAT_MESSAGES_PHASE_A_COLUMNS) {
+        if (ensureColumn(db, 'chat_messages', spec)) {
+            messagesAdded.push(spec.name);
+        }
+    }
+    // Drop the legacy `uq_channel_agent_active` partial index — its constraint
+    // (`agent_session unique among archived_at IS NULL`) is too strict in the
+    // post-Phase-A world where multiple type='channel' rows legitimately share
+    // an empty agent_session. The replacement `uq_channel_agent_dm_active`
+    // (created below) carries the same semantics scoped to type='dm' rows only.
+    //
+    // The drop must happen BEFORE creating the new index — if the legacy
+    // index were left in place, an INSERT into a type='dm' row would still
+    // be checked by both indexes (same expression, different WHERE), which
+    // is harmless functionally but wastes write amplification.
+    const legacyIdx = db
+        .prepare(`SELECT name FROM sqlite_master
+       WHERE type = 'index' AND name = 'uq_channel_agent_active'`)
+        .get();
+    let legacyIndexDropped = false;
+    if (legacyIdx) {
+        db.exec('DROP INDEX IF EXISTS uq_channel_agent_active');
+        legacyIndexDropped = true;
+    }
+    // Now that all Phase A columns are guaranteed to exist, create the
+    // Phase A indexes that reference them. Idempotent — `CREATE INDEX IF NOT
+    // EXISTS` makes this a no-op on subsequent boots.
+    db.exec(CHAT_V2_PHASE_A_INDEX_SQL);
+    return { channelsAdded, messagesAdded, legacyIndexDropped };
+}
+/**
+ * Open (or create) the chat database, apply PRAGMAs, run the Phase 1
+ * migration idempotently, and run a boot-time integrity check.
+ *
+ * @param options - Opener options
+ * @returns A ready-to-use better-sqlite3 Database handle
+ *
+ * @example
+ * ```ts
+ * const db = openChatDatabase({ dbPath: '/tmp/chat.db' });
+ * // ... use db ...
+ * db.close();
+ * ```
+ */
+export function openChatDatabase(options) {
+    const logger = options.logger ??
+        LoggerService.getInstance().createComponentLogger('ChatV2Db');
+    if (!options.inMemory) {
+        const dir = path.dirname(options.dbPath);
+        if (dir && dir !== '.' && !existsSync(dir)) {
+            mkdirSync(dir, { recursive: true });
+        }
+    }
+    const Database = getBetterSqlite3();
+    const target = options.inMemory ? ':memory:' : options.dbPath;
+    const db = new Database(target);
+    // PRAGMAs — must be set outside any transaction (better-sqlite3 opens statements
+    // in autocommit mode by default, so a bare pragma() call is safe).
+    db.pragma('journal_mode = WAL');
+    db.pragma('foreign_keys = ON');
+    db.pragma('synchronous = NORMAL');
+    // Apply the Phase 1 migration idempotently. `exec` accepts multiple statements.
+    // For fresh databases this creates every table + index in one shot, including
+    // the Phase A columns baked into the CREATE TABLE bodies.
+    db.exec(CHAT_V2_MIGRATION_SQL);
+    // For pre-existing databases (created under Phase 1 schema), additively
+    // bring them up to Phase A: add missing columns and drop the superseded
+    // legacy `uq_channel_agent_active` index. Every step is no-op idempotent
+    // on a fresh DB.
+    const upgradeReport = applyPhaseAColumnUpgrades(db);
+    if (upgradeReport.channelsAdded.length > 0 ||
+        upgradeReport.messagesAdded.length > 0 ||
+        upgradeReport.legacyIndexDropped) {
+        logger.info('Chat DB Phase A schema upgrade applied', upgradeReport);
+    }
+    if (!options.skipIntegrityCheck) {
+        try {
+            const rows = db.pragma('integrity_check');
+            const first = rows[0]?.integrity_check;
+            if (first && first !== 'ok') {
+                logger.warn('Chat DB integrity check reported issues', { result: first });
+            }
+        }
+        catch (err) {
+            logger.warn('Chat DB integrity check threw — continuing without gating startup', {
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    logger.info('Chat DB opened', { path: target });
+    return db;
+}
+//# sourceMappingURL=chat-db.js.map