seal-gate 0.3.0

package/src/drift/drift-db.ts

@@ -0,0 +1,281 @@
+import { createRequire } from 'node:module';
+import { join } from 'path';
+import { homedir } from 'os';
+
+// node:sqlite on Node (production), bun:sqlite on Bun (dev/test).
+interface SqliteStatement {
+  get(...params: unknown[]): Record<string, unknown> | undefined;
+  all(...params: unknown[]): Record<string, unknown>[];
+  run(...params: unknown[]): { changes: number; lastInsertRowid: number | bigint };
+}
+interface SqliteDatabase {
+  exec(sql: string): void;
+  prepare(sql: string): SqliteStatement;
+  close(): void;
+}
+const _require = createRequire(import.meta.url);
+const isBun = typeof (globalThis as Record<string, unknown>).Bun !== 'undefined';
+const DatabaseSync: new (path: string) => SqliteDatabase = isBun
+  ? _require('bun:sqlite').Database
+  : _require('node:sqlite').DatabaseSync;
+
+export interface DriftBaselineRow {
+  agent_id: string;
+  baseline_vector: string; // JSON array
+  content_hash: string;
+  embedding_model: string;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface DriftHistoryRow {
+  id: number;
+  agent_id: string;
+  session_id: string;
+  turn_number: number;
+  current_vector: string; // JSON array
+  distance: number;
+  status: string;
+  re_anchor_id: number | null;
+  timestamp: string;
+}
+
+export interface PendingReAnchorRow {
+  id: number;
+  agent_id: string;
+  session_id: string;
+  payload: string;
+  created_at: string;
+  status: 'PENDING' | 'CONSUMED' | 'EXPIRED';
+  consumed_at: string | null;
+}
+
+export interface DriftRepairLogRow {
+  id: number;
+  agent_id: string;
+  session_id: string;
+  turn_number: number;
+  distance: number;
+  hard_limit: number;
+  message_excerpt: string;
+  triggered_at: string;
+  human_review_flag: 'PENDING' | 'REVIEWED' | 'IGNORED';
+  recovery_status: 'UNKNOWN' | 'RECOVERED' | 'PERSISTENT_DRIFT';
+  notes: string | null;
+}
+export class DriftDb {
+  private db: SqliteDatabase;
+
+  constructor(dbPath?: string) {
+    const path =
+      dbPath ?? join(homedir(), '.seal', 'drift.db');
+    this.db = new DatabaseSync(path);
+    this.db.exec('PRAGMA journal_mode = WAL;');
+    this.initSchema();
+  }
+
+  private initSchema(): void {
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS drift_baseline (
+        agent_id TEXT PRIMARY KEY,
+        baseline_vector TEXT NOT NULL,
+        content_hash TEXT NOT NULL,
+        embedding_model TEXT NOT NULL,
+        created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+        updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
+      );
+
+      CREATE TABLE IF NOT EXISTS drift_history (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        agent_id TEXT NOT NULL,
+        session_id TEXT NOT NULL,
+        turn_number INTEGER NOT NULL,
+        current_vector TEXT,
+        distance REAL,
+        status TEXT NOT NULL,
+        re_anchor_id INTEGER,
+        timestamp DATETIME DEFAULT CURRENT_TIMESTAMP
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_history_agent_session
+        ON drift_history(agent_id, session_id);
+
+      CREATE TABLE IF NOT EXISTS pending_re_anchor (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        agent_id TEXT NOT NULL,
+        session_id TEXT NOT NULL,
+        payload TEXT NOT NULL,
+        created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+        status TEXT DEFAULT 'PENDING',
+        consumed_at DATETIME
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_reanchor_pending
+        ON pending_re_anchor(agent_id, session_id, status);
+
+      CREATE TABLE IF NOT EXISTS drift_repair_log (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        agent_id TEXT NOT NULL,
+        session_id TEXT NOT NULL,
+        turn_number INTEGER NOT NULL,
+        distance REAL NOT NULL,
+        hard_limit REAL NOT NULL,
+        message_excerpt TEXT,
+        triggered_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+        human_review_flag TEXT DEFAULT 'PENDING',
+        recovery_status TEXT DEFAULT 'UNKNOWN',
+        notes TEXT
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_repair_pending
+        ON drift_repair_log(agent_id, human_review_flag);
+    `);
+  }
+
+  // ── Baseline CRUD ────────────────────────────────────────────────
+
+  baseline = {
+    get: (agentId: string): DriftBaselineRow | null => {
+      const stmt = this.db.prepare('SELECT * FROM drift_baseline WHERE agent_id = ?');
+      return (stmt.get(agentId) as DriftBaselineRow | undefined) ?? null;
+    },
+
+    set: (
+      agentId: string,
+      vector: number[],
+      hash: string,
+      model: string
+    ): void => {
+      const stmt = this.db.prepare(
+        `INSERT INTO drift_baseline (agent_id, baseline_vector, content_hash, embedding_model)
+         VALUES (?, ?, ?, ?)
+         ON CONFLICT(agent_id) DO UPDATE SET
+           baseline_vector = excluded.baseline_vector,
+           content_hash = excluded.content_hash,
+           embedding_model = excluded.embedding_model,
+           updated_at = CURRENT_TIMESTAMP`
+      );
+      stmt.run(agentId, JSON.stringify(vector), hash, model);
+    },
+  };
+
+  // ── History CRUD ─────────────────────────────────────────────────
+
+  history = {
+    append: (row: {
+      agent_id: string;
+      session_id: string;
+      turn_number: number;
+      current_vector: number[];
+      distance: number;
+      status: string;
+      timestamp: string;
+    }): void => {
+      const stmt = this.db.prepare(
+        `INSERT INTO drift_history
+         (agent_id, session_id, turn_number, current_vector, distance, status, timestamp)
+         VALUES (?, ?, ?, ?, ?, ?, ?)`
+      );
+      stmt.run(
+        row.agent_id,
+        row.session_id,
+        row.turn_number,
+        JSON.stringify(row.current_vector),
+        row.distance,
+        row.status,
+        row.timestamp
+      );
+    },
+
+    list: (agentId: string, sessionId: string): DriftHistoryRow[] => {
+      const stmt = this.db.prepare(
+        'SELECT * FROM drift_history WHERE agent_id = ? AND session_id = ? ORDER BY turn_number'
+      );
+      return stmt.all(agentId, sessionId) as unknown as DriftHistoryRow[];
+    },
+
+    getLatest: (agentId: string, sessionId: string): DriftHistoryRow | null => {
+      const stmt = this.db.prepare(
+        `SELECT * FROM drift_history
+         WHERE agent_id = ? AND session_id = ?
+         ORDER BY turn_number DESC LIMIT 1`
+      );
+      return (stmt.get(agentId, sessionId) as DriftHistoryRow | undefined) ?? null;
+    },
+  };
+
+  // ── Pending Re-Anchor CRUD ───────────────────────────────────────
+
+  pending = {
+    set: (agentId: string, sessionId: string, payload: string): number => {
+      const stmt = this.db.prepare(
+        `INSERT INTO pending_re_anchor (agent_id, session_id, payload, status)
+         VALUES (?, ?, ?, 'PENDING')`
+      );
+      const result = stmt.run(agentId, sessionId, payload);
+      return Number(result.lastInsertRowid);
+    },
+
+    getPending: (
+      agentId: string,
+      sessionId: string
+    ): PendingReAnchorRow | null => {
+      const stmt = this.db.prepare(
+        `SELECT * FROM pending_re_anchor
+         WHERE agent_id = ? AND session_id = ? AND status = 'PENDING'
+         ORDER BY created_at DESC LIMIT 1`
+      );
+      return (stmt.get(agentId, sessionId) as PendingReAnchorRow | undefined) ?? null;
+    },
+
+    markConsumed: (id: number): void => {
+      const stmt = this.db.prepare(
+        `UPDATE pending_re_anchor
+         SET status = 'CONSUMED', consumed_at = CURRENT_TIMESTAMP
+         WHERE id = ?`
+      );
+      stmt.run(id);
+    },
+  };
+
+  // ── Repair Log CRUD ──────────────────────────────────────────────
+
+  repair = {
+    append: (row: {
+      agent_id: string;
+      session_id: string;
+      turn_number: number;
+      distance: number;
+      hard_limit: number;
+      message_excerpt?: string;
+    }): number => {
+      const stmt = this.db.prepare(
+        `INSERT INTO drift_repair_log
+         (agent_id, session_id, turn_number, distance, hard_limit, message_excerpt)
+         VALUES (?, ?, ?, ?, ?, ?)`
+      );
+      const result = stmt.run(
+        row.agent_id,
+        row.session_id,
+        row.turn_number,
+        row.distance,
+        row.hard_limit,
+        row.message_excerpt ?? null
+      );
+      return Number(result.lastInsertRowid);
+    },
+
+    listPending: (agentId: string): DriftRepairLogRow[] => {
+      const stmt = this.db.prepare(
+        `SELECT * FROM drift_repair_log
+         WHERE agent_id = ? AND human_review_flag = 'PENDING'
+         ORDER BY triggered_at`
+      );
+      return stmt.all(agentId) as unknown as DriftRepairLogRow[];
+    },
+  };
+
+  close(): void {
+    this.db.close();
+  }
+}

package/src/drift/drift-guard.ts

@@ -0,0 +1,145 @@
+import { DriftDb } from './drift-db.js';
+import { BaselineManager } from './baseline.js';
+import { Embedder, cosineDistance } from './embedder.js';
+import { Quarantine } from './quarantine.js';
+import { SoftCorrection } from './soft-correction.js';
+
+export type DriftStatus = 'NORMAL' | 'SOFT_DRIFT' | 'HARD_DRIFT';
+
+export interface DriftAction {
+  type: 'NONE' | 'INJECT_RE_ANCHOR' | 'QUARANTINE' | 'FULL_SOUL_RELOAD';
+  payload?: string;
+}
+
+export interface DriftResult {
+  status: DriftStatus;
+  distance: number;
+  action: DriftAction;
+  softLimit: number;
+  hardLimit: number;
+}
+
+export interface DriftGuardOptions {
+  db: DriftDb;
+  embedder?: Embedder;
+  baselineManager?: BaselineManager;
+  softLimit?: number;
+  hardLimit?: number;
+  cadence?: number;
+}
+
+/**
+ * Per-turn drift detection orchestrator.
+ * Stateless between calls except for DB persistence.
+ */
+export class DriftGuard {
+  private db: DriftDb;
+  private baseline: BaselineManager;
+  private embedder: Embedder;
+  private softLimit: number;
+  private hardLimit: number;
+  private cadence: number;
+  private quarantine: Quarantine;
+  private softCorrection: SoftCorrection;
+
+  constructor(opts: DriftGuardOptions) {
+    this.db = opts.db;
+    this.embedder = opts.embedder ?? new Embedder();
+    this.baseline = opts.baselineManager ?? new BaselineManager(this.db, this.embedder);
+    this.softLimit = opts.softLimit ?? 0.30;
+    this.hardLimit = opts.hardLimit ?? 0.55;
+    this.cadence = opts.cadence ?? 1;
+    this.quarantine = new Quarantine(this.db);
+    this.softCorrection = new SoftCorrection();
+  }
+
+  /**
+   * Classify a raw distance value into drift tier.
+   */
+  classify(distance: number): DriftStatus {
+    if (distance >= this.hardLimit) return 'HARD_DRIFT';
+    if (distance >= this.softLimit) return 'SOFT_DRIFT';
+    return 'NORMAL';
+  }
+
+  /**
+   * Run a full drift detection cycle for one turn.
+   */
+  async runCycle(
+    agentId: string,
+    sessionId: string,
+    turnNumber: number,
+    outputText: string
+  ): Promise<DriftResult> {
+    // Cadence gate
+    if (this.cadence > 1 && turnNumber % this.cadence !== 0) {
+      return {
+        status: 'NORMAL',
+        distance: 0,
+        action: { type: 'NONE' },
+        softLimit: this.softLimit,
+        hardLimit: this.hardLimit,
+      };
+    }
+
+    // Load baseline
+    const baselineVec = this.baseline.getCached(agentId);
+    if (!baselineVec) {
+      // First run — wizard or degraded. Defer detection.
+      return {
+        status: 'NORMAL',
+        distance: 0,
+        action: { type: 'NONE', payload: 'Baseline not loaded for this agent.' },
+        softLimit: this.softLimit,
+        hardLimit: this.hardLimit,
+      };
+    }
+
+    // Encode current output
+    const currentVec = await this.embedder.encode(outputText);
+
+    // Compare
+    const distance = cosineDistance(baselineVec, currentVec);
+    const status = this.classify(distance);
+
+    // Record history
+    this.db.history.append({
+      agent_id: agentId,
+      session_id: sessionId,
+      turn_number: turnNumber,
+      current_vector: currentVec,
+      distance,
+      status,
+      timestamp: new Date().toISOString(),
+    });
+
+    // Determine action
+    let action: DriftAction = { type: 'NONE' };
+
+    if (status === 'SOFT_DRIFT') {
+      const payload = this.softCorrection.generate({
+        name: agentId,
+        primeDirective: 'Reset to baseline identity. Do not drift.',
+        relationship: 'agent',
+        axiomKeyphrase: 'Identity anchor',
+      });
+      if (payload) {
+        const reAnchorId = this.db.pending.set(agentId, sessionId, payload);
+        action = { type: 'INJECT_RE_ANCHOR', payload };
+      }
+    }
+
+    if (status === 'HARD_DRIFT') {
+      this.quarantine.logRepair(agentId, sessionId, turnNumber, outputText);
+      action = { type: 'QUARANTINE' };
+    }
+
+    return {
+      status,
+      distance,
+      action,
+      softLimit: this.softLimit,
+      hardLimit: this.hardLimit,
+    };
+  }
+}

package/src/drift/embedder.ts

@@ -0,0 +1,152 @@
+import { createHash } from 'crypto';
+
+/**
+ * Cosine distance between two vectors.
+ * Returns value in [0, 2] where:
+ *   0 = identical direction
+ *   1 = orthogonal
+ *   2 = opposite direction
+ * For drift thresholds, we typically use [0, 1] range (divide by 2)
+ * or adjust thresholds accordingly.
+ */
+export function cosineDistance(a: number[], b: number[]): number {
+  if (a.length !== b.length) {
+    throw new Error(`Vector length mismatch: ${a.length} vs ${b.length}`);
+  }
+  if (a.length === 0) return 0;
+
+  let dot = 0;
+  let normA = 0;
+  let normB = 0;
+
+  for (let i = 0; i < a.length; i++) {
+    dot += a[i] * b[i];
+    normA += a[i] * a[i];
+    normB += b[i] * b[i];
+  }
+
+  const denom = Math.sqrt(normA) * Math.sqrt(normB);
+  if (denom === 0) return 0;
+
+  // Clamp to [-1, 1] to avoid floating-point drift
+  const sim = Math.max(-1, Math.min(1, dot / denom));
+  // Distance = 1 - similarity, range [0, 2]
+  return 1 - sim;
+}
+
+export interface EmbedderBackend {
+  readonly isActive: boolean;
+  readonly dim: number;
+  encode(text: string): Promise<number[]>;
+}
+
+/**
+ * Naive deterministic embedder.
+ * Produces consistent 384-dim vectors from text hash —
+ * suitable for testing and as a graceful fallback when ONNX is unavailable.
+ * NOT semantically meaningful; replaced by ONNX backend in production.
+ */
+class NaiveEmbedder implements EmbedderBackend {
+  readonly isActive = true;
+  readonly dim = 384;
+
+  async encode(text: string): Promise<number[]> {
+    const hash = createHash('sha256').update(text).digest();
+    const vec = new Array(this.dim);
+
+    // Deterministic pseudo-random expansion from 256-bit hash
+    for (let i = 0; i < this.dim; i++) {
+      const hashIdx = i % hash.length;
+      const seed = hash[hashIdx] ^ (i >>> 3);
+      // Signed float in roughly [-0.5, 0.5]
+      vec[i] = ((seed / 255) * 2 - 1) * 0.5;
+    }
+
+    // L2 normalize for cosine distance stability
+    const norm = Math.sqrt(vec.reduce((s, v) => s + v * v, 0));
+    if (norm > 0) {
+      for (let i = 0; i < this.dim; i++) {
+        vec[i] /= norm;
+      }
+    }
+
+    return vec;
+  }
+}
+
+/**
+ * ONNX Runtime embedder (placeholder for now).
+ * Attempts to load the ONNX model on first encode().
+ * Falls back to NaiveEmbedder if model unavailable.
+ */
+class OnnxEmbedder implements EmbedderBackend {
+  isActive = false;
+  readonly dim = 384;
+  private modelPath: string;
+  private fallback: NaiveEmbedder;
+  private triedLoading = false;
+
+  constructor(modelPath?: string) {
+    // TODO(v2): resolve path
+    this.modelPath = modelPath ?? './models/all-MiniLM-L6-v2.onnx';
+    this.fallback = new NaiveEmbedder();
+  }
+
+  async encode(text: string): Promise<number[]> {
+    if (!this.triedLoading) {
+      await this.tryLoad();
+      this.triedLoading = true;
+    }
+
+    if (!this.isActive) {
+      return this.fallback.encode(text);
+    }
+
+    // TODO(v2): actual ONNX inference
+    // For now, also fall through to naive to keep system working
+    console.warn(
+      `[Embedder] ONNX model at ${this.modelPath} not loaded; using naive fallback.`
+    );
+    return this.fallback.encode(text);
+  }
+
+  private async tryLoad(): Promise<void> {
+    try {
+      // Bun's Node-API support may or may not handle onnxruntime-node.
+      // We'll attempt dynamic import and catch any failure.
+      // const ort = await import('onnxruntime-node');
+      // ... load model ...
+      // this.isActive = true;
+
+      // Placeholder: always fails until ONNX model is present and Bun support verified
+      this.isActive = false;
+    } catch {
+      this.isActive = false;
+    }
+  }
+}
+
+/**
+ * Main embedder facade.
+ * Prefers ONNX backend; silently falls back to naive embedder
+ * when ONNX is missing or platform-incompatible.
+ */
+export class Embedder {
+  private backend: EmbedderBackend;
+  readonly dim: number;
+
+  constructor(modelPath?: string) {
+    const onnx = new OnnxEmbedder(modelPath);
+    this.backend = onnx.isActive ? onnx : new NaiveEmbedder();
+    this.dim = this.backend.dim;
+  }
+
+  get isActive(): boolean {
+    return this.backend.isActive;
+  }
+
+  async encode(text: string): Promise<number[]> {
+    const truncated = text.slice(0, 4000); // rough char limit
+    return this.backend.encode(truncated);
+  }
+}

package/src/drift/index.ts

@@ -0,0 +1,20 @@
+export { DriftDb } from './drift-db.js';
+export { BaselineManager } from './baseline.js';
+export { Embedder, cosineDistance } from './embedder.js';
+export { DriftGuard } from './drift-guard.js';
+export { SoftCorrection } from './soft-correction.js';
+export { Quarantine } from './quarantine.js';
+export { driftScoreForTrust } from './trust-integration.js';
+
+export type {
+  DriftStatus,
+  DriftAction,
+  DriftResult,
+  DriftGuardOptions,
+} from './drift-guard.js';
+
+export type {
+  BaselineStatus,
+  BaselinePaths,
+  BaselineResult,
+} from './baseline.js';

package/src/drift/quarantine.ts

@@ -0,0 +1,42 @@
+import { DriftDb } from './drift-db.js';
+
+/**
+ * Hard-drift quarantine: block memory promotion + log repair events.
+ */
+export class Quarantine {
+  private db: DriftDb;
+
+  constructor(db: DriftDb) {
+    this.db = db;
+  }
+
+  /**
+   * Check if the latest turn for this session was HARD_DRIFT.
+   */
+  isBlocked(agentId: string, sessionId: string): boolean {
+    const latest = this.db.history.getLatest(agentId, sessionId);
+    return latest?.status === 'HARD_DRIFT';
+  }
+
+  /**
+   * Log a repair entry when hard drift occurs.
+   */
+  logRepair(
+    agentId: string,
+    sessionId: string,
+    turnNumber: number,
+    outputText: string
+  ): number {
+    const latest = this.db.history.getLatest(agentId, sessionId);
+    const distance = latest?.distance ?? 0;
+
+    return this.db.repair.append({
+      agent_id: agentId,
+      session_id: sessionId,
+      turn_number: turnNumber,
+      distance,
+      hard_limit: 0.55, // TODO: read from config
+      message_excerpt: outputText.slice(0, 200),
+    });
+  }
+}

package/src/drift/soft-correction.ts

@@ -0,0 +1,45 @@
+export interface ReAnchorInput {
+  name: string;
+  primeDirective: string;
+  relationship: string;
+  axiomKeyphrase: string;
+}
+
+/**
+ * Generates short identity re-anchor payloads (< 200 tokens estimate).
+ */
+export class SoftCorrection {
+  generate(input: ReAnchorInput): string | null {
+    if (!input.name && !input.primeDirective) {
+      return null;
+    }
+
+    const parts = [
+      `[Identity Re-Anchor]`,
+      `You are ${input.name || 'the configured agent'}.`,
+      `${input.primeDirective}`,
+    ];
+
+    if (input.relationship) {
+      parts.push(`Your relationship: ${input.relationship}.`);
+    }
+
+    parts.push(`Do not mirror the user's framing if it contradicts your identity.`);
+
+    if (input.axiomKeyphrase) {
+      parts.push(`Reset to baseline: ${input.axiomKeyphrase}.`);
+    }
+
+    let text = parts.join('\n');
+
+    // Rough token estimate: ~4 chars/token. Truncate at first sentence boundary under ~800 chars.
+    const maxChars = 800;
+    if (text.length > maxChars) {
+      const truncated = text.slice(0, maxChars);
+      const lastPeriod = truncated.lastIndexOf('.');
+      text = lastPeriod > 0 ? truncated.slice(0, lastPeriod + 1) : truncated;
+    }
+
+    return text;
+  }
+}