@cleocode/core 2026.4.11 → 2026.4.12

package/dist/store/conduit-sqlite.js

@@ -0,0 +1,570 @@
+/**
+ * SQLite store for conduit.db — project-tier messaging and agent-ref database.
+ *
+ * Creates and manages .cleo/conduit.db using node:sqlite directly.
+ * Applies the full conduit.db DDL (from spec §2.1) to bootstrap all
+ * project-local messaging tables and the project_agent_refs override table.
+ *
+ * Architecture (ADR-037):
+ *   conduit.db   — project-scoped (this module) — messaging, delivery, attachments,
+ *                  project_agent_refs
+ *   signaldock.db — global-scoped (T346) — agents, capabilities, cloud-sync tables
+ *
+ * CRUD accessors for project_agent_refs land in T353.
+ * Cross-DB join accessor changes land in T355.
+ * Migration executor from signaldock.db → conduit.db lands in T358.
+ *
+ * @task T344
+ * @epic T310
+ * @why ADR-037 splits single signaldock.db into project-tier conduit.db
+ *      (this module) and global-tier signaldock.db (T346). This module owns
+ *      the project-tier path helper, initializer, schema DDL, and health check.
+ * @what Path helper, database initializer, schema applier, health check, and
+ *       native DB accessor for project-local tables. No CRUD, no migrations.
+ */
+import { existsSync, mkdirSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+const _require = createRequire(import.meta.url);
+const { DatabaseSync } = _require('node:sqlite');
+/** Database file name within .cleo/ directory. */
+export const CONDUIT_DB_FILENAME = 'conduit.db';
+/** Schema version for conduit.db — updated when DDL changes. */
+export const CONDUIT_SCHEMA_VERSION = '2026.4.12';
+// ---------------------------------------------------------------------------
+// Singleton state
+// ---------------------------------------------------------------------------
+let _conduitNativeDb = null;
+let _conduitDbPath = null;
+// ---------------------------------------------------------------------------
+// DDL
+// ---------------------------------------------------------------------------
+/**
+ * Full conduit.db schema SQL.
+ *
+ * All tables use CREATE TABLE IF NOT EXISTS / CREATE INDEX IF NOT EXISTS /
+ * CREATE TRIGGER IF NOT EXISTS for idempotency. Carried over verbatim from
+ * the project-local tables in signaldock-sqlite.ts (migration
+ * `2026-03-28-000000_initial` + subsequent migrations), minus the global-
+ * identity tables (agents, capabilities, skills, agent_capabilities,
+ * agent_skills, agent_connections, users, organization, accounts, sessions,
+ * verifications, claim_codes, org_agent_keys) which move to global-tier
+ * signaldock.db (T346).
+ *
+ * Additional new table: project_agent_refs (ADR-037 §3, Q6=A).
+ *
+ * NOTE: The `connections` table from the original migration is a cross-agent
+ * social graph that references `agents(id)` — it is a global-identity
+ * concern and stays with signaldock.db (T346). It is NOT included here.
+ */
+const CONDUIT_SCHEMA_SQL = `
+-- -------------------------------------------------------------------------
+-- Project-scoped conversations (LocalTransport DM threads).
+-- -------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS conversations (
+    id TEXT PRIMARY KEY,
+    participants TEXT NOT NULL,
+    visibility TEXT NOT NULL DEFAULT 'private',
+    message_count INTEGER NOT NULL DEFAULT 0,
+    last_message_at INTEGER,
+    created_at INTEGER NOT NULL,
+    updated_at INTEGER NOT NULL
+);
+
+-- -------------------------------------------------------------------------
+-- Project-scoped agent-to-agent messages (LocalTransport content).
+-- -------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS messages (
+    id TEXT PRIMARY KEY,
+    conversation_id TEXT NOT NULL REFERENCES conversations(id),
+    from_agent_id TEXT NOT NULL,
+    to_agent_id TEXT NOT NULL,
+    content TEXT NOT NULL,
+    content_type TEXT NOT NULL DEFAULT 'text',
+    status TEXT NOT NULL DEFAULT 'pending',
+    attachments TEXT NOT NULL DEFAULT '[]',
+    group_id TEXT,
+    metadata TEXT DEFAULT '{}',
+    reply_to TEXT,
+    created_at INTEGER NOT NULL,
+    delivered_at INTEGER,
+    read_at INTEGER
+);
+CREATE INDEX IF NOT EXISTS messages_conversation_idx ON messages(conversation_id);
+CREATE INDEX IF NOT EXISTS messages_from_agent_idx ON messages(from_agent_id);
+CREATE INDEX IF NOT EXISTS messages_to_agent_idx ON messages(to_agent_id);
+CREATE INDEX IF NOT EXISTS messages_created_at_idx ON messages(created_at);
+CREATE INDEX IF NOT EXISTS idx_messages_group_id ON messages(group_id) WHERE group_id IS NOT NULL;
+CREATE INDEX IF NOT EXISTS idx_messages_reply_to ON messages(reply_to) WHERE reply_to IS NOT NULL;
+
+-- -------------------------------------------------------------------------
+-- FTS5 virtual table for full-text search on message content.
+-- NOTE: Must be migrated using VACUUM INTO, not DDL-only copy, to preserve
+-- triggers. The INSERT INTO messages_fts(messages_fts) VALUES('rebuild')
+-- is idempotent — safe to run on every open.
+-- -------------------------------------------------------------------------
+CREATE VIRTUAL TABLE IF NOT EXISTS messages_fts
+    USING fts5(content, from_agent_id, content='messages', content_rowid='rowid');
+INSERT INTO messages_fts(messages_fts) VALUES('rebuild');
+CREATE TRIGGER IF NOT EXISTS messages_ai AFTER INSERT ON messages BEGIN
+    INSERT INTO messages_fts(rowid, content, from_agent_id)
+        VALUES (new.rowid, new.content, new.from_agent_id);
+END;
+CREATE TRIGGER IF NOT EXISTS messages_ad AFTER DELETE ON messages BEGIN
+    INSERT INTO messages_fts(messages_fts, rowid, content, from_agent_id)
+        VALUES('delete', old.rowid, old.content, old.from_agent_id);
+END;
+CREATE TRIGGER IF NOT EXISTS messages_au AFTER UPDATE ON messages BEGIN
+    INSERT INTO messages_fts(messages_fts, rowid, content, from_agent_id)
+        VALUES('delete', old.rowid, old.content, old.from_agent_id);
+    INSERT INTO messages_fts(rowid, content, from_agent_id)
+        VALUES (new.rowid, new.content, new.from_agent_id);
+END;
+
+-- -------------------------------------------------------------------------
+-- Async delivery queue for deferred message dispatch.
+-- -------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS delivery_jobs (
+    id TEXT PRIMARY KEY,
+    message_id TEXT NOT NULL,
+    payload TEXT NOT NULL,
+    status TEXT NOT NULL DEFAULT 'pending',
+    attempts INTEGER NOT NULL DEFAULT 0,
+    max_attempts INTEGER NOT NULL DEFAULT 6,
+    next_attempt_at INTEGER NOT NULL,
+    last_error TEXT,
+    created_at INTEGER NOT NULL,
+    updated_at INTEGER NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_delivery_jobs_status ON delivery_jobs(status, next_attempt_at);
+
+-- -------------------------------------------------------------------------
+-- Dead-letter queue for messages that exceeded max delivery attempts.
+-- -------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS dead_letters (
+    id TEXT PRIMARY KEY,
+    message_id TEXT NOT NULL,
+    job_id TEXT NOT NULL,
+    reason TEXT NOT NULL,
+    attempts INTEGER NOT NULL,
+    created_at INTEGER NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_dead_letters_message ON dead_letters(message_id);
+
+-- -------------------------------------------------------------------------
+-- Pinned messages within a conversation.
+-- -------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS message_pins (
+    id TEXT PRIMARY KEY,
+    message_id TEXT NOT NULL,
+    conversation_id TEXT NOT NULL,
+    pinned_by TEXT NOT NULL,
+    note TEXT,
+    created_at INTEGER NOT NULL,
+    UNIQUE(message_id, pinned_by)
+);
+CREATE INDEX IF NOT EXISTS idx_pins_conversation ON message_pins(conversation_id);
+CREATE INDEX IF NOT EXISTS idx_pins_agent ON message_pins(pinned_by);
+
+-- -------------------------------------------------------------------------
+-- File/blob attachments associated with messages.
+-- -------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS attachments (
+    slug TEXT PRIMARY KEY,
+    conversation_id TEXT NOT NULL,
+    from_agent_id TEXT NOT NULL,
+    content BLOB NOT NULL,
+    original_size INTEGER NOT NULL,
+    compressed_size INTEGER NOT NULL,
+    content_hash TEXT NOT NULL,
+    format TEXT NOT NULL DEFAULT 'text',
+    title TEXT,
+    tokens INTEGER NOT NULL DEFAULT 0,
+    expires_at INTEGER NOT NULL DEFAULT 0,
+    storage_key TEXT,
+    mode TEXT NOT NULL DEFAULT 'draft',
+    version_count INTEGER NOT NULL DEFAULT 1,
+    current_version INTEGER NOT NULL DEFAULT 1,
+    created_at INTEGER NOT NULL
+);
+CREATE INDEX IF NOT EXISTS attachments_conversation_idx ON attachments(conversation_id);
+CREATE INDEX IF NOT EXISTS attachments_agent_idx ON attachments(from_agent_id);
+
+-- -------------------------------------------------------------------------
+-- Version history for attachments (collaborative editing).
+-- -------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS attachment_versions (
+    id TEXT PRIMARY KEY,
+    slug TEXT NOT NULL REFERENCES attachments(slug) ON DELETE CASCADE,
+    version_number INTEGER NOT NULL,
+    author_agent_id TEXT NOT NULL,
+    change_type TEXT NOT NULL DEFAULT 'patch',
+    patch_text TEXT,
+    storage_key TEXT NOT NULL,
+    content_hash TEXT NOT NULL,
+    original_size INTEGER NOT NULL,
+    compressed_size INTEGER NOT NULL,
+    tokens INTEGER NOT NULL,
+    change_summary TEXT,
+    sections_modified TEXT NOT NULL DEFAULT '[]',
+    tokens_added INTEGER NOT NULL DEFAULT 0,
+    tokens_removed INTEGER NOT NULL DEFAULT 0,
+    created_at INTEGER NOT NULL,
+    UNIQUE(slug, version_number)
+);
+CREATE INDEX IF NOT EXISTS idx_attachment_versions_slug ON attachment_versions(slug);
+CREATE INDEX IF NOT EXISTS idx_attachment_versions_author ON attachment_versions(author_agent_id);
+
+-- -------------------------------------------------------------------------
+-- Approval records for attachment content review.
+-- -------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS attachment_approvals (
+    id TEXT PRIMARY KEY,
+    slug TEXT NOT NULL REFERENCES attachments(slug) ON DELETE CASCADE,
+    reviewer_agent_id TEXT NOT NULL,
+    status TEXT NOT NULL DEFAULT 'pending',
+    comment TEXT,
+    version_reviewed INTEGER NOT NULL,
+    created_at INTEGER NOT NULL,
+    updated_at INTEGER NOT NULL,
+    UNIQUE(slug, reviewer_agent_id)
+);
+CREATE INDEX IF NOT EXISTS idx_attachment_approvals_slug ON attachment_approvals(slug);
+
+-- -------------------------------------------------------------------------
+-- Contributor statistics per attachment (who edited, how much).
+-- -------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS attachment_contributors (
+    slug TEXT NOT NULL REFERENCES attachments(slug) ON DELETE CASCADE,
+    agent_id TEXT NOT NULL,
+    version_count INTEGER NOT NULL DEFAULT 0,
+    total_tokens_added INTEGER NOT NULL DEFAULT 0,
+    total_tokens_removed INTEGER NOT NULL DEFAULT 0,
+    first_contribution_at INTEGER NOT NULL,
+    last_contribution_at INTEGER NOT NULL,
+    PRIMARY KEY (slug, agent_id)
+);
+
+-- -------------------------------------------------------------------------
+-- NEW: Per-project agent reference overrides (ADR-037 §3, Q6=A).
+-- agent_id is a SOFT FK to global signaldock.db:agents.agent_id.
+-- Cross-DB FK enforcement is not possible in SQLite; the accessor layer
+-- (T355) validates on every cross-DB join.
+-- -------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS project_agent_refs (
+    agent_id TEXT PRIMARY KEY,
+    attached_at TEXT NOT NULL,
+    role TEXT,
+    capabilities_override TEXT,
+    last_used_at TEXT,
+    enabled INTEGER NOT NULL DEFAULT 1
+);
+-- Partial index: covers the dominant query path (list enabled agents).
+CREATE INDEX IF NOT EXISTS idx_project_agent_refs_enabled
+    ON project_agent_refs(enabled) WHERE enabled = 1;
+
+-- -------------------------------------------------------------------------
+-- Schema tracking tables (mirrors _signaldock_meta / _signaldock_migrations).
+-- -------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS _conduit_meta (
+    key TEXT PRIMARY KEY,
+    value TEXT NOT NULL,
+    updated_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now'))
+);
+CREATE TABLE IF NOT EXISTS _conduit_migrations (
+    name TEXT PRIMARY KEY,
+    applied_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now'))
+);
+`;
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Returns the project-tier conduit.db path.
+ *
+ * Always resolves to `<projectRoot>/.cleo/conduit.db`. The caller is
+ * responsible for supplying the absolute project root (e.g. via
+ * `getProjectRoot()` from `../paths.js`).
+ *
+ * @task T344
+ * @epic T310
+ * @param projectRoot - Absolute path to the project root directory.
+ * @returns Absolute path to `<projectRoot>/.cleo/conduit.db`.
+ */
+export function getConduitDbPath(projectRoot) {
+    return join(projectRoot, '.cleo', CONDUIT_DB_FILENAME);
+}
+/**
+ * Applies the conduit.db schema idempotently using CREATE TABLE IF NOT EXISTS.
+ *
+ * Exposed for the migration executor (T358) which needs to apply the schema
+ * to a newly created conduit.db during the signaldock.db → conduit.db
+ * migration. Also called internally by `ensureConduitDb` on every open.
+ *
+ * @task T344
+ * @epic T310
+ * @param db - An open node:sqlite DatabaseSync instance.
+ */
+export function applyConduitSchema(db) {
+    db.exec(CONDUIT_SCHEMA_SQL);
+}
+/**
+ * Opens or creates conduit.db for the given project root.
+ *
+ * On first call for a given projectRoot:
+ *   1. Creates `<projectRoot>/.cleo/` directory if missing.
+ *   2. Opens (or creates) the SQLite file.
+ *   3. Sets WAL mode and enables foreign keys.
+ *   4. Applies all DDL via `applyConduitSchema` (idempotent).
+ *   5. Records `schema_version` in `_conduit_meta`.
+ *   6. Records the initial migration in `_conduit_migrations`.
+ *   7. Stores the open handle in the module singleton.
+ *
+ * On subsequent calls the existing singleton is returned immediately if the
+ * resolved path matches; otherwise the previous handle is closed and a new
+ * one is opened (test-isolation safety).
+ *
+ * Caller MUST call `closeConduitDb()` when done to release the handle.
+ *
+ * @task T344
+ * @epic T310
+ * @param projectRoot - Absolute path to the project root directory.
+ * @returns Object with `action` (`'created'` | `'exists'`) and `path`.
+ */
+export function ensureConduitDb(projectRoot) {
+    const dbPath = getConduitDbPath(projectRoot);
+    // If singleton already open at the same path, skip re-initialization.
+    if (_conduitNativeDb && _conduitDbPath === dbPath) {
+        return { action: 'exists', path: dbPath };
+    }
+    // Close any stale singleton pointing at a different path (e.g. between tests).
+    if (_conduitNativeDb) {
+        closeConduitDb();
+    }
+    const alreadyExists = existsSync(dbPath);
+    // Ensure parent .cleo/ directory exists.
+    mkdirSync(dirname(dbPath), { recursive: true });
+    const db = new DatabaseSync(dbPath);
+    db.exec('PRAGMA journal_mode = WAL');
+    db.exec('PRAGMA busy_timeout = 5000');
+    db.exec('PRAGMA synchronous = NORMAL');
+    db.exec('PRAGMA foreign_keys = ON');
+    db.exec('PRAGMA cache_size = -64000'); // 64 MB
+    // Check whether the schema sentinel table already exists before applying DDL.
+    const hasSchema = (() => {
+        try {
+            const result = db
+                .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='conversations'")
+                .get();
+            return !!result;
+        }
+        catch {
+            return false;
+        }
+    })();
+    // Apply schema (idempotent — all statements use IF NOT EXISTS).
+    applyConduitSchema(db);
+    // Record schema version and initial migration.
+    db.exec(`INSERT OR REPLACE INTO _conduit_meta (key, value, updated_at)
+     VALUES ('schema_version', '${CONDUIT_SCHEMA_VERSION}', strftime('%s', 'now'))`);
+    db.prepare(`INSERT OR IGNORE INTO _conduit_migrations (name, applied_at)
+     VALUES (?, strftime('%s', 'now'))`).run('2026-04-12-000000_initial_conduit');
+    _conduitNativeDb = db;
+    _conduitDbPath = dbPath;
+    return {
+        action: alreadyExists && hasSchema ? 'exists' : 'created',
+        path: dbPath,
+    };
+}
+/**
+ * Returns the live node:sqlite DatabaseSync handle for conduit.db.
+ *
+ * Returns `null` if `ensureConduitDb` has not been called yet for this
+ * process, or if `closeConduitDb` has been called since the last open.
+ *
+ * @task T344
+ * @epic T310
+ * @returns The open DatabaseSync instance, or `null` if not initialized.
+ */
+export function getConduitNativeDb() {
+    return _conduitNativeDb;
+}
+/**
+ * Closes the conduit.db connection and resets the module singleton.
+ *
+ * Safe to call multiple times. No-op if the database is already closed.
+ *
+ * @task T344
+ * @epic T310
+ */
+export function closeConduitDb() {
+    if (_conduitNativeDb) {
+        try {
+            if (_conduitNativeDb.isOpen) {
+                _conduitNativeDb.close();
+            }
+        }
+        catch {
+            // Ignore close errors — the handle is being discarded regardless.
+        }
+        _conduitNativeDb = null;
+    }
+    _conduitDbPath = null;
+}
+// ---------------------------------------------------------------------------
+// project_agent_refs CRUD accessors (T353)
+// ---------------------------------------------------------------------------
+/**
+ * Attaches an agent to the current project. If a row exists with enabled=0,
+ * re-enables it (update attached_at timestamp). If a row exists with enabled=1,
+ * no-op. Inserts a new row otherwise.
+ *
+ * @param db - conduit.db handle (from ensureConduitDb).
+ * @param agentId - Global signaldock.db:agents.id (soft FK, not validated here).
+ * @param opts - Optional role and capabilities override.
+ * @task T353
+ * @epic T310
+ */
+export function attachAgentToProject(db, agentId, opts) {
+    const now = new Date().toISOString();
+    db.prepare(`INSERT INTO project_agent_refs (agent_id, attached_at, role, capabilities_override, last_used_at, enabled)
+     VALUES (?, ?, ?, ?, NULL, 1)
+     ON CONFLICT(agent_id) DO UPDATE SET
+       enabled = 1,
+       attached_at = CASE WHEN project_agent_refs.enabled = 0 THEN excluded.attached_at ELSE project_agent_refs.attached_at END,
+       role = excluded.role,
+       capabilities_override = excluded.capabilities_override`).run(agentId, now, opts?.role ?? null, opts?.capabilitiesOverride ?? null);
+}
+/**
+ * Detaches an agent from the current project by setting enabled=0.
+ * Does NOT delete the row (preserves attachment history for audit).
+ *
+ * @param db - conduit.db handle (from ensureConduitDb).
+ * @param agentId - Agent ID to detach.
+ * @task T353
+ * @epic T310
+ */
+export function detachAgentFromProject(db, agentId) {
+    db.prepare(`UPDATE project_agent_refs SET enabled = 0 WHERE agent_id = ?`).run(agentId);
+}
+/**
+ * Lists project_agent_refs rows. By default returns only enabled=1 rows.
+ * Pass enabledOnly=false to return all rows regardless of enabled state.
+ *
+ * @param db - conduit.db handle (from ensureConduitDb).
+ * @param opts - Filter options. Defaults to `{ enabledOnly: true }`.
+ * @returns Array of ProjectAgentRef rows ordered by attached_at DESC.
+ * @task T353
+ * @epic T310
+ */
+export function listProjectAgentRefs(db, opts) {
+    const enabledOnly = opts?.enabledOnly ?? true;
+    const sql = enabledOnly
+        ? `SELECT agent_id, attached_at, role, capabilities_override, last_used_at, enabled
+       FROM project_agent_refs WHERE enabled = 1
+       ORDER BY attached_at DESC`
+        : `SELECT agent_id, attached_at, role, capabilities_override, last_used_at, enabled
+       FROM project_agent_refs
+       ORDER BY attached_at DESC`;
+    const rows = db.prepare(sql).all();
+    return rows.map((r) => ({
+        agentId: r.agent_id,
+        attachedAt: r.attached_at,
+        role: r.role,
+        capabilitiesOverride: r.capabilities_override,
+        lastUsedAt: r.last_used_at,
+        enabled: r.enabled,
+    }));
+}
+/**
+ * Returns a single project_agent_refs row by agentId, or null if not found.
+ *
+ * @param db - conduit.db handle (from ensureConduitDb).
+ * @param agentId - Agent ID to look up.
+ * @returns The ProjectAgentRef row, or null if the agent is not attached.
+ * @task T353
+ * @epic T310
+ */
+export function getProjectAgentRef(db, agentId) {
+    const row = db
+        .prepare(`SELECT agent_id, attached_at, role, capabilities_override, last_used_at, enabled
+       FROM project_agent_refs WHERE agent_id = ?`)
+        .get(agentId);
+    if (!row)
+        return null;
+    return {
+        agentId: row.agent_id,
+        attachedAt: row.attached_at,
+        role: row.role,
+        capabilitiesOverride: row.capabilities_override,
+        lastUsedAt: row.last_used_at,
+        enabled: row.enabled,
+    };
+}
+/**
+ * Updates the last_used_at timestamp for an agent to now.
+ * No-op if the agent_id does not exist in project_agent_refs.
+ *
+ * @param db - conduit.db handle (from ensureConduitDb).
+ * @param agentId - Agent ID to update.
+ * @task T353
+ * @epic T310
+ */
+export function updateProjectAgentLastUsed(db, agentId) {
+    db.prepare(`UPDATE project_agent_refs SET last_used_at = ? WHERE agent_id = ?`).run(new Date().toISOString(), agentId);
+}
+/**
+ * Checks conduit.db health — table count, WAL mode, schema version, and
+ * foreign keys status.
+ *
+ * Used by `cleo doctor` to verify conduit.db integrity. Does NOT require
+ * `ensureConduitDb` to have been called; opens and closes the DB internally.
+ *
+ * @task T344
+ * @epic T310
+ * @param projectRoot - Absolute path to the project root directory.
+ * @returns Health report object. `exists: false` when conduit.db is absent.
+ */
+export function checkConduitDbHealth(projectRoot) {
+    const dbPath = getConduitDbPath(projectRoot);
+    if (!existsSync(dbPath)) {
+        return {
+            exists: false,
+            path: dbPath,
+            tableCount: 0,
+            walMode: false,
+            schemaVersion: null,
+            foreignKeysEnabled: false,
+        };
+    }
+    const db = new DatabaseSync(dbPath);
+    try {
+        const tables = db
+            .prepare("SELECT COUNT(*) as count FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'")
+            .get();
+        const journalMode = db.prepare('PRAGMA journal_mode').get();
+        const fkEnabled = db.prepare('PRAGMA foreign_keys').get();
+        let schemaVersion = null;
+        try {
+            const meta = db
+                .prepare("SELECT value FROM _conduit_meta WHERE key = 'schema_version'")
+                .get();
+            schemaVersion = meta?.value ?? null;
+        }
+        catch {
+            // _conduit_meta may not exist on a partially-initialized DB.
+        }
+        return {
+            exists: true,
+            path: dbPath,
+            tableCount: tables.count,
+            walMode: journalMode.journal_mode === 'wal',
+            schemaVersion,
+            foreignKeysEnabled: fkEnabled.foreign_keys === 1,
+        };
+    }
+    finally {
+        db.close();
+    }
+}
+//# sourceMappingURL=conduit-sqlite.js.map

package/dist/store/conduit-sqlite.js.map

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

package/dist/store/global-salt.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Global-salt subsystem for the CLEO API key KDF.
+ *
+ * @task T348
+ * @epic T310
+ * @why ADR-037 §5 — API key KDF uses machine-key + global-salt + agentId.
+ *      global-salt must persist across process restarts but is machine-local.
+ * @what Atomic first-run generation, memoized read, permission/size validation.
+ */
+/** Filename for the global salt file under CLEO home. */
+export declare const GLOBAL_SALT_FILENAME = "global-salt";
+/** Required size of the global salt in bytes. */
+export declare const GLOBAL_SALT_SIZE = 32;
+/**
+ * Returns the absolute path to the global-salt file.
+ *
+ * @returns Absolute path: `{cleoHome}/global-salt`
+ *
+ * @task T348
+ * @epic T310
+ *
+ * @example
+ * ```typescript
+ * const saltPath = getGlobalSaltPath();
+ * // Linux: "/home/user/.local/share/cleo/global-salt"
+ * ```
+ */
+export declare function getGlobalSaltPath(): string;
+/**
+ * Returns the 32-byte global salt. Generates and persists atomically on first
+ * call when the file does not exist. Subsequent calls return the memoized value.
+ *
+ * Never overwrites an existing salt — doing so would invalidate every stored
+ * API key derived from it.
+ *
+ * @returns A 32-byte Buffer containing the global salt
+ * @throws {Error} If the salt file exists with wrong size or wrong permissions
+ *
+ * @task T348
+ * @epic T310
+ *
+ * @example
+ * ```typescript
+ * const salt = getGlobalSalt(); // Buffer(32) [...]
+ * ```
+ */
+export declare function getGlobalSalt(): Buffer;
+/**
+ * Runtime validation helper for startup integrity checks.
+ *
+ * Throws if the salt file exists but is malformed (wrong size or permissions).
+ * Safe to call when the file does not yet exist — returns silently in that case
+ * because first-run generation is handled lazily by `getGlobalSalt()`.
+ *
+ * @throws {Error} If the salt file exists with wrong size or wrong permissions
+ *
+ * @task T348
+ * @epic T310
+ *
+ * @example
+ * ```typescript
+ * // Called at process startup to catch accidental salt corruption early
+ * validateGlobalSalt();
+ * ```
+ */
+export declare function validateGlobalSalt(): void;
+/**
+ * Clears the in-process memoization cache so tests can exercise the
+ * first-call generation path independently.
+ *
+ * @internal TEST ONLY — do NOT export through internal.ts or re-export
+ * from any public barrel. This symbol must never appear in production call paths.
+ *
+ * @task T348
+ * @epic T310
+ */
+export declare function __clearGlobalSaltCache(): void;
+//# sourceMappingURL=global-salt.d.ts.map

package/dist/store/global-salt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"global-salt.d.ts","sourceRoot":"","sources":["../../src/store/global-salt.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH,yDAAyD;AACzD,eAAO,MAAM,oBAAoB,gBAAgB,CAAC;AAElD,iDAAiD;AACjD,eAAO,MAAM,gBAAgB,KAAK,CAAC;AAWnC;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAkDtC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAwBzC;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAE7C"}