monora-ai 2.1.0 → 2.1.4

package/dist/oversight.js

@@ -0,0 +1,497 @@
+"use strict";
+/**
+ * Human oversight tracking for EU AI Act Art.14 and ISO 42001 8.3 compliance.
+ *
+ * This module provides human review and override tracking for AI decisions,
+ * supporting EU AI Act Article 14 human oversight requirements and ISO 42001
+ * control 8.3.
+ *
+ * Cross-SDK Parity:
+ *   Both Python and Node.js SDKs provide identical human oversight APIs:
+ *   - recordHumanReview() / record_human_review()
+ *   - recordHumanOverride() / record_human_override()
+ *   - getPendingReviews() / get_pending_reviews()
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SqliteReviewStore = exports.MemoryReviewStore = void 0;
+exports.reviewToEventBody = reviewToEventBody;
+exports.overrideToEventBody = overrideToEventBody;
+exports.setReviewStore = setReviewStore;
+exports.recordHumanReview = recordHumanReview;
+exports.recordHumanOverride = recordHumanOverride;
+exports.requireReview = requireReview;
+exports.getPendingReviews = getPendingReviews;
+exports.getTimedOutReviews = getTimedOutReviews;
+exports.checkReviewRequired = checkReviewRequired;
+exports.getOversightSummary = getOversightSummary;
+exports.clearOversightData = clearOversightData;
+const crypto = __importStar(require("crypto"));
+/**
+ * Convert HumanReview to event body dictionary.
+ */
+function reviewToEventBody(review) {
+    const body = {
+        reviewed_event_id: review.reviewedEventId,
+        reviewer_id: review.reviewerId,
+        review_type: review.reviewType,
+        decision: review.decision,
+        timestamp: review.timestamp,
+    };
+    if (review.modifications) {
+        body.modifications = review.modifications;
+    }
+    if (review.reviewDurationMs !== undefined) {
+        body.review_duration_ms = review.reviewDurationMs;
+    }
+    if (review.reviewNotes) {
+        body.review_notes = review.reviewNotes;
+    }
+    if (review.complianceFlags.length > 0) {
+        body.compliance_flags = review.complianceFlags;
+    }
+    return body;
+}
+/**
+ * Convert HumanOverride to event body dictionary.
+ */
+function overrideToEventBody(override) {
+    const body = {
+        overridden_event_id: override.overriddenEventId,
+        override_reason: override.overrideReason,
+        timestamp: override.timestamp,
+    };
+    if (override.originalOutputHash) {
+        body.original_output_hash = override.originalOutputHash;
+    }
+    if (override.correctedOutputHash) {
+        body.corrected_output_hash = override.correctedOutputHash;
+    }
+    if (override.overrideAuthority) {
+        body.override_authority = override.overrideAuthority;
+    }
+    return body;
+}
+const DEFAULT_COMPLETED_REVIEW_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+/**
+ * In-memory store for oversight reviews.
+ *
+ * Note: This is single-instance only. For production/distributed use, supply
+ * a persistent store via setReviewStore (e.g., SqliteReviewStore or Redis).
+ */
+class MemoryReviewStore {
+    constructor(options) {
+        this.pendingReviews = new Map();
+        this.completedReviews = [];
+        this.overrides = [];
+        this.completedTtlMs = options?.completedTtlMs ?? DEFAULT_COMPLETED_REVIEW_TTL_MS;
+    }
+    addPendingReview(review) {
+        this.pendingReviews.set(review.eventId, review);
+    }
+    removePendingReview(eventId) {
+        this.pendingReviews.delete(eventId);
+    }
+    listPendingReviews() {
+        return Array.from(this.pendingReviews.values());
+    }
+    listTimedOutReviews(now) {
+        return this.listPendingReviews().filter((review) => review.timeoutAt < now);
+    }
+    addCompletedReview(review) {
+        this.pruneCompletedReviews(Date.now());
+        this.completedReviews.push(review);
+    }
+    listCompletedReviews() {
+        this.pruneCompletedReviews(Date.now());
+        return [...this.completedReviews];
+    }
+    addOverride(override) {
+        this.overrides.push(override);
+    }
+    listOverrides() {
+        return [...this.overrides];
+    }
+    clear() {
+        this.pendingReviews.clear();
+        this.completedReviews = [];
+        this.overrides = [];
+    }
+    pruneCompletedReviews(now) {
+        if (this.completedTtlMs <= 0) {
+            return;
+        }
+        const cutoff = now - this.completedTtlMs;
+        this.completedReviews = this.completedReviews.filter((review) => {
+            const timestampMs = Date.parse(review.timestamp);
+            if (Number.isNaN(timestampMs)) {
+                return true;
+            }
+            return timestampMs >= cutoff;
+        });
+    }
+}
+exports.MemoryReviewStore = MemoryReviewStore;
+/**
+ * SQLite-backed persistent review store (requires better-sqlite3).
+ */
+class SqliteReviewStore {
+    constructor(dbPath, options) {
+        let Database;
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            Database = require('better-sqlite3');
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`SqliteReviewStore requires better-sqlite3. ${message}`);
+        }
+        this.db = new Database(dbPath);
+        this.completedTtlMs = options?.completedTtlMs ?? DEFAULT_COMPLETED_REVIEW_TTL_MS;
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS pending_reviews (
+        event_id TEXT PRIMARY KEY,
+        trace_id TEXT,
+        event_type TEXT,
+        model TEXT,
+        risk_level TEXT,
+        created_at INTEGER,
+        timeout_at INTEGER
+      );
+      CREATE TABLE IF NOT EXISTS completed_reviews (
+        reviewed_event_id TEXT,
+        reviewer_id TEXT,
+        review_type TEXT,
+        decision TEXT,
+        modifications TEXT,
+        review_duration_ms INTEGER,
+        review_notes TEXT,
+        compliance_flags TEXT,
+        timestamp TEXT,
+        timestamp_ms INTEGER
+      );
+      CREATE TABLE IF NOT EXISTS overrides (
+        overridden_event_id TEXT,
+        override_reason TEXT,
+        original_output_hash TEXT,
+        corrected_output_hash TEXT,
+        override_authority TEXT,
+        timestamp TEXT
+      );
+    `);
+    }
+    addPendingReview(review) {
+        this.db.prepare(`
+      INSERT OR REPLACE INTO pending_reviews
+      (event_id, trace_id, event_type, model, risk_level, created_at, timeout_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+    `).run(review.eventId, review.traceId ?? null, review.eventType, review.model ?? null, review.riskLevel ?? null, review.createdAt, review.timeoutAt);
+    }
+    removePendingReview(eventId) {
+        this.db.prepare('DELETE FROM pending_reviews WHERE event_id = ?').run(eventId);
+    }
+    listPendingReviews() {
+        const rows = this.db.prepare('SELECT * FROM pending_reviews').all();
+        return rows.map((row) => ({
+            eventId: row.event_id,
+            traceId: row.trace_id ?? undefined,
+            eventType: row.event_type,
+            model: row.model ?? undefined,
+            riskLevel: row.risk_level ?? undefined,
+            createdAt: row.created_at,
+            timeoutAt: row.timeout_at,
+        }));
+    }
+    listTimedOutReviews(now) {
+        const rows = this.db
+            .prepare('SELECT * FROM pending_reviews WHERE timeout_at < ?')
+            .all(now);
+        return rows.map((row) => ({
+            eventId: row.event_id,
+            traceId: row.trace_id ?? undefined,
+            eventType: row.event_type,
+            model: row.model ?? undefined,
+            riskLevel: row.risk_level ?? undefined,
+            createdAt: row.created_at,
+            timeoutAt: row.timeout_at,
+        }));
+    }
+    addCompletedReview(review) {
+        const timestampMs = Date.parse(review.timestamp);
+        this.db.prepare(`
+      INSERT INTO completed_reviews
+      (reviewed_event_id, reviewer_id, review_type, decision, modifications, review_duration_ms,
+       review_notes, compliance_flags, timestamp, timestamp_ms)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(review.reviewedEventId, review.reviewerId, review.reviewType, review.decision, review.modifications ?? null, review.reviewDurationMs ?? null, review.reviewNotes ?? null, JSON.stringify(review.complianceFlags || []), review.timestamp, Number.isNaN(timestampMs) ? null : timestampMs);
+        this.pruneCompletedReviews(Date.now());
+    }
+    listCompletedReviews() {
+        this.pruneCompletedReviews(Date.now());
+        const rows = this.db.prepare('SELECT * FROM completed_reviews').all();
+        return rows.map((row) => ({
+            reviewedEventId: row.reviewed_event_id,
+            reviewerId: row.reviewer_id,
+            reviewType: row.review_type,
+            decision: row.decision,
+            modifications: row.modifications ?? undefined,
+            reviewDurationMs: row.review_duration_ms ?? undefined,
+            reviewNotes: row.review_notes ?? undefined,
+            complianceFlags: this.parseComplianceFlags(row.compliance_flags),
+            timestamp: row.timestamp,
+        }));
+    }
+    addOverride(override) {
+        this.db.prepare(`
+      INSERT INTO overrides
+      (overridden_event_id, override_reason, original_output_hash, corrected_output_hash,
+       override_authority, timestamp)
+      VALUES (?, ?, ?, ?, ?, ?)
+    `).run(override.overriddenEventId, override.overrideReason, override.originalOutputHash ?? null, override.correctedOutputHash ?? null, override.overrideAuthority ?? null, override.timestamp);
+    }
+    listOverrides() {
+        const rows = this.db.prepare('SELECT * FROM overrides').all();
+        return rows.map((row) => ({
+            overriddenEventId: row.overridden_event_id,
+            overrideReason: row.override_reason,
+            originalOutputHash: row.original_output_hash ?? undefined,
+            correctedOutputHash: row.corrected_output_hash ?? undefined,
+            overrideAuthority: row.override_authority ?? undefined,
+            timestamp: row.timestamp,
+        }));
+    }
+    clear() {
+        this.db.exec('DELETE FROM pending_reviews; DELETE FROM completed_reviews; DELETE FROM overrides;');
+    }
+    pruneCompletedReviews(now) {
+        if (this.completedTtlMs <= 0) {
+            return;
+        }
+        const cutoff = now - this.completedTtlMs;
+        this.db.prepare('DELETE FROM completed_reviews WHERE timestamp_ms IS NOT NULL AND timestamp_ms < ?')
+            .run(cutoff);
+    }
+    parseComplianceFlags(value) {
+        if (!value) {
+            return [];
+        }
+        try {
+            const parsed = JSON.parse(value);
+            return Array.isArray(parsed) ? parsed : [];
+        }
+        catch {
+            return [];
+        }
+    }
+}
+exports.SqliteReviewStore = SqliteReviewStore;
+let reviewStore = new MemoryReviewStore();
+function setReviewStore(store) {
+    reviewStore = store;
+}
+/**
+ * Record a human review of an AI decision.
+ *
+ * @param reviewedEventId - ID of the event being reviewed.
+ * @param reviewerId - ID of the human reviewer.
+ * @param reviewType - Type of review (approval, rejection, modification, escalation).
+ * @param decision - Review decision (approved, rejected, modified, escalated).
+ * @param options - Additional options.
+ * @returns The created HumanReview.
+ *
+ * @example
+ * ```typescript
+ * recordHumanReview(
+ *   'evt_123',
+ *   'usr_456',
+ *   'approval',
+ *   'approved',
+ *   { notes: 'Verified output accuracy' }
+ * );
+ * ```
+ */
+function recordHumanReview(reviewedEventId, reviewerId, reviewType, decision, options = {}) {
+    const review = {
+        reviewedEventId,
+        reviewerId,
+        reviewType,
+        decision,
+        modifications: options.modifications,
+        reviewDurationMs: options.reviewDurationMs,
+        reviewNotes: options.notes,
+        complianceFlags: options.complianceFlags || [],
+        timestamp: new Date().toISOString(),
+    };
+    reviewStore.addCompletedReview(review);
+    reviewStore.removePendingReview(reviewedEventId);
+    return review;
+}
+/**
+ * Record a human override of an AI output.
+ *
+ * @param overriddenEventId - ID of the event being overridden.
+ * @param overrideReason - Reason for the override.
+ * @param options - Additional options.
+ * @returns The created HumanOverride.
+ *
+ * @example
+ * ```typescript
+ * recordHumanOverride(
+ *   'evt_123',
+ *   'Incorrect recommendation',
+ *   { overrideAuthority: 'supervisor' }
+ * );
+ * ```
+ */
+function recordHumanOverride(overriddenEventId, overrideReason, options = {}) {
+    let originalHash;
+    let correctedHash;
+    if (options.originalOutput) {
+        const hash = crypto.createHash('sha256').update(options.originalOutput).digest('hex');
+        originalHash = `sha256:${hash}`;
+    }
+    if (options.correctedOutput) {
+        const hash = crypto.createHash('sha256').update(options.correctedOutput).digest('hex');
+        correctedHash = `sha256:${hash}`;
+    }
+    const override = {
+        overriddenEventId,
+        overrideReason,
+        originalOutputHash: originalHash,
+        correctedOutputHash: correctedHash,
+        overrideAuthority: options.overrideAuthority,
+        timestamp: new Date().toISOString(),
+    };
+    reviewStore.addOverride(override);
+    return override;
+}
+/**
+ * Mark an event as requiring human review.
+ *
+ * @param eventId - ID of the event requiring review.
+ * @param options - Additional options.
+ * @returns The created PendingReview.
+ */
+function requireReview(eventId, options = {}) {
+    const config = options.config || {};
+    const oversightConfig = config.human_oversight || {};
+    const timeoutHours = oversightConfig.review_timeout_hours ?? 24;
+    const now = Date.now();
+    const pending = {
+        eventId,
+        traceId: options.traceId,
+        eventType: options.eventType || 'llm_call',
+        model: options.model,
+        riskLevel: options.riskLevel,
+        createdAt: now,
+        timeoutAt: now + timeoutHours * 3600 * 1000,
+    };
+    reviewStore.addPendingReview(pending);
+    return pending;
+}
+/**
+ * Get all events pending human review.
+ */
+function getPendingReviews() {
+    return reviewStore.listPendingReviews();
+}
+/**
+ * Get reviews that have timed out.
+ */
+function getTimedOutReviews() {
+    return reviewStore.listTimedOutReviews(Date.now());
+}
+/**
+ * Check if an event requires human review based on config.
+ *
+ * @param eventType - Type of event.
+ * @param model - Model used.
+ * @param riskLevel - Risk level of the event.
+ * @param config - Optional config.
+ * @returns True if review is required.
+ */
+function checkReviewRequired(eventType, model, riskLevel, config) {
+    const oversightConfig = config?.human_oversight;
+    if (!oversightConfig?.enabled) {
+        return false;
+    }
+    const requireFor = oversightConfig.require_review_for || [];
+    if (requireFor.length === 0) {
+        return false;
+    }
+    for (const condition of requireFor) {
+        if (condition.risk_level && riskLevel !== condition.risk_level) {
+            continue;
+        }
+        if (condition.event_type && eventType !== condition.event_type) {
+            continue;
+        }
+        if (condition.tool_name && model !== condition.tool_name) {
+            continue;
+        }
+        return true;
+    }
+    return false;
+}
+/**
+ * Get summary of human oversight for reporting.
+ *
+ * @returns Summary dict for compliance reports.
+ */
+function getOversightSummary() {
+    const completed = reviewStore.listCompletedReviews();
+    const pending = reviewStore.listPendingReviews();
+    const overrides = reviewStore.listOverrides();
+    const timedOut = reviewStore.listTimedOutReviews(Date.now());
+    const reviewTimes = completed
+        .filter((r) => r.reviewDurationMs !== undefined)
+        .map((r) => r.reviewDurationMs);
+    const avgReviewTime = reviewTimes.length > 0
+        ? reviewTimes.reduce((a, b) => a + b, 0) / reviewTimes.length
+        : null;
+    return {
+        reviews_completed: completed.length,
+        reviews_pending: pending.length,
+        overrides: overrides.length,
+        average_review_time_ms: avgReviewTime,
+        timed_out_reviews: timedOut.length,
+    };
+}
+/**
+ * Clear all oversight tracking data.
+ */
+function clearOversightData() {
+    reviewStore.clear();
+}

package/dist/presets.js

@@ -63,7 +63,7 @@ exports.DEVELOPMENT = {
             telemetry: {
                 enabled: false,
                 send_data: false,
-                data_residency: 'none',
+                data_residency: null,
             },
         },
     },
@@ -110,7 +110,7 @@ exports.POC = {
             telemetry: {
                 enabled: false,
                 send_data: false,
-                data_residency: 'none',
+                data_residency: null,
             },
         },
     },
@@ -161,7 +161,7 @@ exports.PRODUCTION = {
             environment: 'production',
             data_classification: 'confidential',
         },
-        sinks: [{ type: 'file', path: './monora_events.jsonl', rotation: 'daily' }],
+        sinks: [{ type: 'file', path: './monora_events.jsonl', rotation: 'daily', symlink: true }],
         immutability: {
             enabled: true,
             scope: 'per_trace',
@@ -202,7 +202,7 @@ exports.STRICT_ENTERPRISE = {
             environment: 'production',
             data_classification: 'restricted',
         },
-        sinks: [{ type: 'file', path: './monora_events.jsonl', rotation: 'daily' }],
+        sinks: [{ type: 'file', path: './monora_events.jsonl', rotation: 'daily', symlink: true }],
         immutability: {
             enabled: true,
             scope: 'per_trace',
@@ -328,7 +328,7 @@ exports.AUDIT_FIRST = {
             environment: 'production',
             data_classification: 'restricted',
         },
-        sinks: [{ type: 'file', path: './monora_events.jsonl', rotation: 'daily' }],
+        sinks: [{ type: 'file', path: './monora_events.jsonl', rotation: 'daily', symlink: true }],
         immutability: {
             enabled: true,
             scope: 'per_trace',
@@ -363,7 +363,7 @@ exports.AUDIT_FIRST = {
             telemetry: {
                 enabled: false,
                 send_data: false,
-                data_residency: 'none',
+                data_residency: null,
             },
         },
     },
@@ -506,7 +506,7 @@ function deepMerge(base, updates) {
             deepMerge(base[key], updates[key]);
         }
         else {
-            base[key] = updates[key];
+            base[key] = deepClone(updates[key]);
         }
     }
 }