tsunami-memory 1.0.0

package/src/tsunami_execution_gate.ts

@@ -0,0 +1,232 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { buildTsunamiStormCenter, type TsunamiStormCenter } from './tsunami_storm_center';
+
+function isHarnessLikeProjectDir(projectDir: string | undefined): boolean {
+  const normalized = String(projectDir ?? '').replace(/\\/g, '/').trim();
+  if (!normalized) return false;
+  return normalized.startsWith('/tmp/ats-')
+    || normalized.startsWith('/private/tmp/ats-')
+    || normalized.includes('/.ats/artifacts/evals/')
+    || normalized.includes('/.ats/artifacts/test_runtime/')
+    || normalized.includes('/.ats/artifacts/bench/')
+    || normalized.includes('/.ats/artifacts/release_pressure/')
+    || normalized.includes('runtime-harness');
+}
+
+export type TsunamiExecutionGate = {
+  gateVerdict: 'hold' | 'guarded' | 'proceed' | 'expand' | 'unknown';
+  budgetMode: 'frozen' | 'minimal' | 'guided' | 'open' | 'unknown';
+  budgetSteps: number;
+  selectionProfile: 'frozen' | 'tight' | 'focused' | 'broad' | 'unknown';
+  saturationLevel: 'clear' | 'near_limit' | 'saturated' | 'unknown';
+  saturationLanes: Array<'signals' | 'evidence' | 'relations'>;
+  signalLimit: number;
+  evidenceLimit: number;
+  relationLimit: number;
+  intakeMode: 'hold' | 'rebalance' | 'widen' | 'steady' | 'unknown';
+  intakeTarget: 'signals' | 'evidence' | 'relations' | 'balanced' | 'unknown';
+  nextSignalLimit: number;
+  nextEvidenceLimit: number;
+  nextRelationLimit: number;
+  allowDelegation: boolean;
+  maxDelegationParallel: number;
+  actionLabel?: string;
+  actionTarget?: string;
+  readinessLevel?: string;
+  boundaryMode?: string;
+  reason: string;
+};
+
+export type TsunamiExecutionGateToolResult = {
+  blocked: boolean;
+  reason?: string;
+  args: Record<string, unknown>;
+  notes: string[];
+};
+
+export function deriveTsunamiLoopStepLimit(baseMaxSteps: number, gate: TsunamiExecutionGate | null): number {
+  const normalizedBase = Math.max(1, Math.floor(Number(baseMaxSteps) || 1));
+  if (!gate) return normalizedBase;
+
+  let gateSteps = Math.max(0, Math.floor(Number(gate.budgetSteps) || 0));
+  if (gate.budgetMode === 'frozen' || gate.gateVerdict === 'hold') {
+    gateSteps = 1;
+  } else if (gateSteps <= 0) {
+    if (gate.budgetMode === 'minimal') gateSteps = Math.min(3, normalizedBase);
+    else if (gate.budgetMode === 'guided') gateSteps = Math.min(12, normalizedBase);
+    else if (gate.budgetMode === 'open') gateSteps = normalizedBase;
+    else gateSteps = normalizedBase; // Unknown mode: trust base config, don't cripple
+  }
+
+  return Math.max(1, Math.min(normalizedBase, gateSteps));
+}
+
+function clampPositive(value: unknown, fallback: number): number {
+  const num = Number(value);
+  if (!Number.isFinite(num)) return fallback;
+  return Math.max(1, Math.floor(num));
+}
+
+function deriveSelectionLimits(center: TsunamiStormCenter) {
+  const selection = center.stormSelection;
+  const intake = center.stormIntake;
+  let signalLimit = clampPositive(selection?.signalLimit, 3);
+  let evidenceLimit = clampPositive(selection?.evidenceLimit, 2);
+  let relationLimit = clampPositive(selection?.relationLimit, 6);
+
+  if (intake?.mode === 'widen') {
+    if (intake.target === 'signals' || intake.target === 'balanced') signalLimit = Math.max(signalLimit, clampPositive(intake.nextSignalLimit, signalLimit));
+    if (intake.target === 'evidence' || intake.target === 'balanced') evidenceLimit = Math.max(evidenceLimit, clampPositive(intake.nextEvidenceLimit, evidenceLimit));
+    if (intake.target === 'relations' || intake.target === 'balanced') relationLimit = Math.max(relationLimit, clampPositive(intake.nextRelationLimit, relationLimit));
+  } else if (intake?.mode === 'rebalance') {
+    if (intake.target === 'signals' || intake.target === 'balanced') signalLimit = clampPositive(intake.nextSignalLimit, signalLimit);
+    if (intake.target === 'evidence' || intake.target === 'balanced') evidenceLimit = clampPositive(intake.nextEvidenceLimit, evidenceLimit);
+    if (intake.target === 'relations' || intake.target === 'balanced') relationLimit = clampPositive(intake.nextRelationLimit, relationLimit);
+  } else if (intake?.mode === 'hold') {
+    signalLimit = Math.min(signalLimit, clampPositive(intake.nextSignalLimit, signalLimit));
+    evidenceLimit = Math.min(evidenceLimit, clampPositive(intake.nextEvidenceLimit, evidenceLimit));
+    relationLimit = Math.min(relationLimit, clampPositive(intake.nextRelationLimit, relationLimit));
+  }
+
+  return { signalLimit, evidenceLimit, relationLimit };
+}
+
+function deriveMaxDelegationParallel(center: TsunamiStormCenter): number {
+  const gateVerdict = String(center.stormGate?.verdict ?? '');
+  const budgetMode = String(center.stormBudget?.mode ?? '');
+  const selectionProfile = String(center.stormSelection?.profile ?? '');
+  const intakeMode = String(center.stormIntake?.mode ?? '');
+  const saturationLevel = String(center.stormSaturation?.level ?? '');
+
+  if (gateVerdict === 'hold' || budgetMode === 'frozen') return 1;
+  if (saturationLevel === 'saturated') return 1;
+  if (budgetMode === 'minimal' || selectionProfile === 'tight' || intakeMode === 'hold') return 1;
+  if (saturationLevel === 'near_limit' && (intakeMode === 'rebalance' || selectionProfile === 'focused')) return 1;
+  if (budgetMode === 'guided' || selectionProfile === 'focused' || intakeMode === 'rebalance' || intakeMode === 'steady') return 2;
+  if (gateVerdict === 'expand' || budgetMode === 'open' || selectionProfile === 'broad' || intakeMode === 'widen') return 3;
+  return 2;
+}
+
+export function buildTsunamiExecutionGate(input: {
+  projectDir?: string;
+  sessionId?: string;
+  query?: string;
+}): TsunamiExecutionGate | null {
+  if (!input.projectDir?.trim()) return null;
+  if (isHarnessLikeProjectDir(input.projectDir)) return null;
+  // Skip gate for projects without TSUNAMI data
+  const hasData = existsSync(join(input.projectDir, '.tsunami')) || existsSync(join(input.projectDir, 'README.md'));
+  if (!hasData) return null;
+  const center = buildTsunamiStormCenter({
+    projectDir: input.projectDir,
+    sessionId: input.sessionId,
+    query: input.query || 'continue this project',
+    refreshGraph: false,
+    signalLimit: 3,
+    evidenceLimit: 2,
+    relationLimit: 6,
+  });
+  // Default to 'proceed'/'open' for unknown/unfamiliar projects — don't cripple execution
+  const rawVerdict = String(center.stormGate?.verdict ?? '');
+  const rawBudgetMode = String(center.stormBudget?.mode ?? '');
+  const gateVerdict: TsunamiExecutionGate['gateVerdict'] =
+    (rawVerdict === 'hold' || rawVerdict === 'guarded' || rawVerdict === 'proceed' || rawVerdict === 'expand')
+      ? rawVerdict : 'proceed';
+  const budgetMode: TsunamiExecutionGate['budgetMode'] =
+    (rawBudgetMode === 'frozen' || rawBudgetMode === 'minimal' || rawBudgetMode === 'guided' || rawBudgetMode === 'open')
+      ? rawBudgetMode : 'open';
+  const selectionProfile = String(center.stormSelection?.profile ?? 'unknown') as TsunamiExecutionGate['selectionProfile'];
+  const saturationLevel = String(center.stormSaturation?.level ?? 'unknown') as TsunamiExecutionGate['saturationLevel'];
+  const intakeMode = String(center.stormIntake?.mode ?? 'unknown') as TsunamiExecutionGate['intakeMode'];
+  const intakeTarget = String(center.stormIntake?.target ?? 'unknown') as TsunamiExecutionGate['intakeTarget'];
+  const limits = deriveSelectionLimits(center);
+  const allowDelegation = gateVerdict !== 'hold' && budgetMode !== 'frozen';
+  const maxDelegationParallel = deriveMaxDelegationParallel(center);
+  const reason = [
+    center.stormGate?.reason,
+    center.stormBudget?.reason,
+    center.stormSelection?.reason,
+    center.stormIntake?.reason,
+  ].map((item) => String(item ?? '').trim()).find(Boolean) || 'storm gate requires a tighter execution surface';
+
+  return {
+    gateVerdict,
+    budgetMode,
+    budgetSteps: Math.max(0, Math.floor(Number(center.stormBudget?.steps ?? 0))),
+    selectionProfile,
+    saturationLevel,
+    saturationLanes: Array.isArray(center.stormSaturation?.hitLanes)
+      ? center.stormSaturation.hitLanes.filter((item): item is 'signals' | 'evidence' | 'relations' => ['signals', 'evidence', 'relations'].includes(String(item)))
+      : [],
+    signalLimit: limits.signalLimit,
+    evidenceLimit: limits.evidenceLimit,
+    relationLimit: limits.relationLimit,
+    intakeMode,
+    intakeTarget,
+    nextSignalLimit: clampPositive(center.stormIntake?.nextSignalLimit, limits.signalLimit),
+    nextEvidenceLimit: clampPositive(center.stormIntake?.nextEvidenceLimit, limits.evidenceLimit),
+    nextRelationLimit: clampPositive(center.stormIntake?.nextRelationLimit, limits.relationLimit),
+    allowDelegation,
+    maxDelegationParallel,
+    actionLabel: String(center.stormAction?.label ?? '').trim() || undefined,
+    actionTarget: String(center.stormAction?.target ?? '').trim() || undefined,
+    readinessLevel: String(center.stormReadiness?.level ?? '').trim() || undefined,
+    boundaryMode: String(center.stormBoundary?.mode ?? '').trim() || undefined,
+    reason,
+  };
+}
+
+export function formatTsunamiExecutionGateSummary(gate: TsunamiExecutionGate | null): string {
+  if (!gate) return 'tsunami execution gate unavailable';
+  return [
+    `gate=${gate.gateVerdict}`,
+    `budget=${gate.budgetMode}:${gate.budgetSteps}`,
+    `selection=${gate.selectionProfile}:${gate.signalLimit}/${gate.evidenceLimit}/${gate.relationLimit}`,
+    `saturation=${gate.saturationLevel}:${gate.saturationLanes.join('|') || 'clear'}`,
+    `intake=${gate.intakeMode}:${gate.intakeTarget}:${gate.nextSignalLimit}/${gate.nextEvidenceLimit}/${gate.nextRelationLimit}`,
+    `delegation=${gate.allowDelegation ? `allow:${gate.maxDelegationParallel}` : 'hold'}`,
+  ].join(' · ');
+}
+
+export function applyTsunamiExecutionGateToTool(
+  tool: string,
+  args: Record<string, unknown> | undefined,
+  gate: TsunamiExecutionGate | null,
+): TsunamiExecutionGateToolResult {
+  const nextArgs = { ...(args || {}) };
+  if (!gate) return { blocked: false, args: nextArgs, notes: [] };
+  const notes: string[] = [];
+
+  if (tool === 'delegate_task' || tool === 'swarm_run') {
+    if (!gate.allowDelegation) {
+      return {
+        blocked: true,
+        reason: `TSUNAMI gate=${gate.gateVerdict} budget=${gate.budgetMode}; tighten storm surface first using ${gate.actionLabel || 'mainline repair'}, then decide whether to expand delegation.${gate.reason ? ` ${gate.reason}` : ''}`.trim(),
+        args: nextArgs,
+        notes,
+      };
+    }
+    const currentParallel = clampPositive(nextArgs.max_parallel, tool === 'swarm_run' ? 3 : 2);
+    const clampedParallel = Math.min(currentParallel, gate.maxDelegationParallel);
+    if (clampedParallel !== currentParallel) {
+      nextArgs.max_parallel = clampedParallel;
+      notes.push(`TSUNAMI execution gate reduced ${tool} max_parallel from ${currentParallel} to ${clampedParallel}`);
+    }
+  }
+
+  if (tool === 'tsunami' && String(nextArgs.cmd ?? '').trim() === 'storm_center') {
+    const currentSignals = clampPositive(nextArgs.signal_limit, gate.signalLimit);
+    const currentEvidence = clampPositive(nextArgs.evidence_limit, gate.evidenceLimit);
+    const currentRelations = clampPositive(nextArgs.relation_limit, gate.relationLimit);
+    const nextSignals = Math.min(currentSignals, gate.signalLimit);
+    const nextEvidence = Math.min(currentEvidence, gate.evidenceLimit);
+    const nextRelations = Math.min(currentRelations, gate.relationLimit);
+    nextArgs.signal_limit = nextSignals;
+    nextArgs.evidence_limit = nextEvidence;
+    nextArgs.relation_limit = nextRelations;
+    notes.push(`TSUNAMI execution gate constrained storm_center to ${nextSignals}/${nextEvidence}/${nextRelations}`);
+  }
+
+  return { blocked: false, args: nextArgs, notes };
+}

package/src/tsunami_graph_runtime.ts

@@ -0,0 +1,359 @@
+/**
+ * TSUNAMI Knowledge Graph Runtime — SQLite-backed triple store
+ *
+ * Adds graph tables to the TSUNAMI memory database for storing and querying
+ * subject-predicate-object triples. Supports temporal validity tracking,
+ * BFS traversal, and cross-wing tunnel discovery.
+ */
+
+import { Database } from 'bun:sqlite';
+import { BUN_MEMORY_DB_PATH } from './tsunami_storage_paths';
+import { runMigrations, getMigrations } from './migration';
+
+// ── Database initialization ──────────────────────────────────
+
+let _db: Database | null = null;
+
+function getDb(): Database {
+  if (_db) return _db;
+  _db = new Database(BUN_MEMORY_DB_PATH);
+  _db.run('PRAGMA journal_mode = WAL');
+  runMigrations(_db, getMigrations()); // idempotent — applies only pending
+  return _db;
+}
+
+// ── ID Generation ────────────────────────────────────────────
+
+function generateId(): string {
+  const ts = Date.now().toString(36);
+  const rand = Math.random().toString(36).slice(2, 8);
+  return `kg_${ts}_${rand}`;
+}
+
+// ── Types ────────────────────────────────────────────────────
+
+export interface GraphTriple {
+  id: string;
+  subject: string;
+  predicate: string;
+  object: string;
+  subject_type: string | null;
+  object_type: string | null;
+  subject_properties: string;
+  object_properties: string;
+  confidence: number;
+  valid_from: string | null;
+  valid_to: string | null;
+  source_file: string | null;
+  created_at: number;
+}
+
+export interface GraphAddTripleInput {
+  subject: string;
+  subjectType?: string;
+  subjectProperties?: Record<string, unknown>;
+  predicate: string;
+  object: string;
+  objectType?: string;
+  objectProperties?: Record<string, unknown>;
+  validFrom?: string;
+  validTo?: string;
+  confidence?: number;
+  sourceCloset?: string;
+  sourceFile?: string;
+}
+
+export interface GraphInvalidateTripleInput {
+  subject: string;
+  predicate: string;
+  object: string;
+  ended?: string;
+}
+
+export interface GraphTraverseResult {
+  startRoom: string;
+  maxHops: number;
+  visited: string[];
+  nodes: Array<{
+    entity: string;
+    depth: number;
+    relation: string;
+    confidence: number;
+  }>;
+  error?: string;
+}
+
+export interface GraphTunnelResult {
+  wingA: string;
+  wingB: string;
+  tunnels: Array<{
+    subject: string;
+    predicate: string;
+    object: string;
+    confidence: number;
+  }>;
+}
+
+// ── Public API ───────────────────────────────────────────────
+
+export function tsunamiGraphAddTriple(input: GraphAddTripleInput): string {
+  const db = getDb();
+  const id = generateId();
+
+  const stmt = db.prepare(`
+    INSERT INTO graph_triples (id, subject, predicate, object, subject_type, object_type, subject_properties, object_properties, confidence, valid_from, valid_to, source_file)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `);
+
+  stmt.run(
+    id,
+    input.subject,
+    input.predicate,
+    input.object,
+    input.subjectType || null,
+    input.objectType || null,
+    JSON.stringify(input.subjectProperties || {}),
+    JSON.stringify(input.objectProperties || {}),
+    input.confidence ?? 1.0,
+    input.validFrom || null,
+    input.validTo || null,
+    input.sourceFile || null,
+  );
+
+  return id;
+}
+
+export function tsunamiGraphQueryEntity(
+  entity: string,
+  asOf?: string,
+  direction: 'outgoing' | 'incoming' | 'both' = 'outgoing',
+): GraphTriple[] {
+  const db = getDb();
+
+  const conditions: string[] = [];
+  const params: any[] = [];
+
+  if (direction === 'outgoing' || direction === 'both') {
+    conditions.push('(subject = ?)');
+    params.push(entity);
+  }
+  if (direction === 'incoming' || direction === 'both') {
+    conditions.push('(object = ?)');
+    params.push(entity);
+  }
+
+  if (asOf) {
+    conditions.push('(valid_from IS NULL OR valid_from <= ?)');
+    params.push(asOf);
+    conditions.push('(valid_to IS NULL OR valid_to >= ?)');
+    params.push(asOf);
+  }
+
+  const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(' OR ')}` : '';
+  const sql = `SELECT * FROM graph_triples ${whereClause} ORDER BY confidence DESC, created_at DESC`;
+
+  const stmt = db.prepare(sql);
+  return stmt.all(...params) as GraphTriple[];
+}
+
+export function tsunamiGraphInvalidateTriple(input: GraphInvalidateTripleInput): number {
+  const db = getDb();
+  const ended = input.ended || new Date().toISOString();
+
+  const stmt = db.prepare(`
+    UPDATE graph_triples
+    SET valid_to = ?
+    WHERE subject = ? AND predicate = ? AND object = ? AND valid_to IS NULL
+  `);
+
+  const result = stmt.run(ended, input.subject, input.predicate, input.object);
+  return result.changes;
+}
+
+export function tsunamiGraphStats(): Record<string, unknown> {
+  const db = getDb();
+
+  const total = (db.prepare('SELECT COUNT(*) as count FROM graph_triples').get() as { count: number }).count;
+  const active = (db.prepare('SELECT COUNT(*) as count FROM graph_triples WHERE valid_to IS NULL').get() as { count: number }).count;
+  const subjects = (db.prepare('SELECT COUNT(DISTINCT subject) as count FROM graph_triples').get() as { count: number }).count;
+
+  return {
+    total,
+    active,
+    subjects,
+    backend: 'bun_native',
+  };
+}
+
+export function tsunamiGraphCompatStats(): Record<string, unknown> {
+  // Alias for graph_stats compatibility
+  return tsunamiGraphStats();
+}
+
+export function tsunamiGraphTimeline(entity?: string, limit = 20): GraphTriple[] {
+  const db = getDb();
+  const max = Math.max(1, Math.min(200, Number(limit ?? 20)));
+
+  let sql: string;
+  let params: any[];
+
+  if (entity) {
+    sql = `
+      SELECT * FROM graph_triples
+      WHERE subject = ? OR object = ?
+      ORDER BY created_at DESC
+      LIMIT ?
+    `;
+    params = [entity, entity, max];
+  } else {
+    sql = `
+      SELECT * FROM graph_triples
+      ORDER BY created_at DESC
+      LIMIT ?
+    `;
+    params = [max];
+  }
+
+  const stmt = db.prepare(sql);
+  return stmt.all(...params) as GraphTriple[];
+}
+
+export function tsunamiGraphTraverse(startRoom: string, maxHops = 2): GraphTraverseResult {
+  const db = getDb();
+  const start = String(startRoom ?? '').trim();
+
+  if (!start) {
+    return { startRoom: '', maxHops, visited: [], nodes: [], error: 'startRoom is required' };
+  }
+
+  const visited = new Set<string>();
+  const nodes: GraphTraverseResult['nodes'] = [];
+  let queue: Array<{ entity: string; depth: number }> = [{ entity: start, depth: 0 }];
+  const hops = Math.max(1, Math.min(10, Number(maxHops ?? 2)));
+
+  while (queue.length > 0) {
+    const current = queue.shift()!;
+    if (visited.has(current.entity)) continue;
+    visited.add(current.entity);
+
+    // Find outgoing edges
+    const outgoing = db.prepare(
+      'SELECT * FROM graph_triples WHERE subject = ? AND valid_to IS NULL ORDER BY confidence DESC',
+    ).all(current.entity) as GraphTriple[];
+
+    for (const triple of outgoing) {
+      if (!visited.has(triple.object)) {
+        nodes.push({
+          entity: triple.object,
+          depth: current.depth + 1,
+          relation: triple.predicate,
+          confidence: triple.confidence,
+        });
+        if (current.depth + 1 < hops) {
+          queue.push({ entity: triple.object, depth: current.depth + 1 });
+        }
+      }
+    }
+
+    // Find incoming edges
+    const incoming = db.prepare(
+      'SELECT * FROM graph_triples WHERE object = ? AND valid_to IS NULL ORDER BY confidence DESC',
+    ).all(current.entity) as GraphTriple[];
+
+    for (const triple of incoming) {
+      if (!visited.has(triple.subject)) {
+        nodes.push({
+          entity: triple.subject,
+          depth: current.depth + 1,
+          relation: triple.predicate,
+          confidence: triple.confidence,
+        });
+        if (current.depth + 1 < hops) {
+          queue.push({ entity: triple.subject, depth: current.depth + 1 });
+        }
+      }
+    }
+  }
+
+  return {
+    startRoom: start,
+    maxHops: hops,
+    visited: Array.from(visited),
+    nodes,
+  };
+}
+
+export function tsunamiGraphFindTunnels(wingA?: string, wingB?: string): GraphTunnelResult[] {
+  const db = getDb();
+
+  // Find cross-wing tunnels: triples where subject and object belong to different wings
+  const results: GraphTunnelResult[] = [];
+  const limit = 20;
+
+  let sql: string;
+  let params: any[];
+
+  if (wingA && wingB) {
+    sql = `
+      SELECT * FROM graph_triples
+      WHERE ((subject LIKE ? AND object LIKE ?) OR (subject LIKE ? AND object LIKE ?))
+        AND valid_to IS NULL
+      ORDER BY confidence DESC
+      LIMIT ?
+    `;
+    params = [`${wingA}:%`, `${wingB}:%`, `${wingB}:%`, `${wingA}:%`, limit];
+  } else if (wingA) {
+    sql = `
+      SELECT * FROM graph_triples
+      WHERE (subject LIKE ? OR object LIKE ?)
+        AND valid_to IS NULL
+      ORDER BY confidence DESC
+      LIMIT ?
+    `;
+    params = [`${wingA}:%`, `${wingA}:%`, limit];
+  } else {
+    sql = `
+      SELECT * FROM graph_triples
+      WHERE valid_to IS NULL
+        AND ((subject LIKE 'task:%' AND object LIKE 'memory:%')
+          OR (subject LIKE 'decision:%' AND object LIKE 'task:%')
+          OR (subject LIKE 'ats:%' AND object LIKE 'decision:%')
+          OR (subject LIKE 'memory:%' AND object LIKE 'people:%'))
+      ORDER BY confidence DESC
+      LIMIT ?
+    `;
+    params = [limit];
+  }
+
+  const triples = db.prepare(sql).all(...params) as GraphTriple[];
+
+  // Group by wing pairs
+  const tunnelMap = new Map<string, GraphTriple[]>();
+
+  for (const triple of triples) {
+    const sWing = triple.subject.split('/')[0] || triple.subject.split(':')[0];
+    const oWing = triple.object.split('/')[0] || triple.object.split(':')[0];
+
+    if (sWing && oWing && sWing !== oWing) {
+      const key = [sWing, oWing].sort().join('--');
+      if (!tunnelMap.has(key)) tunnelMap.set(key, []);
+      tunnelMap.get(key)!.push(triple);
+    }
+  }
+
+  for (const [key, tunnels] of tunnelMap) {
+    const [wa, wb] = key.split('--');
+    results.push({
+      wingA: wa,
+      wingB: wb,
+      tunnels: tunnels.slice(0, 10).map((t) => ({
+        subject: t.subject,
+        predicate: t.predicate,
+        object: t.object,
+        confidence: t.confidence,
+      })),
+    });
+  }
+
+  return results;
+}

package/src/tsunami_identity.ts

@@ -0,0 +1,35 @@
+import { existsSync, readFileSync } from 'fs';
+
+import {
+  TSUNAMI_LEGACY_IDENTITY_REPLACEMENTS,
+  hasTsunamiLegacyIdentityTerms,
+} from './legacy_compat/tsunami_legacy_identity';
+import { TSUNAMI_IDENTITY_FILE } from './tsunami_storage_paths';
+
+const NO_IDENTITY = 'No identity configured.';
+
+export function normalizeTsunamiIdentityText(raw: string): string {
+  let next = String(raw ?? '').trim();
+  if (!next) return NO_IDENTITY;
+  for (const [pattern, replacement] of TSUNAMI_LEGACY_IDENTITY_REPLACEMENTS) {
+    next = next.replace(pattern, replacement);
+  }
+  if (!/TSUNAMI/.test(next)) {
+    next = `${next}\n\nPrimary memory system: TSUNAMI (Bun-native ocean memory runtime)`;
+  }
+  return next;
+}
+
+export function readTsunamiIdentity(path = TSUNAMI_IDENTITY_FILE): string {
+  try {
+    if (!existsSync(path)) return NO_IDENTITY;
+    return normalizeTsunamiIdentityText(readFileSync(path, 'utf8'));
+  } catch (err: unknown) {
+    console.warn(`[TSUNAMI] failed to read identity file at ${path}: ${err instanceof Error ? err.message : String(err)}`);
+    return NO_IDENTITY;
+  }
+}
+
+export function hasLegacyIdentityTerms(raw: string): boolean {
+  return hasTsunamiLegacyIdentityTerms(raw);
+}