ruflo-graph-intelligence 0.1.0-alpha.1

package/src/mcp-tools/index.ts

@@ -0,0 +1,316 @@
+/**
+ * ruflo-graph-intelligence — MCP Tool Surface (ADR-123 § Architecture)
+ *
+ * Six tools mounted under `sublinear/*`:
+ *   - sublinear/page-rank-entry  — single-entry PPR (workhorse)
+ *   - sublinear/solve            — full A·x = b
+ *   - sublinear/solve-on-change  — incremental delta (Wedge 12, streaming)
+ *   - sublinear/feasibility      — packing/covering LP feasibility
+ *   - sublinear/jl-embed         — Johnson-Lindenstrauss projection
+ *   - sublinear/analyze          — diagnostics (coherence, sparsity, recommended algo)
+ *
+ * Every tool accepts maxComplexityClass + coherenceThreshold.
+ */
+
+import { getRegistry } from '../domain/adapter.js';
+import {
+  PageRankQuerySchema,
+  SolveQuerySchema,
+  SolveOnChangeQuerySchema,
+} from '../domain/types.js';
+import {
+  runPageRank,
+  runSolve,
+  runSolveOnChange,
+  coherenceScore,
+  checkCoherence,
+} from '../infrastructure/solver-bridge.js';
+
+export interface MCPTool {
+  name: string;
+  description: string;
+  category: string;
+  inputSchema: {
+    type: 'object';
+    properties: Record<string, unknown>;
+    required?: string[];
+  };
+  handler: (input: Record<string, unknown>) => Promise<unknown>;
+}
+
+export const graphIntelligenceTools: MCPTool[] = [
+  {
+    name: 'sublinear/page-rank-entry',
+    description:
+      'Single-entry personalized PageRank over a registered RuFlo graph. O(log n) on DD inputs. Returns score + observed complexity-class + coherence margin. Accepts maxComplexityClass budget gate (default linear) and coherenceThreshold (default 0 = disabled).',
+    category: 'graph-intelligence',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        graphId: { type: 'string', description: 'Adapter-registered graph identifier' },
+        nodeId: { type: 'string', description: 'Node to compute PR score for (single-entry query)' },
+        alpha: { type: 'number', description: 'Damping factor (default 0.85)' },
+        epsilon: { type: 'number', description: 'Convergence target (default 1e-3)' },
+        seedNodes: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'For personalized PR — seed nodes carrying restart distribution',
+        },
+        maxComplexityClass: {
+          type: 'string',
+          description: '12-tier upstream class budget (constant/logarithmic/polylogarithmic/sublinear/linear/...); default linear',
+        },
+        coherenceThreshold: {
+          type: 'number',
+          description: 'DD margin floor in [-∞, 1] (default 0 = disabled)',
+        },
+      },
+      required: ['graphId', 'nodeId'],
+    },
+    handler: async (input) => {
+      const query = PageRankQuerySchema.parse(input);
+      const adapter = getRegistry().get(query.graphId);
+      if (!adapter) {
+        return { success: false, error: { kind: 'graph-not-found', message: `no adapter for graphId=${query.graphId}` } };
+      }
+      const matrix = await adapter.exportAsSparseMatrix();
+      try {
+        const result = runPageRank(matrix, query);
+        return { success: true, result };
+      } catch (err) {
+        return { success: false, error: err };
+      }
+    },
+  },
+
+  {
+    name: 'sublinear/solve',
+    description:
+      'Full linear solve A·x = b over a registered graph. CG (symmetric PD) or Neumann (general DD). Returns x + residual + observed complexity-class + coherence margin.',
+    category: 'graph-intelligence',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        graphId: { type: 'string' },
+        rhs: { type: 'array', items: { type: 'number' } },
+        algorithm: { type: 'string', enum: ['cg', 'neumann', 'random-walk'] },
+        maxComplexityClass: { type: 'string' },
+        coherenceThreshold: { type: 'number' },
+      },
+      required: ['graphId', 'rhs'],
+    },
+    handler: async (input) => {
+      const query = SolveQuerySchema.parse(input);
+      const adapter = getRegistry().get(query.graphId);
+      if (!adapter) {
+        return { success: false, error: { kind: 'graph-not-found', message: `no adapter for graphId=${query.graphId}` } };
+      }
+      const matrix = await adapter.exportAsSparseMatrix();
+      try {
+        const result = runSolve(matrix, query);
+        return { success: true, result };
+      } catch (err) {
+        return { success: false, error: err };
+      }
+    },
+  },
+
+  {
+    name: 'sublinear/solve-on-change',
+    description:
+      'Incremental solve A·dx = δ then x_new = x_prev + dx (Wedge 12, ADR-123). For event-driven streaming systems (federation trust deltas, span streams, append-only causal breaks). Sparse δ → asymptotically faster than full re-solve.',
+    category: 'graph-intelligence',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        graphId: { type: 'string' },
+        prevSolution: { type: 'array', items: { type: 'number' } },
+        delta: {
+          type: 'object',
+          properties: {
+            indices: { type: 'array', items: { type: 'number' } },
+            values: { type: 'array', items: { type: 'number' } },
+          },
+        },
+        algorithm: { type: 'string', enum: ['cg', 'neumann'] },
+        maxComplexityClass: { type: 'string' },
+      },
+      required: ['graphId', 'prevSolution', 'delta'],
+    },
+    handler: async (input) => {
+      const query = SolveOnChangeQuerySchema.parse(input);
+      const adapter = getRegistry().get(query.graphId);
+      if (!adapter) {
+        return { success: false, error: { kind: 'graph-not-found', message: `no adapter for graphId=${query.graphId}` } };
+      }
+      const matrix = await adapter.exportAsSparseMatrix();
+      try {
+        const result = runSolveOnChange(matrix, query);
+        return { success: true, result };
+      } catch (err) {
+        return { success: false, error: err };
+      }
+    },
+  },
+
+  {
+    name: 'sublinear/analyze',
+    description:
+      'Diagnostic report on a registered graph: coherence margin (DD), sparsity, square-size, recommended algorithm. Use before sublinear/solve to choose algorithm + budget.',
+    category: 'graph-intelligence',
+    inputSchema: {
+      type: 'object',
+      properties: { graphId: { type: 'string' } },
+      required: ['graphId'],
+    },
+    handler: async (input) => {
+      const graphId = input.graphId as string;
+      const adapter = getRegistry().get(graphId);
+      if (!adapter) {
+        return { success: false, error: { kind: 'graph-not-found', message: `no adapter for graphId=${graphId}` } };
+      }
+      const matrix = await adapter.exportAsSparseMatrix();
+      const coherence = checkCoherence(matrix, 0);
+      const nonzeros = matrix.entries.length;
+      const density = nonzeros / (matrix.size * matrix.size);
+      const recommendedAlgorithm = density < 0.01 ? 'forward-push' : coherence.score > 0 ? 'cg' : 'neumann';
+      return {
+        success: true,
+        result: {
+          graphId,
+          size: matrix.size,
+          nonzeros,
+          density,
+          coherenceScore: coherence.score,
+          isDiagonallyDominant: coherence.score > 0,
+          recommendedAlgorithm,
+        },
+      };
+    },
+  },
+
+  {
+    name: 'sublinear/feasibility',
+    description:
+      'Packing/covering LP feasibility check (Kyng-Sachdeva style). Wedge 9 — pre-flight check before invoking A* / heavy planners.',
+    category: 'graph-intelligence',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        constraints: { type: 'array', description: 'A·x ≤ b constraint set' },
+        tolerance: { type: 'number', description: 'Slack for soft constraints (default 0.05)' },
+        maxComplexityClass: { type: 'string' },
+      },
+      required: ['constraints'],
+    },
+    handler: async (input) => {
+      // Phase 6: relaxed packing/covering LP. Each constraint is a row Aᵢ
+      // with shape { coeffs: Record<varId, number>, bound: number, kind: 'leq'|'geq'|'eq' }.
+      // The relaxed check: does there exist x ≥ 0 satisfying all constraints within `tolerance`?
+      // For Phase 6 we ship a tight bounded-variable LP via a simple Lagrangian
+      // shrink-on-violation pass. Real Kyng–Sachdeva solver wires in Phase 7+.
+      const constraints = (input.constraints as Array<{
+        coeffs: Record<string, number>;
+        bound: number;
+        kind?: 'leq' | 'geq' | 'eq';
+      }>) ?? [];
+      const tolerance = (input.tolerance as number) ?? 0.05;
+      if (constraints.length === 0) {
+        return { success: true, result: { feasible: true, witness: {}, method: 'no-constraints' } };
+      }
+      // Collect variables; initialise x = 0 (the trivial point).
+      const varSet = new Set<string>();
+      for (const c of constraints) for (const k of Object.keys(c.coeffs)) varSet.add(k);
+      const vars = [...varSet];
+      const x: Record<string, number> = {};
+      for (const v of vars) x[v] = 0;
+      // 200-iter Lagrangian shrink: for each violated row, push x toward
+      // satisfaction by a small step proportional to violation magnitude.
+      const stepSize = 0.05;
+      for (let it = 0; it < 200; it++) {
+        let maxViolation = 0;
+        for (const c of constraints) {
+          let lhs = 0;
+          for (const [k, w] of Object.entries(c.coeffs)) lhs += (x[k] ?? 0) * w;
+          const kind = c.kind ?? 'leq';
+          let violation = 0;
+          if (kind === 'leq' && lhs > c.bound) violation = lhs - c.bound;
+          else if (kind === 'geq' && lhs < c.bound) violation = c.bound - lhs;
+          else if (kind === 'eq') violation = Math.abs(lhs - c.bound);
+          if (violation > maxViolation) maxViolation = violation;
+          if (violation === 0) continue;
+          for (const [k, w] of Object.entries(c.coeffs)) {
+            if (w === 0) continue;
+            const direction = kind === 'leq' ? -Math.sign(w) : Math.sign(w);
+            x[k] = Math.max(0, (x[k] ?? 0) + direction * stepSize * (violation / Math.abs(w)));
+          }
+        }
+        if (maxViolation <= tolerance) {
+          return { success: true, result: { feasible: true, witness: x, iterations: it + 1, method: 'lagrangian-shrink' } };
+        }
+      }
+      // Couldn't satisfy within iteration cap — infeasibility certificate
+      // is the residual violation vector.
+      const residuals = constraints.map((c) => {
+        let lhs = 0;
+        for (const [k, w] of Object.entries(c.coeffs)) lhs += (x[k] ?? 0) * w;
+        return { lhs, bound: c.bound, kind: c.kind ?? 'leq' };
+      });
+      return {
+        success: true,
+        result: {
+          feasible: false,
+          witness: x,
+          certificateOfInfeasibility: residuals,
+          method: 'lagrangian-shrink (capped)',
+        },
+      };
+    },
+  },
+
+  {
+    name: 'sublinear/jl-embed',
+    description:
+      'Johnson-Lindenstrauss projection. Maps vectors to a target dimension with ε-distortion. Replaces @claude-flow/embeddings hand-rolled JL (closes ADR-121 Phase 4 follow-up).',
+    category: 'graph-intelligence',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        vectors: { type: 'array', description: 'Input vectors' },
+        targetDim: { type: 'number' },
+        epsilon: { type: 'number' },
+      },
+      required: ['vectors', 'targetDim'],
+    },
+    handler: async (input) => {
+      // Phase 6: real JL via jlEmbed (replaces ADR-121 hand-rolled).
+      const { jlEmbed } = await import('../infrastructure/jl-embed.js');
+      const vectors = (input.vectors as number[][]) ?? [];
+      const targetDim = (input.targetDim as number) ?? 64;
+      const epsilon = (input.epsilon as number) ?? 0.1;
+      try {
+        const result = jlEmbed(vectors, { targetDim, epsilon });
+        return {
+          success: true,
+          result: {
+            projected: result.projected,
+            targetDim: result.targetDim,
+            distortionBound: result.epsilon,
+            withinAchlioptasBound: result.withinAchlioptasBound,
+            method: 'real JL — Gaussian projection with k ≤ n−1 cap',
+          },
+        };
+      } catch (err) {
+        return {
+          success: false,
+          error: {
+            kind: 'invalid-input',
+            message: err instanceof Error ? err.message : String(err),
+          },
+        };
+      }
+    },
+  },
+];
+
+export default graphIntelligenceTools;

package/tests/adapter-registry.test.ts

@@ -0,0 +1,69 @@
+/**
+ * ruflo-graph-intelligence — Adapter Registry Tests (ADR-123 Phase 1)
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { AdapterRegistry, getRegistry, resetRegistry } from '../src/domain/adapter.js';
+import type { SublinearAdapter } from '../src/domain/adapter.js';
+import type { SparseMatrix } from '../src/domain/types.js';
+
+function fakeAdapter(graphId: string): SublinearAdapter {
+  return {
+    graphId,
+    ownerPlugin: 'test',
+    async exportAsSparseMatrix(): Promise<SparseMatrix> {
+      return {
+        graphId,
+        size: 1,
+        entries: [{ row: 0, col: 0, value: 1 }],
+        nodeIndex: { only: 0 },
+        indexNode: ['only'],
+        capturedAt: 't',
+      };
+    },
+  };
+}
+
+describe('AdapterRegistry', () => {
+  beforeEach(() => resetRegistry());
+
+  it('registers + retrieves an adapter', () => {
+    const r = new AdapterRegistry();
+    const a = fakeAdapter('test:graph');
+    r.register(a);
+    expect(r.get('test:graph')).toBe(a);
+  });
+
+  it('throws on duplicate registration', () => {
+    const r = new AdapterRegistry();
+    r.register(fakeAdapter('test:graph'));
+    expect(() => r.register(fakeAdapter('test:graph'))).toThrow(/already registered/);
+  });
+
+  it('unregister removes the adapter', () => {
+    const r = new AdapterRegistry();
+    r.register(fakeAdapter('test:graph'));
+    expect(r.unregister('test:graph')).toBe(true);
+    expect(r.get('test:graph')).toBeUndefined();
+  });
+
+  it('list returns all adapters', () => {
+    const r = new AdapterRegistry();
+    r.register(fakeAdapter('a'));
+    r.register(fakeAdapter('b'));
+    expect(r.list()).toHaveLength(2);
+  });
+
+  it('getRegistry returns a singleton', () => {
+    const r1 = getRegistry();
+    const r2 = getRegistry();
+    expect(r1).toBe(r2);
+  });
+
+  it('resetRegistry forces a new instance', () => {
+    const r1 = getRegistry();
+    resetRegistry();
+    const r2 = getRegistry();
+    expect(r1).not.toBe(r2);
+  });
+});

package/tests/browser-causal-adapter.test.ts

@@ -0,0 +1,174 @@
+/**
+ * Browser Causal-Recovery Adapter Tests (Wedge 1, ADR-123 Phase 2)
+ *
+ * Acceptance:
+ *  - Exports a SparseMatrix whose dimensions match the node-set
+ *  - Result matrix is diagonally-dominant (coherence > 0)
+ *  - Time-decay weights older events less
+ *  - registerBrowserCausalAdapter() puts the adapter in the registry under
+ *    the canonical `browser:causal:<origin>` graphId
+ *  - sublinear/page-rank-entry routes through the adapter end-to-end
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import {
+  BrowserCausalAdapter,
+  browserCausalGraphId,
+  registerBrowserCausalAdapter,
+  type BreakEventLike,
+  type BreakEventSource,
+} from '../src/adapters/browser-causal-adapter.js';
+import { resetRegistry, getRegistry } from '../src/domain/adapter.js';
+import { coherenceScore } from '../src/infrastructure/solver-bridge.js';
+import { graphIntelligenceTools } from '../src/mcp-tools/index.js';
+
+function stubSource(events: BreakEventLike[]): BreakEventSource {
+  return {
+    async listBreaks(origin) {
+      return events.filter((e) => e.origin === origin);
+    },
+  };
+}
+
+function evt(partial: Partial<BreakEventLike> & Pick<BreakEventLike, 'id' | 'selector' | 'origin'>): BreakEventLike {
+  return {
+    timestamp: '2026-05-19T00:00:00.000Z',
+    ...partial,
+  };
+}
+
+describe('browserCausalGraphId', () => {
+  it('encodes origin into a stable identifier', () => {
+    expect(browserCausalGraphId('https://example.com')).toBe('browser:causal:https://example.com');
+  });
+});
+
+describe('BrowserCausalAdapter.exportAsSparseMatrix', () => {
+  it('returns an empty matrix when there are no break events', async () => {
+    const adapter = new BrowserCausalAdapter({
+      origin: 'https://empty.test',
+      source: stubSource([]),
+    });
+    const m = await adapter.exportAsSparseMatrix();
+    expect(m.size).toBe(0);
+    expect(m.entries).toHaveLength(0);
+  });
+
+  it('builds a DD matrix from a chronological event sequence', async () => {
+    const adapter = new BrowserCausalAdapter({
+      origin: 'https://example.com',
+      source: stubSource([
+        evt({ id: 'b1', origin: 'https://example.com', selector: '@e1', timestamp: '2026-05-19T00:00:00.000Z' }),
+        evt({ id: 'b2', origin: 'https://example.com', selector: '@e2', timestamp: '2026-05-19T00:00:01.000Z' }),
+        evt({ id: 'b3', origin: 'https://example.com', selector: '@e3', timestamp: '2026-05-19T00:00:02.000Z' }),
+      ]),
+    });
+    const m = await adapter.exportAsSparseMatrix();
+    expect(m.size).toBe(3);
+    expect(coherenceScore(m)).toBeGreaterThan(0);
+    expect(m.contentHash).toMatch(/^[0-9a-f]{64}$/);
+  });
+
+  it('honours nodeFilter to prune irrelevant rows', async () => {
+    const adapter = new BrowserCausalAdapter({
+      origin: 'https://example.com',
+      source: stubSource([
+        evt({ id: 'b1', origin: 'https://example.com', selector: '@e1' }),
+        evt({ id: 'b2', origin: 'https://example.com', selector: '@e2' }),
+        evt({ id: 'b3', origin: 'https://example.com', selector: '@e3' }),
+      ]),
+    });
+    const m = await adapter.exportAsSparseMatrix({ nodeFilter: new Set(['@e1', '@e2']) });
+    expect(m.size).toBe(2);
+    expect(Object.keys(m.nodeIndex).sort()).toEqual(['@e1', '@e2']);
+  });
+
+  it('records (role:name) fuzzy keys when present', async () => {
+    const adapter = new BrowserCausalAdapter({
+      origin: 'https://example.com',
+      source: stubSource([
+        evt({
+          id: 'b1',
+          origin: 'https://example.com',
+          selector: '@e3',
+          lastKnownRole: 'button',
+          lastKnownName: 'Submit',
+        }),
+        evt({
+          id: 'b2',
+          origin: 'https://example.com',
+          selector: '@e3',
+          lastKnownRole: 'button',
+          lastKnownName: 'Submit',
+        }),
+      ]),
+    });
+    const m = await adapter.exportAsSparseMatrix();
+    expect(Object.keys(m.nodeIndex)).toContain('role:button:Submit');
+  });
+
+  it('time-decays older events relative to newer ones', async () => {
+    const oneHour = 60 * 60 * 1000;
+    const now = Date.now();
+    const events: BreakEventLike[] = [
+      evt({ id: 'old1', origin: 'https://x.com', selector: 'a', timestamp: new Date(now - 240 * oneHour).toISOString() }),
+      evt({ id: 'old2', origin: 'https://x.com', selector: 'b', timestamp: new Date(now - 239 * oneHour).toISOString() }),
+      evt({ id: 'new1', origin: 'https://x.com', selector: 'a', timestamp: new Date(now - oneHour).toISOString() }),
+      evt({ id: 'new2', origin: 'https://x.com', selector: 'b', timestamp: new Date(now).toISOString() }),
+    ];
+    const adapter = new BrowserCausalAdapter({
+      origin: 'https://x.com',
+      source: stubSource(events),
+      halfLifeMs: 24 * oneHour,
+    });
+    const m = await adapter.exportAsSparseMatrix();
+    // Find the a→b edge: at least one entry should exist; the weight should
+    // be dominated by the recent event-pair, not the old one.
+    const aIdx = m.nodeIndex['a'];
+    const bIdx = m.nodeIndex['b'];
+    const offDiag = m.entries.filter((e) => e.row === aIdx && e.col === bIdx);
+    expect(offDiag.length).toBeGreaterThan(0);
+    // The accumulated decay should be small for old pair, ~1.0 for recent.
+    const totalWeight = offDiag.reduce((s, e) => s + e.value, 0);
+    // Recent pair contributes ~1.0, old pair contributes ~ exp(-239/24) ≈ 4e-5.
+    expect(totalWeight).toBeGreaterThan(0.5);
+    expect(totalWeight).toBeLessThan(2);
+  });
+});
+
+describe('registerBrowserCausalAdapter', () => {
+  beforeEach(() => resetRegistry());
+
+  it('registers under the canonical graph id', () => {
+    const registry = getRegistry();
+    registerBrowserCausalAdapter({
+      origin: 'https://example.com',
+      source: stubSource([]),
+      registry,
+    });
+    expect(registry.get('browser:causal:https://example.com')).toBeDefined();
+  });
+
+  it('end-to-end: sublinear/page-rank-entry resolves through the registered adapter', async () => {
+    const registry = getRegistry();
+    registerBrowserCausalAdapter({
+      origin: 'https://example.com',
+      source: stubSource([
+        evt({ id: 'b1', origin: 'https://example.com', selector: '@e1' }),
+        evt({ id: 'b2', origin: 'https://example.com', selector: '@e2' }),
+        evt({ id: 'b3', origin: 'https://example.com', selector: '@e3' }),
+      ]),
+      registry,
+    });
+    const tool = graphIntelligenceTools.find((t) => t.name === 'sublinear/page-rank-entry');
+    expect(tool).toBeDefined();
+    const r = (await tool!.handler({
+      graphId: 'browser:causal:https://example.com',
+      nodeId: '@e2',
+      maxComplexityClass: 'polynomial',
+    })) as { success: boolean; result?: { score: number; complexityClass: string } };
+    expect(r.success).toBe(true);
+    expect(r.result?.score).toBeGreaterThanOrEqual(0);
+    expect(r.result?.complexityClass).toBeDefined();
+  });
+});