ruflo-graph-intelligence 0.1.0-alpha.1

package/src/adapters/jujutsu-blast-radius-adapter.ts

@@ -0,0 +1,107 @@
+/**
+ * Jujutsu Blast-Radius Adapter (Wedge 11, ADR-123 Phase 6)
+ *
+ * `ruflo-jujutsu` runs diff-analyze. This adapter exports the file-import
+ * graph so "if I change `foo.ts`, which files are downstream-affected" is a
+ * single-entry PR query — O(log files) instead of O(LOC × imports).
+ *
+ * The graph is directed: A imports B → A is downstream of B (B's change
+ * propagates upward to A). For blast-radius FROM a changed file, the matrix
+ * keeps natural orientation (changed file is the seed; downstream files
+ * receive the PR mass).
+ */
+
+import { createHash } from 'node:crypto';
+import type { SparseEntry, SparseMatrix } from '../domain/types.js';
+import type { SublinearAdapter, AdapterRegistry } from '../domain/adapter.js';
+import { getRegistry } from '../domain/adapter.js';
+
+export interface ImportEdge {
+  /** File that does the importing. */
+  importer: string;
+  /** File being imported. */
+  importee: string;
+  /** Optional weight — number of distinct symbols imported. Default 1. */
+  weight?: number;
+}
+
+export interface JujutsuSource {
+  listImportEdges(): Promise<readonly ImportEdge[]>;
+}
+
+export interface JujutsuAdapterOptions {
+  source: JujutsuSource;
+  /** DD safety margin. Default 0.25. */
+  ddSafetyMargin?: number;
+}
+
+export const JUJUTSU_IMPORT_GRAPH_ID = 'ruflo-jujutsu:import-graph';
+
+export class JujutsuBlastRadiusAdapter implements SublinearAdapter {
+  readonly graphId = JUJUTSU_IMPORT_GRAPH_ID;
+  readonly ownerPlugin = 'ruflo-jujutsu';
+  readonly requiresPreprocessing = false;
+
+  private readonly source: JujutsuSource;
+  private readonly ddSafetyMargin: number;
+
+  constructor(options: JujutsuAdapterOptions) {
+    this.source = options.source;
+    this.ddSafetyMargin = options.ddSafetyMargin ?? 0.25;
+  }
+
+  async exportAsSparseMatrix(options?: { nodeFilter?: ReadonlySet<string> }): Promise<SparseMatrix> {
+    const edges = await this.source.listImportEdges();
+    const fileSet = new Set<string>();
+    for (const e of edges) {
+      fileSet.add(e.importer);
+      fileSet.add(e.importee);
+    }
+    if (options?.nodeFilter) {
+      for (const n of [...fileSet]) if (!options.nodeFilter.has(n)) fileSet.delete(n);
+    }
+    const files = [...fileSet].sort();
+    const nodeIndex: Record<string, number> = {};
+    files.forEach((f, i) => (nodeIndex[f] = i));
+
+    // For blast-radius PR seeded at the changed file: we want change to flow
+    // from `importee` → `importer`. So row = importee, col = importer.
+    const entries: SparseEntry[] = [];
+    const rowSums = new Array<number>(files.length).fill(0);
+    for (const e of edges) {
+      const r = nodeIndex[e.importee];
+      const c = nodeIndex[e.importer];
+      if (r === undefined || c === undefined || r === c) continue;
+      const w = Math.max(0, e.weight ?? 1);
+      entries.push({ row: r, col: c, value: w });
+      rowSums[r] += w;
+    }
+    for (let i = 0; i < files.length; i++) {
+      entries.push({ row: i, col: i, value: rowSums[i]! + this.ddSafetyMargin });
+    }
+    return {
+      graphId: this.graphId,
+      size: files.length,
+      entries,
+      nodeIndex,
+      indexNode: files,
+      capturedAt: new Date().toISOString(),
+      contentHash: hashContent(this.graphId, entries),
+    };
+  }
+}
+
+export function registerJujutsuBlastRadiusAdapter(
+  options: JujutsuAdapterOptions & { registry?: AdapterRegistry },
+): JujutsuBlastRadiusAdapter {
+  const adapter = new JujutsuBlastRadiusAdapter(options);
+  (options.registry ?? getRegistry()).register(adapter);
+  return adapter;
+}
+
+function hashContent(graphId: string, entries: readonly SparseEntry[]): string {
+  const h = createHash('sha256');
+  h.update(graphId);
+  for (const e of entries) h.update(`|${e.row},${e.col},${e.value.toFixed(8)}`);
+  return h.digest('hex');
+}

package/src/adapters/knowledge-graph-adapter.ts

@@ -0,0 +1,110 @@
+/**
+ * Knowledge Graph Adapter (Wedge 4, ADR-123 Phase 4)
+ *
+ * `ruflo-knowledge-graph` builds an entity-relation graph via kg-extract.
+ * This adapter exports it as a SparseMatrix so kg-importance(entity) becomes
+ * a single-entry PR query — answering "which entity is most central" in
+ * sub-millisecond on a 10k-node graph.
+ */
+
+import { createHash } from 'node:crypto';
+import type { SparseEntry, SparseMatrix } from '../domain/types.js';
+import type { SublinearAdapter, AdapterRegistry } from '../domain/adapter.js';
+import { getRegistry } from '../domain/adapter.js';
+
+export interface KGEdge {
+  fromEntity: string;
+  toEntity: string;
+  relation: string;
+  /** Edge confidence in [0,1]. Default 1.0. */
+  confidence?: number;
+}
+
+export interface KnowledgeGraphSource {
+  listEdges(): Promise<readonly KGEdge[]>;
+}
+
+export interface KnowledgeGraphAdapterOptions {
+  source: KnowledgeGraphSource;
+  /** DD safety margin. Default 0.25. */
+  ddSafetyMargin?: number;
+}
+
+export const KNOWLEDGE_GRAPH_ID = 'ruflo-knowledge-graph:entities';
+
+export class KnowledgeGraphAdapter implements SublinearAdapter {
+  readonly graphId = KNOWLEDGE_GRAPH_ID;
+  readonly ownerPlugin = 'ruflo-knowledge-graph';
+  readonly requiresPreprocessing = false;
+
+  private readonly source: KnowledgeGraphSource;
+  private readonly ddSafetyMargin: number;
+
+  constructor(options: KnowledgeGraphAdapterOptions) {
+    this.source = options.source;
+    this.ddSafetyMargin = options.ddSafetyMargin ?? 0.25;
+  }
+
+  async exportAsSparseMatrix(options?: { nodeFilter?: ReadonlySet<string> }): Promise<SparseMatrix> {
+    const edges = await this.source.listEdges();
+    const entitySet = new Set<string>();
+    for (const e of edges) {
+      entitySet.add(e.fromEntity);
+      entitySet.add(e.toEntity);
+    }
+    if (options?.nodeFilter) {
+      for (const n of [...entitySet]) if (!options.nodeFilter.has(n)) entitySet.delete(n);
+    }
+
+    const entities = [...entitySet].sort();
+    const nodeIndex: Record<string, number> = {};
+    entities.forEach((n, i) => (nodeIndex[n] = i));
+
+    // Weight edges by confidence; if multiple relations exist between two
+    // entities, sum confidences (cap at 1).
+    const weights = new Map<string, number>();
+    for (const e of edges) {
+      const r = nodeIndex[e.fromEntity];
+      const c = nodeIndex[e.toEntity];
+      if (r === undefined || c === undefined || r === c) continue;
+      const key = `${r},${c}`;
+      weights.set(key, Math.min(1, (weights.get(key) ?? 0) + (e.confidence ?? 1)));
+    }
+    const entries: SparseEntry[] = [];
+    const rowSums = new Array<number>(entities.length).fill(0);
+    for (const [key, w] of weights) {
+      const [rStr, cStr] = key.split(',');
+      const r = Number(rStr);
+      const c = Number(cStr);
+      entries.push({ row: r, col: c, value: w });
+      rowSums[r] += w;
+    }
+    for (let i = 0; i < entities.length; i++) {
+      entries.push({ row: i, col: i, value: rowSums[i]! + this.ddSafetyMargin });
+    }
+    return {
+      graphId: this.graphId,
+      size: entities.length,
+      entries,
+      nodeIndex,
+      indexNode: entities,
+      capturedAt: new Date().toISOString(),
+      contentHash: hashContent(this.graphId, entries),
+    };
+  }
+}
+
+export function registerKnowledgeGraphAdapter(
+  options: KnowledgeGraphAdapterOptions & { registry?: AdapterRegistry },
+): KnowledgeGraphAdapter {
+  const adapter = new KnowledgeGraphAdapter(options);
+  (options.registry ?? getRegistry()).register(adapter);
+  return adapter;
+}
+
+function hashContent(graphId: string, entries: readonly SparseEntry[]): string {
+  const h = createHash('sha256');
+  h.update(graphId);
+  for (const e of entries) h.update(`|${e.row},${e.col},${e.value.toFixed(8)}`);
+  return h.digest('hex');
+}

package/src/adapters/observability-span-adapter.ts

@@ -0,0 +1,123 @@
+/**
+ * Observability Span Adapter (Wedge 7, ADR-123 Phase 3)
+ *
+ * `ruflo-observability` records spans (OpenTelemetry-style) with parent links
+ * + cross-trace causality. This adapter exports the span graph so the user
+ * can ask "which span most contributed to this slow/failed request" in
+ * O(log spans) instead of full-trace walks.
+ */
+
+import { createHash } from 'node:crypto';
+import type { SparseEntry, SparseMatrix } from '../domain/types.js';
+import type { SublinearAdapter, AdapterRegistry } from '../domain/adapter.js';
+import { getRegistry } from '../domain/adapter.js';
+
+export interface SpanRecord {
+  spanId: string;
+  parentSpanId?: string;
+  traceId: string;
+  /** Self-time in microseconds — used as edge weight. */
+  selfTimeUs: number;
+  /** Optional cross-trace causality link (e.g. an event triggered this trace). */
+  causedBySpanId?: string;
+}
+
+export interface ObservabilitySpanSource {
+  listSpans(traceId: string): Promise<readonly SpanRecord[]>;
+}
+
+export interface ObservabilitySpanAdapterOptions {
+  source: ObservabilitySpanSource;
+  traceId: string;
+  /** DD safety margin. Default 0.25. */
+  ddSafetyMargin?: number;
+}
+
+export function observabilityGraphId(traceId: string): string {
+  return `ruflo-observability:trace:${traceId}`;
+}
+
+export class ObservabilitySpanAdapter implements SublinearAdapter {
+  readonly graphId: string;
+  readonly ownerPlugin = 'ruflo-observability';
+  readonly requiresPreprocessing = false;
+
+  private readonly source: ObservabilitySpanSource;
+  private readonly traceId: string;
+  private readonly ddSafetyMargin: number;
+
+  constructor(options: ObservabilitySpanAdapterOptions) {
+    this.source = options.source;
+    this.traceId = options.traceId;
+    this.ddSafetyMargin = options.ddSafetyMargin ?? 0.25;
+    this.graphId = observabilityGraphId(this.traceId);
+  }
+
+  async exportAsSparseMatrix(options?: { nodeFilter?: ReadonlySet<string> }): Promise<SparseMatrix> {
+    const spans = await this.source.listSpans(this.traceId);
+    const idSet = new Set<string>();
+    for (const s of spans) {
+      idSet.add(s.spanId);
+      if (s.parentSpanId) idSet.add(s.parentSpanId);
+      if (s.causedBySpanId) idSet.add(s.causedBySpanId);
+    }
+    if (options?.nodeFilter) {
+      for (const n of [...idSet]) if (!options.nodeFilter.has(n)) idSet.delete(n);
+    }
+
+    const nodes = [...idSet].sort();
+    const nodeIndex: Record<string, number> = {};
+    nodes.forEach((n, i) => (nodeIndex[n] = i));
+
+    // Normalise self-time per parent: each parent's outbound weights sum to ≤1.
+    const childrenByParent = new Map<string, SpanRecord[]>();
+    for (const s of spans) {
+      const p = s.parentSpanId ?? s.causedBySpanId;
+      if (!p) continue;
+      if (!childrenByParent.has(p)) childrenByParent.set(p, []);
+      childrenByParent.get(p)!.push(s);
+    }
+
+    const entries: SparseEntry[] = [];
+    const rowSums = new Array<number>(nodes.length).fill(0);
+    for (const [parent, children] of childrenByParent) {
+      const r = nodeIndex[parent];
+      if (r === undefined) continue;
+      const total = children.reduce((s, c) => s + Math.max(1, c.selfTimeUs), 0);
+      for (const child of children) {
+        const c = nodeIndex[child.spanId];
+        if (c === undefined || c === r) continue;
+        const w = Math.max(1, child.selfTimeUs) / total;
+        entries.push({ row: r, col: c, value: w });
+        rowSums[r] += w;
+      }
+    }
+    for (let i = 0; i < nodes.length; i++) {
+      entries.push({ row: i, col: i, value: rowSums[i]! + this.ddSafetyMargin });
+    }
+    return {
+      graphId: this.graphId,
+      size: nodes.length,
+      entries,
+      nodeIndex,
+      indexNode: nodes,
+      capturedAt: new Date().toISOString(),
+      contentHash: hashContent(this.graphId, entries),
+    };
+  }
+}
+
+export function registerObservabilitySpanAdapter(
+  options: ObservabilitySpanAdapterOptions & { registry?: AdapterRegistry },
+): ObservabilitySpanAdapter {
+  const adapter = new ObservabilitySpanAdapter(options);
+  (options.registry ?? getRegistry()).register(adapter);
+  return adapter;
+}
+
+function hashContent(graphId: string, entries: readonly SparseEntry[]): string {
+  const h = createHash('sha256');
+  h.update(graphId);
+  for (const e of entries) h.update(`|${e.row},${e.col},${e.value.toFixed(8)}`);
+  return h.digest('hex');
+}

package/src/adapters/portfolio-cg-adapter.ts

@@ -0,0 +1,140 @@
+/**
+ * Portfolio Covariance Adapter (Wedge 8, ADR-123 Phase 5)
+ *
+ * `ruflo-neural-trader` does mean-variance optimisation: solve `Σ x = μ`
+ * where `Σ` is the symmetric positive-definite asset-covariance matrix and
+ * `μ` is the vector of expected returns. CG is the ideal target — upstream
+ * 1.7.0 benchmarks: **816 ns at n=256, 40-60× faster than Neumann**.
+ *
+ * This adapter exports the covariance matrix as a SparseMatrix so callers
+ * use `sublinear/solve` with `algorithm: 'cg'` and get the optimal weights.
+ * Unlike the PageRank wedges, this graph IS symmetric (Σ = Σᵀ) and SPD by
+ * construction.
+ */
+
+import { createHash } from 'node:crypto';
+import type { SparseEntry, SparseMatrix } from '../domain/types.js';
+import type { SublinearAdapter, AdapterRegistry } from '../domain/adapter.js';
+import { getRegistry } from '../domain/adapter.js';
+
+export interface CovarianceEntry {
+  /** Asset symbol on the row side. */
+  assetA: string;
+  /** Asset symbol on the column side. */
+  assetB: string;
+  /** Covariance value. Σ[A,B] = Σ[B,A] by SPD construction. */
+  covariance: number;
+}
+
+export interface PortfolioSource {
+  /**
+   * Dense or sparse covariance entries. Adapter symmetrises automatically
+   * if only one of (A,B) or (B,A) is provided.
+   */
+  listCovarianceEntries(portfolioId: string): Promise<readonly CovarianceEntry[]>;
+  /** Expected returns vector — same keys as covariance assets. */
+  listExpectedReturns(portfolioId: string): Promise<Record<string, number>>;
+}
+
+export interface PortfolioAdapterOptions {
+  source: PortfolioSource;
+  portfolioId: string;
+  /**
+   * Ridge regularisation added to the diagonal to ensure SPD even when the
+   * empirical covariance is rank-deficient. Default 1e-6.
+   */
+  ridge?: number;
+}
+
+export function portfolioGraphId(portfolioId: string): string {
+  return `ruflo-neural-trader:covariance:${portfolioId}`;
+}
+
+export class PortfolioCovarianceAdapter implements SublinearAdapter {
+  readonly graphId: string;
+  readonly ownerPlugin = 'ruflo-neural-trader';
+  readonly requiresPreprocessing = false;
+
+  private readonly source: PortfolioSource;
+  private readonly portfolioId: string;
+  private readonly ridge: number;
+
+  constructor(options: PortfolioAdapterOptions) {
+    this.source = options.source;
+    this.portfolioId = options.portfolioId;
+    this.ridge = options.ridge ?? 1e-6;
+    this.graphId = portfolioGraphId(this.portfolioId);
+  }
+
+  async exportAsSparseMatrix(options?: { nodeFilter?: ReadonlySet<string> }): Promise<SparseMatrix> {
+    const covEntries = await this.source.listCovarianceEntries(this.portfolioId);
+    const assetSet = new Set<string>();
+    for (const e of covEntries) {
+      assetSet.add(e.assetA);
+      assetSet.add(e.assetB);
+    }
+    if (options?.nodeFilter) {
+      for (const a of [...assetSet]) if (!options.nodeFilter.has(a)) assetSet.delete(a);
+    }
+
+    const assets = [...assetSet].sort();
+    const nodeIndex: Record<string, number> = {};
+    assets.forEach((a, i) => (nodeIndex[a] = i));
+
+    // Symmetrise. If only Σ[A,B] is provided, also emit Σ[B,A] with the same value.
+    const sym = new Map<string, number>();
+    for (const e of covEntries) {
+      const r = nodeIndex[e.assetA];
+      const c = nodeIndex[e.assetB];
+      if (r === undefined || c === undefined) continue;
+      const k1 = `${r},${c}`;
+      const k2 = `${c},${r}`;
+      sym.set(k1, e.covariance);
+      sym.set(k2, e.covariance);
+    }
+    const entries: SparseEntry[] = [];
+    for (const [key, v] of sym) {
+      const [rStr, cStr] = key.split(',');
+      const r = Number(rStr);
+      const c = Number(cStr);
+      if (r === c) continue;
+      entries.push({ row: r, col: c, value: v });
+    }
+    // Diagonal: existing variance value (if provided) PLUS ridge — keeps SPD
+    // even when the empirical Σ is rank-deficient.
+    for (let i = 0; i < assets.length; i++) {
+      const provided = sym.get(`${i},${i}`) ?? 0;
+      entries.push({ row: i, col: i, value: provided + this.ridge });
+    }
+    return {
+      graphId: this.graphId,
+      size: assets.length,
+      entries,
+      nodeIndex,
+      indexNode: assets,
+      capturedAt: new Date().toISOString(),
+      contentHash: hashContent(this.graphId, entries),
+    };
+  }
+
+  /** Fetch expected returns aligned with the matrix's node order. */
+  async expectedReturnsVector(matrix: SparseMatrix): Promise<number[]> {
+    const expected = await this.source.listExpectedReturns(this.portfolioId);
+    return matrix.indexNode.map((a) => expected[a] ?? 0);
+  }
+}
+
+export function registerPortfolioCovarianceAdapter(
+  options: PortfolioAdapterOptions & { registry?: AdapterRegistry },
+): PortfolioCovarianceAdapter {
+  const adapter = new PortfolioCovarianceAdapter(options);
+  (options.registry ?? getRegistry()).register(adapter);
+  return adapter;
+}
+
+function hashContent(graphId: string, entries: readonly SparseEntry[]): string {
+  const h = createHash('sha256');
+  h.update(graphId);
+  for (const e of entries) h.update(`|${e.row},${e.col},${e.value.toFixed(8)}`);
+  return h.digest('hex');
+}

package/src/adapters/rag-memory-adapter.ts

@@ -0,0 +1,117 @@
+/**
+ * RAG Memory Adapter (Wedge 5, ADR-123 Phase 4)
+ *
+ * `ruflo-rag-memory` ships Graph-RAG multi-hop retrieval. This adapter
+ * exports the chunk-connectivity graph so personalized PR seeded by the
+ * query embedding ranks candidate chunks globally — graph-aware retrieval
+ * beyond flat top-k MMR rerank.
+ *
+ * The seedNodes for personalized PR come from the caller's query side
+ * (`sublinear/page-rank-entry` already accepts seedNodes). This adapter
+ * just exposes the underlying chunk graph.
+ */
+
+import { createHash } from 'node:crypto';
+import type { SparseEntry, SparseMatrix } from '../domain/types.js';
+import type { SublinearAdapter, AdapterRegistry } from '../domain/adapter.js';
+import { getRegistry } from '../domain/adapter.js';
+
+export interface ChunkEdge {
+  fromChunkId: string;
+  toChunkId: string;
+  /** Similarity weight in [0, 1] — typically cosine similarity of chunk embeddings. */
+  similarity: number;
+}
+
+export interface RagMemorySource {
+  listChunkEdges(namespace?: string): Promise<readonly ChunkEdge[]>;
+}
+
+export interface RagMemoryAdapterOptions {
+  source: RagMemorySource;
+  namespace?: string;
+  /** Minimum similarity to include an edge. Default 0.5. */
+  similarityFloor?: number;
+  /** DD safety margin. Default 0.25. */
+  ddSafetyMargin?: number;
+}
+
+export function ragMemoryGraphId(namespace?: string): string {
+  return namespace
+    ? `ruflo-rag-memory:chunks:${namespace}`
+    : 'ruflo-rag-memory:chunks:default';
+}
+
+export class RagMemoryAdapter implements SublinearAdapter {
+  readonly graphId: string;
+  readonly ownerPlugin = 'ruflo-rag-memory';
+  readonly requiresPreprocessing = false;
+
+  private readonly source: RagMemorySource;
+  private readonly namespace?: string;
+  private readonly similarityFloor: number;
+  private readonly ddSafetyMargin: number;
+
+  constructor(options: RagMemoryAdapterOptions) {
+    this.source = options.source;
+    this.namespace = options.namespace;
+    this.similarityFloor = options.similarityFloor ?? 0.5;
+    this.ddSafetyMargin = options.ddSafetyMargin ?? 0.25;
+    this.graphId = ragMemoryGraphId(this.namespace);
+  }
+
+  async exportAsSparseMatrix(options?: { nodeFilter?: ReadonlySet<string> }): Promise<SparseMatrix> {
+    const edges = (await this.source.listChunkEdges(this.namespace)).filter(
+      (e) => e.similarity >= this.similarityFloor,
+    );
+    const chunkSet = new Set<string>();
+    for (const e of edges) {
+      chunkSet.add(e.fromChunkId);
+      chunkSet.add(e.toChunkId);
+    }
+    if (options?.nodeFilter) {
+      for (const n of [...chunkSet]) if (!options.nodeFilter.has(n)) chunkSet.delete(n);
+    }
+
+    const chunks = [...chunkSet].sort();
+    const nodeIndex: Record<string, number> = {};
+    chunks.forEach((n, i) => (nodeIndex[n] = i));
+
+    const entries: SparseEntry[] = [];
+    const rowSums = new Array<number>(chunks.length).fill(0);
+    for (const e of edges) {
+      const r = nodeIndex[e.fromChunkId];
+      const c = nodeIndex[e.toChunkId];
+      if (r === undefined || c === undefined || r === c) continue;
+      entries.push({ row: r, col: c, value: e.similarity });
+      rowSums[r] += e.similarity;
+    }
+    for (let i = 0; i < chunks.length; i++) {
+      entries.push({ row: i, col: i, value: rowSums[i]! + this.ddSafetyMargin });
+    }
+    return {
+      graphId: this.graphId,
+      size: chunks.length,
+      entries,
+      nodeIndex,
+      indexNode: chunks,
+      capturedAt: new Date().toISOString(),
+      contentHash: hashContent(this.graphId, entries),
+    };
+  }
+}
+
+export function registerRagMemoryAdapter(
+  options: RagMemoryAdapterOptions & { registry?: AdapterRegistry },
+): RagMemoryAdapter {
+  const adapter = new RagMemoryAdapter(options);
+  (options.registry ?? getRegistry()).register(adapter);
+  return adapter;
+}
+
+function hashContent(graphId: string, entries: readonly SparseEntry[]): string {
+  const h = createHash('sha256');
+  h.update(graphId);
+  for (const e of entries) h.update(`|${e.row},${e.col},${e.value.toFixed(8)}`);
+  return h.digest('hex');
+}