@cgh567/agent 2.4.2 → 2.4.4

package/lib/hbo-core-store.ts

@@ -0,0 +1,979 @@
+/**
+ * hbo-core-store.ts
+ * Unified SQLite store for HBO (Helios Business Operations) core domain data.
+ *
+ * Covers: tasks, approvals, budget policies, cost events, business agents,
+ *         OKRs, leads, CRM contacts, accounts, and opportunities.
+ *
+ * Storage engine: node:sqlite (DatabaseSync) when available (Node ≥ 22.13
+ * without flags, or Node ≥ 22.5 with --experimental-sqlite), otherwise
+ * better-sqlite3 (Node ≥ 16, requires native compilation via node-gyp but
+ * is already a declared dependency).
+ *
+ * Runs natively on Windows, macOS, and Linux for all users regardless of
+ * Node version.
+ *
+ * Data model: Memgraph is primary. This store is the fallback when Memgraph
+ * is unavailable. Writes go to SQLite first (authoritative on Memgraph failure),
+ * then fire-and-forget to Memgraph as a projection.
+ *
+ * Pattern:
+ *   - Lazy singleton DB open via getDb()
+ *   - Schema initialised once on first open (initSchema)
+ *   - All writes use INSERT OR REPLACE for idempotency
+ *   - All records are stored with a data_json column for full fidelity
+ *   - Read helpers parse data_json and merge with top-level indexed columns
+ *   - No hardcoded company IDs anywhere
+ */
+import * as path from 'path';
+import * as os from 'os';
+import { mkdirSync } from 'fs';
+
+// ---------------------------------------------------------------------------
+// Engine detection — node:sqlite (Node 22+) preferred, better-sqlite3 fallback
+// ---------------------------------------------------------------------------
+
+// _engine tracks which SQLite library is in use so initSchema can apply the
+// correct WAL pragma syntax:
+//   node:sqlite  → db.exec('PRAGMA journal_mode = WAL')
+//   better-sqlite3 → db.pragma('journal_mode = WAL')
+let _engine: 'node-sqlite' | 'better-sqlite3' | null = null;
+
+function _openDatabase(dbPath: string): any {
+  // Attempt 1: node:sqlite built-in (Node >= 22.13 no flags needed; Node >= 22.5 with --experimental-sqlite)
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { DatabaseSync } = require('node:sqlite');
+    const db = new DatabaseSync(dbPath);
+    _engine = 'node-sqlite';
+    return db;
+  } catch (_nodeSqliteErr) {
+    // node:sqlite unavailable (Node < 22.13 without flag, or Node < 22.5)
+  }
+
+  // Attempt 2: better-sqlite3 — synchronous, compiled native module, Node ≥ 16
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const BetterSqlite3 = require('better-sqlite3');
+    const db = new BetterSqlite3(dbPath);
+    _engine = 'better-sqlite3';
+    return db;
+  } catch (_betterSqliteErr) {
+    // better-sqlite3 unavailable (native build failed or not installed)
+  }
+
+  throw new Error(
+    '[hbo-core-store] No SQLite engine available. ' +
+    'Requires Node >= 22.13 (no flags) or Node >= 22.5 with --experimental-sqlite, ' +
+    'OR better-sqlite3 installed. Run: npm install better-sqlite3'
+  );
+}
+
+// ---------------------------------------------------------------------------
+// DB singleton
+// ---------------------------------------------------------------------------
+
+let _db: any | null = null;
+
+function getDb(): any {
+  if (_db) return _db;
+
+  const dbPath = path.join(
+    process.env.HELIOS_ROOT ?? path.join(os.homedir(), 'helios-agent'),
+    'data',
+    'hbo-core.db',
+  );
+
+  mkdirSync(path.join(dbPath, '..'), { recursive: true });
+
+  _db = _openDatabase(dbPath);
+
+  // WAL mode for concurrent readers + single writer.
+  // node:sqlite uses .exec('PRAGMA ...'); better-sqlite3 uses .pragma('...')
+  if (_engine === 'better-sqlite3') {
+    _db.pragma('journal_mode = WAL');
+    _db.pragma('foreign_keys = ON');
+  } else {
+    _db.exec('PRAGMA journal_mode = WAL');
+    _db.exec('PRAGMA foreign_keys = ON');
+  }
+
+  initSchema(_db);
+  return _db;
+}
+
+// ---------------------------------------------------------------------------
+// Schema
+// ---------------------------------------------------------------------------
+
+function initSchema(db: any): void {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS tasks (
+      id                   TEXT    PRIMARY KEY,
+      company_id           TEXT    NOT NULL,
+      title                TEXT,
+      status               TEXT,
+      assignee_agent_id    TEXT,
+      goal_id              TEXT,
+      origin_kind          TEXT,
+      helios_issue_id      TEXT,
+      execution_locked_at  INTEGER,
+      created_at           INTEGER,
+      updated_at           INTEGER,
+      data_json            TEXT
+    );
+    CREATE INDEX IF NOT EXISTS idx_tasks_company_status ON tasks(company_id, status);
+    CREATE INDEX IF NOT EXISTS idx_tasks_assignee       ON tasks(assignee_agent_id, company_id);
+
+    CREATE TABLE IF NOT EXISTS approvals (
+      id            TEXT    PRIMARY KEY,
+      company_id    TEXT    NOT NULL,
+      type          TEXT,
+      status        TEXT,
+      strategy_id   TEXT,
+      requested_by  TEXT,
+      created_at    INTEGER,
+      updated_at    INTEGER,
+      data_json     TEXT
+    );
+    CREATE INDEX IF NOT EXISTS idx_approvals_company_status ON approvals(company_id, status);
+
+    CREATE TABLE IF NOT EXISTS budget_policies (
+      id            TEXT    PRIMARY KEY,
+      company_id    TEXT    NOT NULL,
+      agent_id      TEXT,
+      spent_cents   INTEGER DEFAULT 0,
+      percent_used  REAL    DEFAULT 0,
+      updated_at    INTEGER,
+      data_json     TEXT
+    );
+    CREATE INDEX IF NOT EXISTS idx_budget_company_agent ON budget_policies(company_id, agent_id);
+
+    CREATE TABLE IF NOT EXISTS cost_events (
+      id          TEXT    PRIMARY KEY,
+      company_id  TEXT    NOT NULL,
+      agent_id    TEXT,
+      feature     TEXT,
+      model       TEXT,
+      amount_usd  REAL,
+      created_at  INTEGER,
+      data_json   TEXT
+    );
+    CREATE INDEX IF NOT EXISTS idx_cost_company ON cost_events(company_id, created_at);
+
+    CREATE TABLE IF NOT EXISTS business_agents (
+      id               TEXT    PRIMARY KEY,
+      company_id       TEXT    NOT NULL,
+      role             TEXT,
+      status           TEXT,
+      current_task_id  TEXT,
+      skill            TEXT,
+      adapter          TEXT,
+      updated_at       INTEGER,
+      data_json        TEXT
+    );
+    CREATE INDEX IF NOT EXISTS idx_agents_company_status ON business_agents(company_id, status);
+
+    CREATE TABLE IF NOT EXISTS okrs (
+      id          TEXT    PRIMARY KEY,
+      company_id  TEXT    NOT NULL,
+      type        TEXT,
+      status      TEXT,
+      title       TEXT,
+      updated_at  INTEGER,
+      data_json   TEXT
+    );
+    CREATE INDEX IF NOT EXISTS idx_okrs_company_type ON okrs(company_id, type, status);
+
+    CREATE TABLE IF NOT EXISTS goals (
+      id          TEXT    PRIMARY KEY,
+      company_id  TEXT    NOT NULL,
+      title       TEXT,
+      description TEXT,
+      level       TEXT,
+      status      TEXT,
+      parent_id   TEXT,
+      created_at  INTEGER,
+      updated_at  INTEGER,
+      data_json   TEXT
+    );
+    CREATE INDEX IF NOT EXISTS idx_goals_company_status ON goals(company_id, status);
+    CREATE INDEX IF NOT EXISTS idx_goals_parent ON goals(company_id, parent_id);
+
+    CREATE TABLE IF NOT EXISTS leads (
+      id          TEXT    PRIMARY KEY,
+      company_id  TEXT    NOT NULL,
+      status      TEXT,
+      email       TEXT,
+      name        TEXT,
+      updated_at  INTEGER,
+      data_json   TEXT
+    );
+    CREATE INDEX IF NOT EXISTS idx_leads_company_status ON leads(company_id, status);
+
+    CREATE TABLE IF NOT EXISTS crm_contacts (
+      id          TEXT    PRIMARY KEY,
+      company_id  TEXT    NOT NULL,
+      email       TEXT,
+      name        TEXT,
+      updated_at  INTEGER,
+      data_json   TEXT
+    );
+    CREATE INDEX IF NOT EXISTS idx_crm_company ON crm_contacts(company_id);
+
+    CREATE TABLE IF NOT EXISTS accounts (
+      id          TEXT    PRIMARY KEY,
+      company_id  TEXT    NOT NULL,
+      name        TEXT,
+      updated_at  INTEGER,
+      data_json   TEXT
+    );
+
+    CREATE TABLE IF NOT EXISTS opportunities (
+      id          TEXT    PRIMARY KEY,
+      company_id  TEXT    NOT NULL,
+      title       TEXT,
+      status      TEXT,
+      updated_at  INTEGER,
+      data_json   TEXT
+    );
+
+    CREATE TABLE IF NOT EXISTS helios_projects (
+      id          TEXT    PRIMARY KEY,
+      company_id  TEXT    NOT NULL,
+      name        TEXT,
+      pillar_id   TEXT,
+      goal_id     TEXT,
+      status      TEXT,
+      phase       TEXT,
+      created_at  INTEGER,
+      updated_at  INTEGER,
+      data_json   TEXT
+    );
+    CREATE INDEX IF NOT EXISTS idx_helios_projects_company ON helios_projects(company_id, status);
+
+    CREATE TABLE IF NOT EXISTS project_documents (
+      id            TEXT    PRIMARY KEY,
+      project_id    TEXT    NOT NULL,
+      company_id    TEXT,
+      purpose       TEXT,
+      approach      TEXT,
+      intent_anchor TEXT,
+      success_criteria TEXT,
+      exclusions    TEXT,
+      content       TEXT,
+      version       INTEGER DEFAULT 1,
+      updated_at    INTEGER,
+      data_json     TEXT
+    );
+    CREATE INDEX IF NOT EXISTS idx_project_docs_project ON project_documents(project_id);
+
+    CREATE TABLE IF NOT EXISTS routines (
+      id                  TEXT    PRIMARY KEY,
+      company_id          TEXT    NOT NULL,
+      agent_id            TEXT,
+      name                TEXT,
+      cron_expr           TEXT,
+      status              TEXT    DEFAULT 'active',
+      concurrency_policy  TEXT    DEFAULT 'skip_if_active',
+      catch_up_policy     TEXT    DEFAULT 'skip_missed',
+      catch_up_cap        INTEGER DEFAULT 0,
+      next_run_at         TEXT,
+      last_run_at         TEXT,
+      created_at          INTEGER,
+      updated_at          INTEGER,
+      data_json           TEXT
+    );
+    CREATE INDEX IF NOT EXISTS idx_routines_company_status ON routines(company_id, status);
+
+    CREATE TABLE IF NOT EXISTS comments (
+      id            TEXT    PRIMARY KEY,
+      task_id       TEXT,
+      approval_id   TEXT,
+      company_id    TEXT    NOT NULL,
+      body          TEXT    NOT NULL,
+      author_type   TEXT    DEFAULT 'user',
+      author_id     TEXT,
+      presentation_kind TEXT,
+      presentation_tone TEXT,
+      sync_status   TEXT    DEFAULT 'pending',
+      created_at    INTEGER,
+      data_json     TEXT
+    );
+    CREATE INDEX IF NOT EXISTS idx_comments_task ON comments(task_id, created_at);
+    CREATE INDEX IF NOT EXISTS idx_comments_approval ON comments(approval_id, created_at);
+    CREATE INDEX IF NOT EXISTS idx_comments_sync ON comments(company_id, sync_status);
+  `);
+
+  // H-7 migration: add created_at column to existing goals tables that predate this commit.
+  // ALTER TABLE ADD COLUMN is idempotent in SQLite when caught — safe to run on every startup.
+  try { db.exec(`ALTER TABLE goals ADD COLUMN created_at INTEGER`); } catch (_) { /* column already exists */ }
+  // C-2 migration: project_documents table may not exist on older installs (added in Phase 3 audit fix).
+  // CREATE TABLE IF NOT EXISTS handles this; no ALTER needed since it's a new table.
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function _parseJson<T>(value: string | null | undefined, fallback: T): T {
+  if (!value) return fallback;
+  try { return JSON.parse(value); } catch { return fallback; }
+}
+
+// H-8 fix: these are the SQLite column names that _mergeRow overlays from the DB row.
+// When passing a _mergeRow result back into a CREATE/upsert function, strip these so
+// data_json doesn't accumulate duplicate snake_case keys alongside the camelCase ones.
+const _SQLITE_COLUMN_KEYS = new Set([
+  'id', 'company_id', 'title', 'description', 'level', 'status', 'parent_id',
+  'created_at', 'updated_at', 'data_json',
+  // tasks
+  'assignee_agent_id', 'goal_id', 'origin_kind', 'helios_issue_id', 'execution_locked_at',
+  // approvals
+  'type', 'strategy_id', 'requested_by',
+  // cost_events
+  'agent_id', 'feature', 'model', 'amount_usd',
+  // business_agents
+  'role', 'last_heartbeat_at', 'pause_reason',
+  // okrs / leads / crm_contacts / accounts / opportunities
+  'email', 'name', 'amount',
+  // helios_projects (C-4 fix: prevents H-8 data pollution for projects)
+  'pillar_id', 'phase',
+  // project_documents
+  'project_id', 'section', 'value', 'updated_by',
+  'intent_anchor', 'success_criteria', 'exclusions', 'content', 'purpose', 'approach', 'version',
+  // routines
+  'agent_id', 'cron_expr', 'concurrency_policy', 'catch_up_policy', 'catch_up_cap',
+  'next_run_at', 'last_run_at',
+  // comments (P8C-09)
+  'task_id', 'approval_id', 'author_type', 'author_id',
+  'presentation_kind', 'presentation_tone', 'sync_status',
+]);
+
+function _stripSqliteCols(obj: Record<string, any>): Record<string, any> {
+  const result: Record<string, any> = {};
+  for (const key of Object.keys(obj)) {
+    if (!_SQLITE_COLUMN_KEYS.has(key)) result[key] = obj[key];
+  }
+  return result;
+}
+
+function _mergeRow(row: any): Record<string, any> {
+  const base = _parseJson<Record<string, any>>(row.data_json, {});
+  const merged: Record<string, any> = { ...base };
+  for (const key of Object.keys(row)) {
+    if (key !== 'data_json') merged[key] = row[key];
+  }
+  return merged;
+}
+
+function _statusParams(statuses: string[]): { placeholders: string; params: string[] } {
+  const placeholders = statuses.map(() => '?').join(', ');
+  return { placeholders, params: statuses };
+}
+
+// ---------------------------------------------------------------------------
+// Tasks
+// ---------------------------------------------------------------------------
+
+export function createTask(task: Record<string, any>): void {
+  const companyId = task.company_id ?? task.companyId;
+  if (!companyId) throw new Error(`[hbo-core-store] createTask: company_id is required (task id=${task.id})`);
+  const db = getDb();
+  const now = Date.now();
+  db.prepare(`
+    INSERT OR REPLACE INTO tasks
+      (id, company_id, title, status, assignee_agent_id, goal_id,
+       origin_kind, helios_issue_id, execution_locked_at, created_at, updated_at, data_json)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(
+    task.id,
+    companyId,
+    task.title ?? null,
+    task.status ?? null,
+    task.assignee_agent_id ?? task.assigneeAgentId ?? null,
+    task.goal_id ?? task.goalId ?? null,
+    task.origin_kind ?? task.originKind ?? null,
+    task.helios_issue_id ?? task.heliosIssueId ?? null,
+    task.execution_locked_at ?? task.executionLockedAt ?? null,
+    task.created_at ?? task.createdAt ?? now,
+    task.updated_at ?? task.updatedAt ?? now,
+    JSON.stringify(task),
+  );
+}
+
+export function getTask(id: string, companyId: string): Record<string, any> | null {
+  const db = getDb();
+  const row = db.prepare('SELECT * FROM tasks WHERE id = ? AND company_id = ?').get(id, companyId) as any;
+  return row ? _mergeRow(row) : null;
+}
+
+export function updateTask(id: string, companyId: string, update: Record<string, any>): void {
+  // Upsert: if not in SQLite yet, create with update applied rather than silently no-op
+  const existing = getTask(id, companyId) ?? { id, company_id: companyId };
+  const merged = { ...existing, ...update, id, company_id: companyId, updated_at: Date.now() };
+  createTask(merged);
+}
+
+export function getTasksByCompanyStatus(
+  companyId: string,
+  status: string | string[],
+): Record<string, any>[] {
+  const db = getDb();
+  const statuses = Array.isArray(status) ? status : [status];
+  const { placeholders, params } = _statusParams(statuses);
+  return (db.prepare(
+    `SELECT * FROM tasks WHERE company_id = ? AND status IN (${placeholders})`
+  ).all(companyId, ...params) as any[]).map(_mergeRow);
+}
+
+export function deleteTask(id: string, companyId: string): void {
+  const db = getDb();
+  db.prepare('DELETE FROM tasks WHERE id = ? AND company_id = ?').run(id, companyId);
+}
+
+// ---------------------------------------------------------------------------
+// Approvals
+// ---------------------------------------------------------------------------
+
+export function createApproval(approval: Record<string, any>): void {
+  const companyId = approval.company_id ?? approval.companyId;
+  if (!companyId) throw new Error(`[hbo-core-store] createApproval: company_id is required (approval id=${approval.id})`);
+  const db = getDb();
+  const now = Date.now();
+  db.prepare(`
+    INSERT OR REPLACE INTO approvals
+      (id, company_id, type, status, strategy_id, requested_by, created_at, updated_at, data_json)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(
+    approval.id,
+    companyId,
+    approval.type ?? null,
+    approval.status ?? null,
+    approval.strategy_id ?? approval.strategyId ?? null,
+    approval.requested_by ?? approval.requestedBy ?? null,
+    approval.created_at ?? approval.createdAt ?? now,
+    approval.updated_at ?? approval.updatedAt ?? now,
+    JSON.stringify(approval),
+  );
+}
+
+export function getApproval(id: string, companyId: string): Record<string, any> | null {
+  const db = getDb();
+  const row = db.prepare('SELECT * FROM approvals WHERE id = ? AND company_id = ?').get(id, companyId) as any;
+  return row ? _mergeRow(row) : null;
+}
+
+export function updateApproval(id: string, companyId: string, update: Record<string, any>): void {
+  const existing = getApproval(id, companyId) ?? { id, company_id: companyId };
+  const merged = { ...existing, ...update, id, company_id: companyId, updated_at: Date.now() };
+  createApproval(merged);
+}
+
+export function getApprovalsByCompanyStatus(
+  companyId: string,
+  status: string | string[],
+): Record<string, any>[] {
+  const db = getDb();
+  const statuses = Array.isArray(status) ? status : [status];
+  const { placeholders, params } = _statusParams(statuses);
+  return (db.prepare(
+    `SELECT * FROM approvals WHERE company_id = ? AND status IN (${placeholders})`
+  ).all(companyId, ...params) as any[]).map(_mergeRow);
+}
+
+// ---------------------------------------------------------------------------
+// Budget Policies
+// ---------------------------------------------------------------------------
+
+export function upsertBudgetPolicy(policy: Record<string, any>): void {
+  const companyId = policy.company_id ?? policy.companyId;
+  if (!companyId) throw new Error(`[hbo-core-store] upsertBudgetPolicy: company_id is required`);
+  const db = getDb();
+  db.prepare(`
+    INSERT OR REPLACE INTO budget_policies
+      (id, company_id, agent_id, spent_cents, percent_used, updated_at, data_json)
+    VALUES (?, ?, ?, ?, ?, ?, ?)
+  `).run(
+    policy.id,
+    companyId,
+    policy.agent_id ?? policy.agentId ?? null,
+    policy.spent_cents ?? policy.spentCents ?? 0,
+    policy.percent_used ?? policy.percentUsed ?? 0,
+    policy.updated_at ?? policy.updatedAt ?? Date.now(),
+    JSON.stringify(policy),
+  );
+}
+
+export function getBudgetPolicy(id: string, companyId: string): Record<string, any> | null {
+  const db = getDb();
+  const row = db.prepare('SELECT * FROM budget_policies WHERE id = ? AND company_id = ?').get(id, companyId) as any;
+  return row ? _mergeRow(row) : null;
+}
+
+export function getBudgetPoliciesByCompany(companyId: string): Record<string, any>[] {
+  const db = getDb();
+  return (db.prepare('SELECT * FROM budget_policies WHERE company_id = ?').all(companyId) as any[]).map(_mergeRow);
+}
+
+// ---------------------------------------------------------------------------
+// Cost Events
+// ---------------------------------------------------------------------------
+
+export function createCostEvent(event: Record<string, any>): void {
+  const companyId = event.company_id ?? event.companyId;
+  if (!companyId) throw new Error(`[hbo-core-store] createCostEvent: company_id is required`);
+  const db = getDb();
+  const now = Date.now();
+  db.prepare(`
+    INSERT OR REPLACE INTO cost_events
+      (id, company_id, agent_id, feature, model, amount_usd, created_at, data_json)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(
+    event.id,
+    companyId,
+    event.agent_id ?? event.agentId ?? null,
+    event.feature ?? null,
+    event.model ?? null,
+    event.amount_usd ?? event.amountUsd ?? null,
+    event.created_at ?? event.createdAt ?? now,
+    JSON.stringify(event),
+  );
+}
+
+export function getCostEventsByCompanyRange(
+  companyId: string,
+  startMs: number,
+  endMs: number,
+): Record<string, any>[] {
+  const db = getDb();
+  return (db.prepare(
+    'SELECT * FROM cost_events WHERE company_id = ? AND created_at >= ? AND created_at <= ? ORDER BY created_at ASC'
+  ).all(companyId, startMs, endMs) as any[]).map(_mergeRow);
+}
+
+// ---------------------------------------------------------------------------
+// Business Agents
+// ---------------------------------------------------------------------------
+
+export function upsertBusinessAgent(agent: Record<string, any>): void {
+  const companyId = agent.company_id ?? agent.companyId;
+  if (!companyId) throw new Error(`[hbo-core-store] upsertBusinessAgent: company_id is required`);
+  const db = getDb();
+  db.prepare(`
+    INSERT OR REPLACE INTO business_agents
+      (id, company_id, role, status, current_task_id, skill, adapter, updated_at, data_json)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(
+    agent.id,
+    companyId,
+    agent.role ?? null,
+    agent.status ?? null,
+    agent.current_task_id ?? agent.currentTaskId ?? null,
+    agent.skill ?? null,
+    agent.adapter ?? null,
+    agent.updated_at ?? agent.updatedAt ?? Date.now(),
+    JSON.stringify(agent),
+  );
+}
+
+export function getBusinessAgent(id: string, companyId: string): Record<string, any> | null {
+  const db = getDb();
+  const row = db.prepare('SELECT * FROM business_agents WHERE id = ? AND company_id = ?').get(id, companyId) as any;
+  return row ? _mergeRow(row) : null;
+}
+
+export function getBusinessAgentsByCompany(companyId: string): Record<string, any>[] {
+  const db = getDb();
+  return (db.prepare('SELECT * FROM business_agents WHERE company_id = ?').all(companyId) as any[]).map(_mergeRow);
+}
+
+// ---------------------------------------------------------------------------
+// OKRs
+// ---------------------------------------------------------------------------
+
+export function upsertOKR(okr: Record<string, any>): void {
+  const companyId = okr.company_id ?? okr.companyId;
+  if (!companyId) throw new Error(`[hbo-core-store] upsertOKR: company_id is required`);
+  const db = getDb();
+  db.prepare(`
+    INSERT OR REPLACE INTO okrs
+      (id, company_id, type, status, title, updated_at, data_json)
+    VALUES (?, ?, ?, ?, ?, ?, ?)
+  `).run(
+    okr.id,
+    companyId,
+    okr.type ?? null,
+    okr.status ?? null,
+    okr.title ?? null,
+    okr.updated_at ?? okr.updatedAt ?? Date.now(),
+    JSON.stringify(okr),
+  );
+}
+
+export function getOKRsByCompanyType(
+  companyId: string,
+  type?: string,
+  status?: string,
+): Record<string, any>[] {
+  const db = getDb();
+  if (type !== undefined && status !== undefined) {
+    return (db.prepare('SELECT * FROM okrs WHERE company_id = ? AND type = ? AND status = ?').all(companyId, type, status) as any[]).map(_mergeRow);
+  }
+  if (type !== undefined) {
+    return (db.prepare('SELECT * FROM okrs WHERE company_id = ? AND type = ?').all(companyId, type) as any[]).map(_mergeRow);
+  }
+  if (status !== undefined) {
+    return (db.prepare('SELECT * FROM okrs WHERE company_id = ? AND status = ?').all(companyId, status) as any[]).map(_mergeRow);
+  }
+  return (db.prepare('SELECT * FROM okrs WHERE company_id = ?').all(companyId) as any[]).map(_mergeRow);
+}
+
+// ---------------------------------------------------------------------------
+// Goals
+// ---------------------------------------------------------------------------
+
+export function createGoal(goal: Record<string, any>): void {
+  const companyId = goal.company_id ?? goal.companyId;
+  if (!companyId) throw new Error(`[hbo-core-store] createGoal: company_id is required (goal id=${goal.id})`);
+  const db = getDb();
+  const now = Date.now();
+  db.prepare(`
+    INSERT OR REPLACE INTO goals
+      (id, company_id, title, description, level, status, parent_id, created_at, updated_at, data_json)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(
+    goal.id,
+    companyId,
+    goal.title ?? null,
+    goal.description ?? goal.desc ?? null,
+    goal.level ?? null,
+    goal.status ?? null,
+    goal.parent_id ?? goal.parentId ?? goal.parentGoalId ?? null,
+    goal.created_at ?? goal.createdAt ?? now,
+    goal.updated_at ?? goal.updatedAt ?? now,
+    JSON.stringify(goal),
+  );
+}
+
+export function getGoal(id: string, companyId: string): Record<string, any> | null {
+  const db = getDb();
+  const row = db.prepare('SELECT * FROM goals WHERE id = ? AND company_id = ?').get(id, companyId) as any;
+  return row ? _mergeRow(row) : null;
+}
+
+export function updateGoal(id: string, companyId: string, update: Record<string, any>): void {
+  const existing = getGoal(id, companyId) ?? { id, company_id: companyId };
+  // H-8 fix: strip SQLite column keys from the existing merged row before re-creating,
+  // so data_json doesn't accumulate duplicate snake_case keys from _mergeRow.
+  const cleanExisting = _stripSqliteCols(existing);
+  createGoal({ ...cleanExisting, ...update, id, company_id: companyId, updated_at: Date.now() });
+}
+
+export function deleteGoal(id: string, companyId: string): void {
+  const db = getDb();
+  db.prepare('DELETE FROM goals WHERE id = ? AND company_id = ?').run(id, companyId);
+}
+
+export function getGoalsByCompany(companyId: string): Record<string, any>[] {
+  const db = getDb();
+  return (db.prepare('SELECT * FROM goals WHERE company_id = ?').all(companyId) as any[]).map(_mergeRow);
+}
+
+// ---------------------------------------------------------------------------
+// HeliosProjects (P3-SQL: SQLite mirror of HeliosProject Memgraph nodes)
+// ---------------------------------------------------------------------------
+
+export function upsertProject(project: Record<string, any>): void {
+  const companyId = project.company_id ?? project.companyId;
+  if (!companyId) throw new Error(`[hbo-core-store] upsertProject: company_id is required`);
+  const db = getDb();
+  const now = Date.now();
+  db.prepare(`
+    INSERT OR REPLACE INTO helios_projects
+      (id, company_id, name, pillar_id, goal_id, status, phase, created_at, updated_at, data_json)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(
+    project.id,
+    companyId,
+    project.name ?? null,
+    project.pillar_id ?? project.pillarId ?? null,
+    project.goal_id ?? project.goalId ?? null,
+    project.status ?? 'planning',
+    project.phase ?? 'planning',
+    project.created_at ?? project.createdAt ?? now,
+    project.updated_at ?? project.updatedAt ?? now,
+    JSON.stringify(project),
+  );
+}
+
+export function getProject(id: string, companyId: string): Record<string, any> | null {
+  const db = getDb();
+  const row = db.prepare('SELECT * FROM helios_projects WHERE id = ? AND company_id = ?').get(id, companyId) as any;
+  return row ? _mergeRow(row) : null;
+}
+
+export function getProjectsByCompany(companyId: string): Record<string, any>[] {
+  const db = getDb();
+  return (db.prepare('SELECT * FROM helios_projects WHERE company_id = ? ORDER BY created_at DESC LIMIT 100').all(companyId) as any[]).map(_mergeRow);
+}
+
+export function updateProject(id: string, companyId: string, update: Record<string, any>): void {
+  // M-4 fix: SQLite project state can now advance (status, phase, name changes)
+  const existing = getProject(id, companyId) ?? { id, company_id: companyId };
+  const cleanExisting = _stripSqliteCols(existing);
+  upsertProject({ ...cleanExisting, ...update, id, company_id: companyId, updated_at: Date.now() });
+}
+
+// ---------------------------------------------------------------------------
+// ProjectDocuments (C-2: SQLite mirror of ProjectDocument Memgraph nodes)
+// ---------------------------------------------------------------------------
+
+export function upsertProjectDocument(doc: Record<string, any>): void {
+  const projectId = doc.project_id ?? doc.projectId;
+  if (!projectId) throw new Error(`[hbo-core-store] upsertProjectDocument: project_id is required`);
+  const db = getDb();
+  const id = doc.id ?? `pdoc:${projectId}:main`;
+  const now = Date.now();
+  db.prepare(`
+    INSERT OR REPLACE INTO project_documents
+      (id, project_id, company_id, purpose, approach, intent_anchor,
+       success_criteria, exclusions, content, version, updated_at, data_json)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(
+    id,
+    projectId,
+    doc.company_id ?? doc.companyId ?? null,
+    doc.purpose ?? null,
+    doc.approach ?? null,
+    doc.intent_anchor ?? doc.intentAnchor ?? null,
+    doc.success_criteria ?? doc.successCriteria ?? '[]',
+    doc.exclusions ?? '[]',
+    doc.content ?? null,
+    doc.version ?? 1,
+    doc.updated_at ?? doc.updatedAt ?? now,
+    JSON.stringify(doc),
+  );
+}
+
+export function getProjectDocument(projectId: string): Record<string, any> | null {
+  const db = getDb();
+  const row = db.prepare('SELECT * FROM project_documents WHERE project_id = ? ORDER BY updated_at DESC LIMIT 1').get(projectId) as any;
+  return row ? _mergeRow(row) : null;
+}
+
+// ---------------------------------------------------------------------------
+// Routines (P5-SQL: SQLite mirror of Routine Memgraph nodes)
+// ---------------------------------------------------------------------------
+
+export function upsertRoutine(routine: Record<string, any>): void {
+  const companyId = routine.company_id ?? routine.companyId;
+  if (!companyId) throw new Error(`[hbo-core-store] upsertRoutine: company_id is required`);
+  const db = getDb();
+  const now = Date.now();
+  db.prepare(`
+    INSERT OR REPLACE INTO routines
+      (id, company_id, agent_id, name, cron_expr, status, concurrency_policy,
+       catch_up_policy, catch_up_cap, next_run_at, last_run_at, created_at, updated_at, data_json)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(
+    routine.id,
+    companyId,
+    routine.agent_id ?? routine.agentId ?? null,
+    routine.name ?? routine.title ?? null,
+    routine.cron_expr ?? routine.cronExpr ?? null,
+    routine.status ?? 'active',
+    routine.concurrency_policy ?? routine.concurrencyPolicy ?? 'skip_if_active',
+    routine.catch_up_policy ?? routine.catchUpPolicy ?? 'skip_missed',
+    routine.catch_up_cap ?? routine.catchUpCap ?? 0,
+    routine.next_run_at ?? routine.nextRunAt ?? null,
+    routine.last_run_at ?? routine.lastRunAt ?? null,
+    routine.created_at ?? routine.createdAt ?? now,
+    routine.updated_at ?? routine.updatedAt ?? now,
+    JSON.stringify(routine),
+  );
+}
+
+export function getRoutine(id: string, companyId: string): Record<string, any> | null {
+  const db = getDb();
+  const row = db.prepare('SELECT * FROM routines WHERE id = ? AND company_id = ?').get(id, companyId) as any;
+  return row ? _mergeRow(row) : null;
+}
+
+export function getRoutinesByCompany(companyId: string, status?: string): Record<string, any>[] {
+  const db = getDb();
+  if (status) {
+    return (db.prepare('SELECT * FROM routines WHERE company_id = ? AND status = ? ORDER BY created_at DESC').all(companyId, status) as any[]).map(_mergeRow);
+  }
+  return (db.prepare('SELECT * FROM routines WHERE company_id = ? ORDER BY created_at DESC').all(companyId) as any[]).map(_mergeRow);
+}
+
+export function updateRoutine(id: string, companyId: string, update: Record<string, any>): void {
+  const existing = getRoutine(id, companyId) ?? { id, company_id: companyId };
+  const cleanExisting = _stripSqliteCols(existing);
+  upsertRoutine({ ...cleanExisting, ...update, id, company_id: companyId, updated_at: Date.now() });
+}
+
+// ---------------------------------------------------------------------------
+// Comments (P8C-09: offline queue for task + approval comments)
+// ---------------------------------------------------------------------------
+
+export function createComment(comment: Record<string, any>): void {
+  const companyId = comment.company_id ?? comment.companyId;
+  if (!companyId) throw new Error(`[hbo-core-store] createComment: company_id is required`);
+  const db = getDb();
+  const now = Date.now();
+  db.prepare(`
+    INSERT OR REPLACE INTO comments
+      (id, task_id, approval_id, company_id, body, author_type, author_id,
+       presentation_kind, presentation_tone, sync_status, created_at, data_json)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(
+    comment.id,
+    comment.task_id ?? comment.taskId ?? null,
+    comment.approval_id ?? comment.approvalId ?? null,
+    companyId,
+    comment.body ?? '',
+    comment.author_type ?? comment.authorType ?? 'user',
+    comment.author_id ?? comment.authorId ?? null,
+    comment.presentation_kind ?? comment.presentationKind ?? null,
+    comment.presentation_tone ?? comment.presentationTone ?? null,
+    comment.sync_status ?? comment.syncStatus ?? 'pending',
+    comment.created_at ?? comment.createdAt ?? now,
+    JSON.stringify(comment),
+  );
+}
+
+export function getCommentsByTask(taskId: string, companyId: string): Record<string, any>[] {
+  const db = getDb();
+  return (db.prepare('SELECT * FROM comments WHERE task_id = ? AND company_id = ? ORDER BY created_at ASC').all(taskId, companyId) as any[]).map(_mergeRow);
+}
+
+export function getCommentsByApproval(approvalId: string, companyId: string): Record<string, any>[] {
+  const db = getDb();
+  return (db.prepare('SELECT * FROM comments WHERE approval_id = ? AND company_id = ? ORDER BY created_at ASC').all(approvalId, companyId) as any[]).map(_mergeRow);
+}
+
+export function getPendingComments(companyId: string): Record<string, any>[] {
+  const db = getDb();
+  return (db.prepare("SELECT * FROM comments WHERE company_id = ? AND sync_status = 'pending' ORDER BY created_at ASC").all(companyId) as any[]).map(_mergeRow);
+}
+
+export function markCommentSynced(id: string): void {
+  const db = getDb();
+  db.prepare("UPDATE comments SET sync_status = 'synced' WHERE id = ?").run(id);
+}
+
+// ---------------------------------------------------------------------------
+// Leads
+// ---------------------------------------------------------------------------
+
+export function upsertLead(lead: Record<string, any>): void {
+  const companyId = lead.company_id ?? lead.companyId;
+  if (!companyId) throw new Error(`[hbo-core-store] upsertLead: company_id is required`);
+  const db = getDb();
+  db.prepare(`
+    INSERT OR REPLACE INTO leads
+      (id, company_id, status, email, name, updated_at, data_json)
+    VALUES (?, ?, ?, ?, ?, ?, ?)
+  `).run(
+    lead.id,
+    companyId,
+    lead.status ?? null,
+    lead.email ?? null,
+    lead.name ?? null,
+    lead.updated_at ?? lead.updatedAt ?? Date.now(),
+    JSON.stringify(lead),
+  );
+}
+
+export function getLeadsByCompanyStatus(companyId: string, statuses: string[]): Record<string, any>[] {
+  const db = getDb();
+  const { placeholders, params } = _statusParams(statuses);
+  return (db.prepare(
+    `SELECT * FROM leads WHERE company_id = ? AND status IN (${placeholders})`
+  ).all(companyId, ...params) as any[]).map(_mergeRow);
+}
+
+// ---------------------------------------------------------------------------
+// CRM Contacts
+// ---------------------------------------------------------------------------
+
+export function upsertCRMContact(contact: Record<string, any>): void {
+  const companyId = contact.company_id ?? contact.companyId;
+  if (!companyId) throw new Error(`[hbo-core-store] upsertCRMContact: company_id is required`);
+  const db = getDb();
+  db.prepare(`
+    INSERT OR REPLACE INTO crm_contacts
+      (id, company_id, email, name, updated_at, data_json)
+    VALUES (?, ?, ?, ?, ?, ?)
+  `).run(
+    contact.id,
+    companyId,
+    contact.email ?? null,
+    contact.name ?? null,
+    contact.updated_at ?? contact.updatedAt ?? Date.now(),
+    JSON.stringify(contact),
+  );
+}
+
+export function getCRMContactsByCompany(companyId: string): Record<string, any>[] {
+  const db = getDb();
+  return (db.prepare('SELECT * FROM crm_contacts WHERE company_id = ?').all(companyId) as any[]).map(_mergeRow);
+}
+
+// ---------------------------------------------------------------------------
+// Accounts
+// ---------------------------------------------------------------------------
+
+export function upsertAccount(account: Record<string, any>): void {
+  const companyId = account.company_id ?? account.companyId;
+  if (!companyId) throw new Error(`[hbo-core-store] upsertAccount: company_id is required`);
+  const db = getDb();
+  db.prepare(`
+    INSERT OR REPLACE INTO accounts
+      (id, company_id, name, updated_at, data_json)
+    VALUES (?, ?, ?, ?, ?)
+  `).run(
+    account.id,
+    companyId,
+    account.name ?? null,
+    account.updated_at ?? account.updatedAt ?? Date.now(),
+    JSON.stringify(account),
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Opportunities
+// ---------------------------------------------------------------------------
+
+export function upsertOpportunity(opp: Record<string, any>): void {
+  const companyId = opp.company_id ?? opp.companyId;
+  if (!companyId) throw new Error(`[hbo-core-store] upsertOpportunity: company_id is required`);
+  const db = getDb();
+  db.prepare(`
+    INSERT OR REPLACE INTO opportunities
+      (id, company_id, title, status, updated_at, data_json)
+    VALUES (?, ?, ?, ?, ?, ?)
+  `).run(
+    opp.id,
+    companyId,
+    opp.title ?? null,
+    opp.status ?? null,
+    opp.updated_at ?? opp.updatedAt ?? Date.now(),
+    JSON.stringify(opp),
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Test / lifecycle helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Reset the DB singleton. ONLY call this in tests.
+ */
+export function resetHboCoreStore(): void {
+  try { _db?.close(); } catch { /* ignore */ }
+  _db = null;
+  _engine = null;
+}