openclaw-observability 2026.4.1 → 2026.4.21

package/dist/storage/duckdb-local-writer.js

@@ -38,9 +38,31 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DuckDBLocalWriter = void 0;
+exports.buildDuckDBOpenOptions = buildDuckDBOpenOptions;
 const path = __importStar(require("path"));
 const fs = __importStar(require("fs"));
 const structured_model_1 = require("./structured-model");
+const DEFAULT_DUCKDB_MEMORY_LIMIT = '1GB';
+const DEFAULT_DUCKDB_THREADS = 2;
+const MAX_DUCKDB_THREADS = 8;
+const DEFAULT_DUCKDB_TEMP_DIRECTORY = path.join('/tmp', 'openclaw-observability-duckdb');
+function buildDuckDBOpenOptions(config) {
+    const memoryLimit = typeof config.memoryLimit === 'string' && config.memoryLimit.trim()
+        ? config.memoryLimit.trim()
+        : DEFAULT_DUCKDB_MEMORY_LIMIT;
+    const rawThreads = Number(config.threads ?? DEFAULT_DUCKDB_THREADS);
+    const threads = Number.isFinite(rawThreads)
+        ? Math.min(MAX_DUCKDB_THREADS, Math.max(1, Math.floor(rawThreads)))
+        : DEFAULT_DUCKDB_THREADS;
+    const tempDirectory = typeof config.tempDirectory === 'string' && config.tempDirectory.trim()
+        ? config.tempDirectory.trim()
+        : DEFAULT_DUCKDB_TEMP_DIRECTORY;
+    return {
+        memory_limit: memoryLimit,
+        threads: String(threads),
+        temp_directory: tempDirectory,
+    };
+}
 /* ------------------------------------------------------------------ */
 /*  @duckdb/node-api Promise wrapper -> QueryPool adapter              */
 /* ------------------------------------------------------------------ */
@@ -252,9 +274,9 @@ class DuckDBPool {
  */
 const DUCKDB_SCHEMA_STATEMENTS = [
     // Drop legacy sequences that cause WAL write-write conflicts
-    `DROP SEQUENCE IF EXISTS audit_actions_id_seq`,
-    `DROP SEQUENCE IF EXISTS audit_alerts_id_seq`,
-    `CREATE TABLE IF NOT EXISTS audit_actions (
+    `DROP SEQUENCE IF EXISTS observation_actions_id_seq`,
+    `DROP SEQUENCE IF EXISTS observation_alerts_id_seq`,
+    `CREATE TABLE IF NOT EXISTS observation_actions (
     id BIGINT PRIMARY KEY,
     session_id VARCHAR(64) NOT NULL,
     action_type VARCHAR(32) NOT NULL,
@@ -266,18 +288,21 @@ const DUCKDB_SCHEMA_STATEMENTS = [
     completion_tokens INTEGER DEFAULT NULL,
     duration_ms INTEGER DEFAULT NULL,
     user_id VARCHAR(128) DEFAULT '',
+    run_id VARCHAR(128) DEFAULT '',
+    parent_run_id VARCHAR(128) DEFAULT '',
     channel_id VARCHAR(128) DEFAULT '',
     created_at TIMESTAMP DEFAULT current_timestamp
   )`,
-    `CREATE INDEX IF NOT EXISTS idx_act_session ON audit_actions(session_id)`,
-    `CREATE INDEX IF NOT EXISTS idx_act_type ON audit_actions(action_type)`,
-    `CREATE INDEX IF NOT EXISTS idx_act_created ON audit_actions(created_at)`,
-    `CREATE INDEX IF NOT EXISTS idx_act_user ON audit_actions(user_id)`,
+    `CREATE INDEX IF NOT EXISTS idx_act_session ON observation_actions(session_id)`,
+    `CREATE INDEX IF NOT EXISTS idx_act_type ON observation_actions(action_type)`,
+    `CREATE INDEX IF NOT EXISTS idx_act_created ON observation_actions(created_at)`,
+    `CREATE INDEX IF NOT EXISTS idx_act_user ON observation_actions(user_id)`,
     // Note: idx_act_channel is created after migration (see migration logic below)
     // This prevents errors when table exists without channel_id column
-    `CREATE TABLE IF NOT EXISTS audit_sessions (
+    `CREATE TABLE IF NOT EXISTS observation_sessions (
     session_id VARCHAR(64) PRIMARY KEY,
     user_id VARCHAR(128) DEFAULT '',
+    parent_session_id VARCHAR(128) DEFAULT '',
     model_name VARCHAR(128) DEFAULT '',
     channel_id VARCHAR(128) DEFAULT '',
     start_time TIMESTAMP NOT NULL,
@@ -285,11 +310,11 @@ const DUCKDB_SCHEMA_STATEMENTS = [
     total_actions INTEGER DEFAULT 0,
     total_tokens INTEGER DEFAULT 0
   )`,
-    `CREATE INDEX IF NOT EXISTS idx_ses_user ON audit_sessions(user_id)`,
-    `CREATE INDEX IF NOT EXISTS idx_ses_start ON audit_sessions(start_time)`,
-    // Note: idx_ses_channel is created after migration (see migration logic below)
+    `CREATE INDEX IF NOT EXISTS idx_ses_user ON observation_sessions(user_id)`,
+    `CREATE INDEX IF NOT EXISTS idx_ses_start ON observation_sessions(start_time)`,
+    // Note: idx_ses_parent / idx_ses_channel are created after migration
     // This prevents errors when table exists without channel_id column
-    `CREATE TABLE IF NOT EXISTS audit_alerts (
+    `CREATE TABLE IF NOT EXISTS observation_alerts (
     id BIGINT PRIMARY KEY,
     alert_id VARCHAR(64) NOT NULL,
     session_id VARCHAR(64) NOT NULL,
@@ -308,12 +333,12 @@ const DUCKDB_SCHEMA_STATEMENTS = [
     model_name VARCHAR(128) DEFAULT '',
     created_at TIMESTAMP DEFAULT current_timestamp
   )`,
-    `CREATE INDEX IF NOT EXISTS idx_alrt_sev ON audit_alerts(severity)`,
-    `CREATE INDEX IF NOT EXISTS idx_alrt_cat ON audit_alerts(category)`,
-    `CREATE INDEX IF NOT EXISTS idx_alrt_sta ON audit_alerts(status)`,
-    `CREATE INDEX IF NOT EXISTS idx_alrt_ses ON audit_alerts(session_id)`,
-    `CREATE INDEX IF NOT EXISTS idx_alrt_cre ON audit_alerts(created_at)`,
-    `CREATE INDEX IF NOT EXISTS idx_alrt_rul ON audit_alerts(rule_id)`,
+    `CREATE INDEX IF NOT EXISTS idx_alrt_sev ON observation_alerts(severity)`,
+    `CREATE INDEX IF NOT EXISTS idx_alrt_cat ON observation_alerts(category)`,
+    `CREATE INDEX IF NOT EXISTS idx_alrt_sta ON observation_alerts(status)`,
+    `CREATE INDEX IF NOT EXISTS idx_alrt_ses ON observation_alerts(session_id)`,
+    `CREATE INDEX IF NOT EXISTS idx_alrt_cre ON observation_alerts(created_at)`,
+    `CREATE INDEX IF NOT EXISTS idx_alrt_rul ON observation_alerts(rule_id)`,
     `CREATE TABLE IF NOT EXISTS observability_metrics_samples (
     id BIGINT PRIMARY KEY,
     metric_name VARCHAR(256) NOT NULL,
@@ -330,6 +355,9 @@ const DUCKDB_SCHEMA_STATEMENTS = [
     `CREATE INDEX IF NOT EXISTS idx_metrics_fp_ts ON observability_metrics_samples(label_fingerprint, sample_timestamp_ms)`,
     `CREATE TABLE IF NOT EXISTS oc_traces (
     trace_id VARCHAR(128) PRIMARY KEY,
+    organization_id VARCHAR(64) DEFAULT 'local',
+    scope_id VARCHAR(64) DEFAULT 'local',
+    environment VARCHAR(32) DEFAULT 'prod',
     session_id VARCHAR(128) NOT NULL,
     user_id VARCHAR(128) DEFAULT '',
     channel_id VARCHAR(128) DEFAULT '',
@@ -347,6 +375,9 @@ const DUCKDB_SCHEMA_STATEMENTS = [
     `CREATE INDEX IF NOT EXISTS idx_oc_trace_channel ON oc_traces(channel_id)`,
     `CREATE TABLE IF NOT EXISTS oc_observations_core (
     observation_id VARCHAR(160) PRIMARY KEY,
+    organization_id VARCHAR(64) DEFAULT 'local',
+    scope_id VARCHAR(64) DEFAULT 'local',
+    environment VARCHAR(32) DEFAULT 'prod',
     trace_id VARCHAR(128) NOT NULL,
     parent_observation_id VARCHAR(160),
     root_observation_id VARCHAR(160) NOT NULL,
@@ -388,6 +419,9 @@ const DUCKDB_SCHEMA_STATEMENTS = [
   )`,
     `CREATE TABLE IF NOT EXISTS oc_events_raw (
     event_id VARCHAR(180) PRIMARY KEY,
+    organization_id VARCHAR(64) DEFAULT 'local',
+    scope_id VARCHAR(64) DEFAULT 'local',
+    environment VARCHAR(32) DEFAULT 'prod',
     trace_id VARCHAR(128) NOT NULL,
     observation_id VARCHAR(160) NOT NULL,
     event_type VARCHAR(64) NOT NULL,
@@ -448,6 +482,8 @@ const DUCKDB_SCHEMA_STATEMENTS = [
 class DuckDBLocalWriter {
     pool = null;
     config;
+    dataRetentionDays;
+    startupMaintenanceDone = false;
     initialized = false;
     /** Promise for an in-progress initialization (allows concurrent callers to await) */
     _initPromise = null;
@@ -461,8 +497,11 @@ class DuckDBLocalWriter {
      * This gives ~10,000 unique IDs per millisecond.
      */
     _idCounter = 0;
-    constructor(config) {
+    constructor(config, options) {
         this.config = config;
+        this.dataRetentionDays = Number.isFinite(Number(options?.dataRetentionDays))
+            ? Math.max(0, Math.floor(Number(options?.dataRetentionDays)))
+            : 30;
     }
     /** Generate a unique BIGINT ID without DuckDB SEQUENCE (precision-safe) */
     _nextId() {
@@ -583,6 +622,10 @@ class DuckDBLocalWriter {
         }
         // Ensure parent directory exists
         const dbPath = this.config.path;
+        const openOptions = buildDuckDBOpenOptions(this.config);
+        if (openOptions.temp_directory && !fs.existsSync(openOptions.temp_directory)) {
+            fs.mkdirSync(openOptions.temp_directory, { recursive: true });
+        }
         if (dbPath !== ':memory:') {
             const dir = path.dirname(dbPath);
             if (!fs.existsSync(dir)) {
@@ -594,7 +637,7 @@ class DuckDBLocalWriter {
             if (!fs.existsSync(dbPath)) {
                 // Create empty database file first (this creates the main .duckdb file)
                 // Then we'll open it normally for actual operations
-                const tempInstance = await duckdb.DuckDBInstance.create(dbPath);
+                const tempInstance = await duckdb.DuckDBInstance.create(dbPath, openOptions);
                 const tempConn = await tempInstance.connect();
                 // Immediately checkpoint to ensure main file is created (not just WAL)
                 // Use run() for DDL/commands (query() is for SELECT statements)
@@ -627,48 +670,60 @@ class DuckDBLocalWriter {
             }
         }
         // Open database (main file now guaranteed to exist)
-        const instance = await duckdb.DuckDBInstance.create(dbPath);
+        const instance = await duckdb.DuckDBInstance.create(dbPath, openOptions);
         const conn = await instance.connect();
         this.pool = new DuckDBPool(instance, conn);
         // Create table schema (execute one statement at a time)
         for (const stmt of DUCKDB_SCHEMA_STATEMENTS) {
             await this.pool.run(stmt);
         }
-        // Migration: add channel_id column if it doesn't exist (for existing databases)
-        // Silently check if column exists before adding to avoid unnecessary logs
-        const hasChannelIdInActions = await this._hasColumn('audit_actions', 'channel_id');
-        if (!hasChannelIdInActions) {
-            try {
-                await this.pool.run(`ALTER TABLE audit_actions ADD COLUMN channel_id VARCHAR(128) DEFAULT ''`);
-                // Only log when actually adding the column (silent if already exists)
-            }
-            catch (err) {
-                const errMsg = err.message || String(err);
-                if (!errMsg.includes('already exists') && !errMsg.includes('duplicate column')) {
-                    console.warn('[openclaw-observability] Failed to add channel_id to audit_actions:', errMsg);
-                }
-            }
-        }
-        const hasChannelIdInSessions = await this._hasColumn('audit_sessions', 'channel_id');
-        if (!hasChannelIdInSessions) {
+        // Migration: channel_id for legacy DBs.
+        await this._ensureChannelIdColumn('observation_actions');
+        await this._ensureChannelIdColumn('observation_sessions');
+        // Migration: cloud-tenant columns for legacy local DuckDB databases.
+        // New query layer filters by scope_id; old databases created before this
+        // column existed would fail with Binder Error.
+        await this._ensureTenantColumn('observation_actions', 'organization_id', `VARCHAR(64) DEFAULT 'local'`, 'local');
+        await this._ensureTenantColumn('observation_actions', 'scope_id', `VARCHAR(64) DEFAULT 'local'`, 'local');
+        await this._ensureTenantColumn('observation_actions', 'environment', `VARCHAR(32) DEFAULT 'prod'`, 'prod');
+        await this._ensureActionRunLineageColumns();
+        await this._ensureTenantColumn('observation_sessions', 'organization_id', `VARCHAR(64) DEFAULT 'local'`, 'local');
+        await this._ensureTenantColumn('observation_sessions', 'scope_id', `VARCHAR(64) DEFAULT 'local'`, 'local');
+        await this._ensureTenantColumn('observation_sessions', 'environment', `VARCHAR(32) DEFAULT 'prod'`, 'prod');
+        await this._ensureColumn('observation_sessions', 'parent_session_id', `VARCHAR(128) DEFAULT ''`);
+        if (!(await this._hasIndex('observation_sessions', 'idx_ses_parent'))) {
             try {
-                await this.pool.run(`ALTER TABLE audit_sessions ADD COLUMN channel_id VARCHAR(128) DEFAULT ''`);
-                // Only log when actually adding the column (silent if already exists)
+                await this.pool.run(`CREATE INDEX idx_ses_parent ON observation_sessions(parent_session_id)`);
             }
             catch (err) {
                 const errMsg = err.message || String(err);
-                if (!errMsg.includes('already exists') && !errMsg.includes('duplicate column')) {
-                    console.warn('[openclaw-observability] Failed to add channel_id to audit_sessions:', errMsg);
+                if (!errMsg.includes('already exists')) {
+                    console.warn('[openclaw-observability] Failed to create idx_ses_parent:', errMsg);
                 }
             }
         }
+        await this._ensureTenantColumn('observation_alerts', 'organization_id', `VARCHAR(64) DEFAULT 'local'`, 'local');
+        await this._ensureTenantColumn('observation_alerts', 'scope_id', `VARCHAR(64) DEFAULT 'local'`, 'local');
+        await this._ensureTenantColumn('observation_alerts', 'environment', `VARCHAR(32) DEFAULT 'prod'`, 'prod');
+        await this._ensureTenantColumn('observability_metrics_samples', 'organization_id', `VARCHAR(64) DEFAULT 'local'`, 'local');
+        await this._ensureTenantColumn('observability_metrics_samples', 'scope_id', `VARCHAR(64) DEFAULT 'local'`, 'local');
+        await this._ensureTenantColumn('observability_metrics_samples', 'environment', `VARCHAR(32) DEFAULT 'prod'`, 'prod');
+        await this._ensureTenantColumn('oc_traces', 'organization_id', `VARCHAR(64) DEFAULT 'local'`, 'local');
+        await this._ensureTenantColumn('oc_traces', 'scope_id', `VARCHAR(64) DEFAULT 'local'`, 'local');
+        await this._ensureTenantColumn('oc_traces', 'environment', `VARCHAR(32) DEFAULT 'prod'`, 'prod');
+        await this._ensureTenantColumn('oc_observations_core', 'organization_id', `VARCHAR(64) DEFAULT 'local'`, 'local');
+        await this._ensureTenantColumn('oc_observations_core', 'scope_id', `VARCHAR(64) DEFAULT 'local'`, 'local');
+        await this._ensureTenantColumn('oc_observations_core', 'environment', `VARCHAR(32) DEFAULT 'prod'`, 'prod');
+        await this._ensureTenantColumn('oc_events_raw', 'organization_id', `VARCHAR(64) DEFAULT 'local'`, 'local');
+        await this._ensureTenantColumn('oc_events_raw', 'scope_id', `VARCHAR(64) DEFAULT 'local'`, 'local');
+        await this._ensureTenantColumn('oc_events_raw', 'environment', `VARCHAR(32) DEFAULT 'prod'`, 'prod');
         // Create index if column exists and index doesn't exist (silent check)
-        const hasChannelIdColumn = await this._hasColumn('audit_actions', 'channel_id');
+        const hasChannelIdColumn = await this._hasColumn('observation_actions', 'channel_id');
         if (hasChannelIdColumn) {
-            const hasIndex = await this._hasIndex('audit_actions', 'idx_act_channel');
+            const hasIndex = await this._hasIndex('observation_actions', 'idx_act_channel');
             if (!hasIndex) {
                 try {
-                    await this.pool.run(`CREATE INDEX idx_act_channel ON audit_actions(channel_id)`);
+                    await this.pool.run(`CREATE INDEX idx_act_channel ON observation_actions(channel_id)`);
                 }
                 catch (err) {
                     const errMsg = err.message || String(err);
@@ -678,12 +733,12 @@ class DuckDBLocalWriter {
                 }
             }
         }
-        const hasChannelIdInSessionsCol = await this._hasColumn('audit_sessions', 'channel_id');
+        const hasChannelIdInSessionsCol = await this._hasColumn('observation_sessions', 'channel_id');
         if (hasChannelIdInSessionsCol) {
-            const hasIndex = await this._hasIndex('audit_sessions', 'idx_ses_channel');
+            const hasIndex = await this._hasIndex('observation_sessions', 'idx_ses_channel');
             if (!hasIndex) {
                 try {
-                    await this.pool.run(`CREATE INDEX idx_ses_channel ON audit_sessions(channel_id)`);
+                    await this.pool.run(`CREATE INDEX idx_ses_channel ON observation_sessions(channel_id)`);
                 }
                 catch (err) {
                     const errMsg = err.message || String(err);
@@ -712,6 +767,7 @@ class DuckDBLocalWriter {
             // Still continue, but log the risk
         }
         await this._backfillStructuredFromLegacy();
+        await this.runStartupMaintenance();
         this.initialized = true;
         console.log(`[openclaw-observability] DuckDB writer initialized: ${dbPath}`);
     }
@@ -742,12 +798,13 @@ class DuckDBLocalWriter {
         if (!this.pool)
             return;
         // Ensure channel_id column exists before writing (migration safety check)
-        await this._ensureChannelIdColumn('audit_actions');
+        await this._ensureChannelIdColumn('observation_actions');
+        await this._ensureActionRunLineageColumns();
         const sql = `
-      INSERT INTO audit_actions
+      INSERT INTO observation_actions
         (id, session_id, action_type, action_name, model_name, input_params, output_result,
-         prompt_tokens, completion_tokens, duration_ms, user_id, channel_id, created_at)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+         prompt_tokens, completion_tokens, duration_ms, user_id, run_id, parent_run_id, channel_id, created_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     `;
         for (const a of actions) {
             await this.pool.run(sql, [
@@ -756,7 +813,7 @@ class DuckDBLocalWriter {
                 a.inputParams ? JSON.stringify(a.inputParams) : null,
                 a.outputResult ? JSON.stringify(a.outputResult) : null,
                 a.promptTokens, a.completionTokens, a.durationMs,
-                a.userId, a.channelId || '',
+                a.userId, a.runId || '', a.parentRunId || '', a.channelId || '',
                 this._formatDate(a.createdAt),
             ]);
         }
@@ -769,13 +826,13 @@ class DuckDBLocalWriter {
         for (const s of sessions)
             deduped.set(s.sessionId, s);
         for (const session of deduped.values()) {
-            // Aggregate stats from audit_actions in real-time
+            // Aggregate stats from observation_actions in real-time
             const [statsRows] = await this.pool.query(`SELECT
            MIN(created_at) AS start_time,
            MAX(created_at) AS end_time,
            COUNT(*)        AS total_actions,
            COALESCE(SUM(COALESCE(prompt_tokens, 0) + COALESCE(completion_tokens, 0)), 0) AS total_tokens
-         FROM audit_actions WHERE session_id = ?`, [session.sessionId]);
+         FROM observation_actions WHERE session_id = ?`, [session.sessionId]);
             const stats = statsRows[0];
             const startTime = stats?.start_time || this._formatDate(session.startTime);
             const endTime = stats?.end_time || this._formatDate(session.endTime);
@@ -784,19 +841,20 @@ class DuckDBLocalWriter {
             // Use INSERT OR REPLACE to handle concurrent inserts atomically
             // This prevents PRIMARY KEY constraint violations when multiple processes
             // or concurrent transactions try to insert the same session_id
-            await this.pool.run(`INSERT INTO audit_sessions
-          (session_id, user_id, model_name, channel_id, start_time, end_time, total_actions, total_tokens)
-         VALUES (?, ?, ?, ?, CAST(? AS TIMESTAMP), CAST(? AS TIMESTAMP), ?, ?)
+            await this.pool.run(`INSERT INTO observation_sessions
+          (session_id, user_id, parent_session_id, model_name, channel_id, start_time, end_time, total_actions, total_tokens)
+         VALUES (?, ?, ?, ?, ?, CAST(? AS TIMESTAMP), CAST(? AS TIMESTAMP), ?, ?)
          ON CONFLICT (session_id) DO UPDATE SET
-           user_id      = COALESCE(EXCLUDED.user_id, audit_sessions.user_id),
-           model_name   = CASE WHEN EXCLUDED.model_name != '' THEN EXCLUDED.model_name ELSE audit_sessions.model_name END,
-           channel_id   = CASE WHEN EXCLUDED.channel_id != '' THEN EXCLUDED.channel_id ELSE audit_sessions.channel_id END,
-           start_time   = CASE WHEN audit_sessions.start_time < EXCLUDED.start_time THEN audit_sessions.start_time ELSE EXCLUDED.start_time END,
+           user_id      = COALESCE(EXCLUDED.user_id, observation_sessions.user_id),
+           parent_session_id = CASE WHEN EXCLUDED.parent_session_id != '' THEN EXCLUDED.parent_session_id ELSE observation_sessions.parent_session_id END,
+           model_name   = CASE WHEN EXCLUDED.model_name != '' THEN EXCLUDED.model_name ELSE observation_sessions.model_name END,
+           channel_id   = CASE WHEN EXCLUDED.channel_id != '' THEN EXCLUDED.channel_id ELSE observation_sessions.channel_id END,
+           start_time   = CASE WHEN observation_sessions.start_time < EXCLUDED.start_time THEN observation_sessions.start_time ELSE EXCLUDED.start_time END,
            end_time     = EXCLUDED.end_time,
            total_actions = EXCLUDED.total_actions,
            total_tokens  = EXCLUDED.total_tokens`, [
                 session.sessionId,
-                session.userId, session.modelName, session.channelId || '',
+                session.userId, session.parentSessionId || '', session.modelName, session.channelId || '',
                 this._formatDate(session.startTime), this._formatDate(session.endTime),
                 totalActions, totalTokens,
             ]);
@@ -808,9 +866,12 @@ class DuckDBLocalWriter {
         const batch = (0, structured_model_1.buildStructuredWriteBatch)(actions);
         const traceSql = `
       INSERT INTO oc_traces
-        (trace_id, session_id, user_id, channel_id, trace_name, status, tags_json, metadata_json, start_time, end_time, created_at, updated_at)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, CAST(? AS TIMESTAMP), CAST(? AS TIMESTAMP), CAST(? AS TIMESTAMP), CAST(? AS TIMESTAMP))
+        (trace_id, organization_id, scope_id, environment, session_id, user_id, channel_id, trace_name, status, tags_json, metadata_json, start_time, end_time, created_at, updated_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, CAST(? AS TIMESTAMP), CAST(? AS TIMESTAMP), CAST(? AS TIMESTAMP), CAST(? AS TIMESTAMP))
       ON CONFLICT (trace_id) DO UPDATE SET
+        organization_id = CASE WHEN EXCLUDED.organization_id != '' THEN EXCLUDED.organization_id ELSE oc_traces.organization_id END,
+        scope_id = CASE WHEN EXCLUDED.scope_id != '' THEN EXCLUDED.scope_id ELSE oc_traces.scope_id END,
+        environment = CASE WHEN EXCLUDED.environment != '' THEN EXCLUDED.environment ELSE oc_traces.environment END,
         user_id = CASE WHEN EXCLUDED.user_id != '' THEN EXCLUDED.user_id ELSE oc_traces.user_id END,
         channel_id = CASE WHEN EXCLUDED.channel_id != '' THEN EXCLUDED.channel_id ELSE oc_traces.channel_id END,
         trace_name = CASE WHEN EXCLUDED.trace_name != '' THEN EXCLUDED.trace_name ELSE oc_traces.trace_name END,
@@ -828,9 +889,12 @@ class DuckDBLocalWriter {
     `;
         const obsSql = `
       INSERT INTO oc_observations_core
-        (observation_id, trace_id, parent_observation_id, root_observation_id, observation_type, observation_name, level, status, start_time, end_time, duration_ms, run_id, tool_call_id, model_name, provider, prompt_tokens, completion_tokens, total_tokens, cost_usd, user_id, session_id, channel_id, created_at, updated_at)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, CAST(? AS TIMESTAMP), CAST(? AS TIMESTAMP), ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, CAST(? AS TIMESTAMP), CAST(? AS TIMESTAMP))
+        (observation_id, organization_id, scope_id, environment, trace_id, parent_observation_id, root_observation_id, observation_type, observation_name, level, status, start_time, end_time, duration_ms, run_id, tool_call_id, model_name, provider, prompt_tokens, completion_tokens, total_tokens, cost_usd, user_id, session_id, channel_id, created_at, updated_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, CAST(? AS TIMESTAMP), CAST(? AS TIMESTAMP), ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, CAST(? AS TIMESTAMP), CAST(? AS TIMESTAMP))
       ON CONFLICT (observation_id) DO UPDATE SET
+        organization_id = CASE WHEN EXCLUDED.organization_id != '' THEN EXCLUDED.organization_id ELSE oc_observations_core.organization_id END,
+        scope_id = CASE WHEN EXCLUDED.scope_id != '' THEN EXCLUDED.scope_id ELSE oc_observations_core.scope_id END,
+        environment = CASE WHEN EXCLUDED.environment != '' THEN EXCLUDED.environment ELSE oc_observations_core.environment END,
         parent_observation_id = COALESCE(oc_observations_core.parent_observation_id, EXCLUDED.parent_observation_id),
         root_observation_id = EXCLUDED.root_observation_id,
         level = EXCLUDED.level,
@@ -871,13 +935,16 @@ class DuckDBLocalWriter {
     `;
         const eventSql = `
       INSERT INTO oc_events_raw
-        (event_id, trace_id, observation_id, event_type, event_name, event_time, run_id, payload_json, created_at)
-      VALUES (?, ?, ?, ?, ?, CAST(? AS TIMESTAMP), ?, ?, CAST(? AS TIMESTAMP))
+        (event_id, organization_id, scope_id, environment, trace_id, observation_id, event_type, event_name, event_time, run_id, payload_json, created_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, CAST(? AS TIMESTAMP), ?, ?, CAST(? AS TIMESTAMP))
       ON CONFLICT (event_id) DO NOTHING
     `;
         for (const t of batch.traces) {
             await this.pool.run(traceSql, [
                 t.traceId,
+                t.organizationId || 'local',
+                t.scopeId || 'local',
+                t.environment || 'prod',
                 t.sessionId,
                 t.userId,
                 t.channelId,
@@ -894,6 +961,9 @@ class DuckDBLocalWriter {
         for (const o of batch.observations) {
             await this.pool.run(obsSql, [
                 o.observationId,
+                o.organizationId || 'local',
+                o.scopeId || 'local',
+                o.environment || 'prod',
                 o.traceId,
                 o.parentObservationId,
                 o.rootObservationId,
@@ -934,6 +1004,9 @@ class DuckDBLocalWriter {
         for (const e of batch.events) {
             await this.pool.run(eventSql, [
                 e.eventId,
+                e.organizationId || 'local',
+                e.scopeId || 'local',
+                e.environment || 'prod',
                 e.traceId,
                 e.observationId,
                 e.eventType,
@@ -951,7 +1024,7 @@ class DuckDBLocalWriter {
         try {
             const [legacyRows] = await this.pool.query(`SELECT session_id, action_type, action_name, model_name, input_params, output_result,
                 prompt_tokens, completion_tokens, duration_ms, user_id, channel_id, created_at
-         FROM audit_actions a
+         FROM observation_actions a
          WHERE NOT EXISTS (
            SELECT 1
            FROM oc_observations_core c
@@ -992,7 +1065,7 @@ class DuckDBLocalWriter {
                 };
             });
             await this.writeStructured(actions);
-            console.log(`[openclaw-observability] Backfilled structured observations from legacy audit_actions: ${actions.length}`);
+            console.log(`[openclaw-observability] Backfilled structured observations from legacy observation_actions: ${actions.length}`);
         }
         catch (error) {
             console.warn('[openclaw-observability] Structured backfill skipped:', error.message);
@@ -1002,7 +1075,7 @@ class DuckDBLocalWriter {
         if (!this.pool || alerts.length === 0)
             return;
         const sql = `
-      INSERT INTO audit_alerts
+      INSERT INTO observation_alerts
         (id, alert_id, session_id, action_type, action_name, rule_id, rule_name,
          category, severity, finding, context, status, user_id, model_name, created_at)
       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
@@ -1140,6 +1213,7 @@ class DuckDBLocalWriter {
             await this.pool.close();
             this.pool = null;
             this.initialized = false;
+            this.startupMaintenanceDone = false;
             console.log('[openclaw-observability] DuckDB writer closed (checkpoint done)');
         }
     }
@@ -1202,23 +1276,98 @@ class DuckDBLocalWriter {
     async _ensureChannelIdColumn(tableName) {
         if (!this.pool)
             return;
-        const exists = await this._hasColumn(tableName, 'channel_id');
-        if (exists)
-            return; // Column exists, no action needed
         try {
-            await this.pool.run(`ALTER TABLE ${tableName} ADD COLUMN channel_id VARCHAR(128) DEFAULT ''`);
-            // Only log when actually adding the column (silent if already exists)
+            // Do not rely on _hasColumn() for old DB variants; make DDL idempotent.
+            await this.pool.run(`ALTER TABLE ${tableName} ADD COLUMN IF NOT EXISTS channel_id VARCHAR(128) DEFAULT ''`);
         }
         catch (err) {
             const errMsg = err.message || String(err);
-            // If column already exists, that's fine (silent success)
-            if (errMsg.includes('already exists') || errMsg.includes('duplicate column')) {
-                return; // Column exists, no action needed
-            }
             // Other errors should be logged
             console.warn(`[openclaw-observability] Failed to ensure channel_id in ${tableName}:`, errMsg);
         }
     }
+    async _ensureActionRunLineageColumns() {
+        if (!this.pool)
+            return;
+        try {
+            await this.pool.run(`ALTER TABLE observation_actions ADD COLUMN IF NOT EXISTS run_id VARCHAR(128) DEFAULT ''`);
+            await this.pool.run(`ALTER TABLE observation_actions ADD COLUMN IF NOT EXISTS parent_run_id VARCHAR(128) DEFAULT ''`);
+            await this.pool.run(`UPDATE observation_actions
+         SET run_id = ''
+         WHERE run_id IS NULL`);
+            await this.pool.run(`UPDATE observation_actions
+         SET parent_run_id = ''
+         WHERE parent_run_id IS NULL`);
+        }
+        catch (err) {
+            const errMsg = err.message || String(err);
+            console.warn('[openclaw-observability] Failed to ensure run lineage columns:', errMsg);
+        }
+        if (!(await this._hasIndex('observation_actions', 'idx_act_run_id'))) {
+            try {
+                await this.pool.run(`CREATE INDEX idx_act_run_id ON observation_actions(run_id)`);
+            }
+            catch (err) {
+                const errMsg = err.message || String(err);
+                if (!errMsg.includes('already exists')) {
+                    console.warn('[openclaw-observability] Failed to create idx_act_run_id:', errMsg);
+                }
+            }
+        }
+        if (!(await this._hasIndex('observation_actions', 'idx_act_parent_run_id'))) {
+            try {
+                await this.pool.run(`CREATE INDEX idx_act_parent_run_id ON observation_actions(parent_run_id)`);
+            }
+            catch (err) {
+                const errMsg = err.message || String(err);
+                if (!errMsg.includes('already exists')) {
+                    console.warn('[openclaw-observability] Failed to create idx_act_parent_run_id:', errMsg);
+                }
+            }
+        }
+    }
+    async _ensureColumn(tableName, columnName, columnDef) {
+        if (!this.pool)
+            return;
+        try {
+            // Do not rely on _hasColumn() for old DB variants; make DDL idempotent.
+            await this.pool.run(`ALTER TABLE ${tableName} ADD COLUMN IF NOT EXISTS ${columnName} ${columnDef}`);
+        }
+        catch (err) {
+            const errMsg = err.message || String(err);
+            if (!errMsg.includes('already exists') && !errMsg.includes('duplicate column')) {
+                console.warn(`[openclaw-observability] Failed to add ${columnName} to ${tableName}:`, errMsg);
+            }
+        }
+    }
+    /**
+     * Ensure a tenant-related column exists and legacy rows are backfilled.
+     * This keeps old local DuckDB files compatible with new project-scoped queries.
+     */
+    async _ensureTenantColumn(tableName, columnName, columnDef, defaultValue) {
+        if (!this.pool)
+            return;
+        try {
+            // Do not rely on _hasColumn() for old DB variants; make DDL idempotent.
+            await this.pool.run(`ALTER TABLE ${tableName} ADD COLUMN IF NOT EXISTS ${columnName} ${columnDef}`);
+        }
+        catch (err) {
+            const errMsg = err.message || String(err);
+            if (!errMsg.includes('already exists') && !errMsg.includes('duplicate column')) {
+                console.warn(`[openclaw-observability] Failed to add ${columnName} to ${tableName}:`, errMsg);
+                return;
+            }
+        }
+        try {
+            await this.pool.run(`UPDATE ${tableName}
+         SET ${columnName} = ?
+         WHERE ${columnName} IS NULL OR CAST(${columnName} AS VARCHAR) = ''`, [defaultValue]);
+        }
+        catch (err) {
+            const errMsg = err.message || String(err);
+            console.warn(`[openclaw-observability] Failed to backfill ${columnName} in ${tableName}:`, errMsg);
+        }
+    }
     _formatDate(d) {
         if (!d)
             return this._formatTimestamp(new Date());
@@ -1233,6 +1382,37 @@ class DuckDBLocalWriter {
             return this._formatTimestamp(d);
         return String(d);
     }
+    async runStartupMaintenance() {
+        if (this.startupMaintenanceDone)
+            return;
+        await this._cleanupExpiredDataOnStartup();
+        this.startupMaintenanceDone = true;
+    }
+    async _cleanupExpiredDataOnStartup() {
+        if (!this.pool || this.dataRetentionDays <= 0)
+            return;
+        const cutoffDate = new Date(Date.now() - this.dataRetentionDays * 24 * 60 * 60 * 1000);
+        const cutoffText = this._formatDate(cutoffDate);
+        const cutoffMs = cutoffDate.getTime();
+        await this.pool.run('DELETE FROM observation_alerts WHERE created_at < ?', [cutoffText]);
+        await this.pool.run('DELETE FROM observation_actions WHERE created_at < ?', [cutoffText]);
+        await this.pool.run('DELETE FROM observation_sessions WHERE COALESCE(end_time, start_time) < ?', [cutoffText]);
+        await this.pool.run('DELETE FROM oc_events_raw WHERE event_time < ?', [cutoffText]);
+        await this.pool.run(`DELETE FROM oc_observations_payload
+        WHERE observation_id IN (
+          SELECT observation_id
+            FROM oc_observations_core
+           WHERE COALESCE(end_time, start_time, created_at) < ?
+        )`, [cutoffText]);
+        await this.pool.run('DELETE FROM oc_observations_core WHERE COALESCE(end_time, start_time, created_at) < ?', [cutoffText]);
+        await this.pool.run('DELETE FROM oc_traces WHERE COALESCE(end_time, start_time, created_at) < ?', [cutoffText]);
+        await this.pool.run('DELETE FROM observability_metrics_samples WHERE sample_timestamp_ms < ?', [cutoffMs]);
+        await this.pool.run('DELETE FROM oc_metric_points_number WHERE ts_ms < ?', [cutoffMs]);
+        await this.pool.run('DELETE FROM oc_metric_points_histogram WHERE ts_ms < ?', [cutoffMs]);
+        await this.pool.run('DELETE FROM oc_metric_series WHERE last_seen_ms < ?', [cutoffMs]);
+        await this.pool.run('DELETE FROM oc_observations_payload WHERE observation_id NOT IN (SELECT observation_id FROM oc_observations_core)');
+        console.log(`[openclaw-observability] Startup data retention cleanup completed for DuckDB (days=${this.dataRetentionDays}, cutoff=${cutoffDate.toISOString()})`);
+    }
     _formatTimestamp(d) {
         return d.toISOString().replace('T', ' ').replace('Z', '');
     }