ruflo-graph-intelligence 0.1.0-alpha.1

package/tests/phase8-federation.test.ts

@@ -0,0 +1,194 @@
+/**
+ * Phase 8 Tests — Federation Distribution of Signed PR Vectors (beyond-SOTA)
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { FederationServer } from '../src/application/federation-server.js';
+import {
+  FederationClient,
+  inProcessTransport,
+} from '../src/application/federation-client.js';
+import { generateWitnessKey } from '../src/infrastructure/witness-signer.js';
+import { resetRegistry, getRegistry, type SublinearAdapter } from '../src/domain/adapter.js';
+import type { SparseMatrix } from '../src/domain/types.js';
+import { createHash } from 'node:crypto';
+
+function ddAdapter(graphId: string, n = 6): SublinearAdapter {
+  const entries = [];
+  const nodeIndex: Record<string, number> = {};
+  const indexNode: string[] = [];
+  for (let i = 0; i < n; i++) {
+    nodeIndex[`n${i}`] = i;
+    indexNode.push(`n${i}`);
+    entries.push({ row: i, col: i, value: 5 });
+    if (i > 0) entries.push({ row: i, col: i - 1, value: -1 });
+    if (i < n - 1) entries.push({ row: i, col: i + 1, value: -1 });
+  }
+  const contentHash = createHash('sha256')
+    .update(JSON.stringify({ graphId, n }))
+    .digest('hex');
+  const matrix: SparseMatrix = {
+    graphId,
+    size: n,
+    entries,
+    nodeIndex,
+    indexNode,
+    capturedAt: '2026-05-19T00:00:00Z',
+    contentHash,
+  };
+  return {
+    graphId,
+    ownerPlugin: 'test',
+    async exportAsSparseMatrix() {
+      return matrix;
+    },
+  };
+}
+
+describe('Federation round-trip', () => {
+  beforeEach(() => resetRegistry());
+
+  it('client receives a verifiable peer artifact', async () => {
+    const adapter = ddAdapter('fed:test', 6);
+    getRegistry().register(adapter);
+    const key = generateWitnessKey();
+    const server = new FederationServer({
+      installationId: 'inst-A',
+      witnessKey: key,
+      witnessKeyId: 'key-v1',
+      transport: { async send() { return null; }, onMessage() { return () => {}; } },
+    });
+    const client = new FederationClient({
+      installationId: 'inst-B',
+      transport: inProcessTransport(server),
+      trustedPublicKeys: [key.publicKeyHex],
+    });
+    const result = await client.fetchPageRank({
+      peer: 'inst-A',
+      graphId: 'fed:test',
+      nodeId: 'n2',
+    });
+    expect(result.origin).toBe('peer');
+    expect(result.verification?.valid).toBe(true);
+    expect(result.result.score).toBeGreaterThanOrEqual(0);
+  });
+
+  it('client falls back to local on untrusted signer', async () => {
+    const adapter = ddAdapter('fed:test', 6);
+    getRegistry().register(adapter);
+    const strangerKey = generateWitnessKey();
+    const server = new FederationServer({
+      installationId: 'inst-A',
+      witnessKey: strangerKey,
+      witnessKeyId: 'key-v1',
+      transport: { async send() { return null; }, onMessage() { return () => {}; } },
+    });
+    const client = new FederationClient({
+      installationId: 'inst-B',
+      transport: inProcessTransport(server),
+      trustedPublicKeys: ['0'.repeat(64)], // stranger NOT in trust list
+    });
+    const result = await client.fetchPageRank({
+      peer: 'inst-A',
+      graphId: 'fed:test',
+      nodeId: 'n2',
+    });
+    expect(result.origin).toBe('untrusted-fallback');
+    expect(result.fallbackReason).toMatch(/trusted list/i);
+    expect(result.result.score).toBeGreaterThanOrEqual(0);
+  });
+
+  it('server sends pr_artifact_stale when graphHash differs', async () => {
+    const adapter = ddAdapter('fed:test', 6);
+    getRegistry().register(adapter);
+    const key = generateWitnessKey();
+    const server = new FederationServer({
+      installationId: 'inst-A',
+      witnessKey: key,
+      witnessKeyId: 'key-v1',
+      transport: { async send() { return null; }, onMessage() { return () => {}; } },
+    });
+    const client = new FederationClient({
+      installationId: 'inst-B',
+      transport: inProcessTransport(server),
+      trustedPublicKeys: [key.publicKeyHex],
+    });
+    const result = await client.fetchPageRank({
+      peer: 'inst-A',
+      graphId: 'fed:test',
+      nodeId: 'n2',
+      lastKnownGraphHash: '0'.repeat(64), // doesn't match what server has
+    });
+    expect(result.origin).toBe('stale-fallback');
+    expect(result.fallbackReason).toMatch(/changed/);
+  });
+
+  it('server returns stale-reject for an unknown graphId', async () => {
+    const key = generateWitnessKey();
+    const server = new FederationServer({
+      installationId: 'inst-A',
+      witnessKey: key,
+      witnessKeyId: 'key-v1',
+      transport: { async send() { return null; }, onMessage() { return () => {}; } },
+    });
+    const client = new FederationClient({
+      installationId: 'inst-B',
+      transport: inProcessTransport(server),
+    });
+    // No adapter registered on client OR server side
+    try {
+      await client.fetchPageRank({
+        peer: 'inst-A',
+        graphId: 'fed:nonexistent',
+        nodeId: 'n2',
+      });
+      throw new Error('expected localCompute to throw');
+    } catch (err) {
+      expect((err as Error).message).toMatch(/no adapter/);
+    }
+  });
+
+  it('server rate-limits per peer', async () => {
+    const adapter = ddAdapter('fed:test', 6);
+    getRegistry().register(adapter);
+    const key = generateWitnessKey();
+    const server = new FederationServer({
+      installationId: 'inst-A',
+      witnessKey: key,
+      witnessKeyId: 'key-v1',
+      transport: { async send() { return null; }, onMessage() { return () => {}; } },
+      rateLimitPerPeerPerMinute: 2,
+    });
+    const client = new FederationClient({
+      installationId: 'inst-B',
+      transport: inProcessTransport(server),
+      trustedPublicKeys: [key.publicKeyHex],
+    });
+    const r1 = await client.fetchPageRank({ peer: 'inst-A', graphId: 'fed:test', nodeId: 'n2' });
+    const r2 = await client.fetchPageRank({ peer: 'inst-A', graphId: 'fed:test', nodeId: 'n3' });
+    const r3 = await client.fetchPageRank({ peer: 'inst-A', graphId: 'fed:test', nodeId: 'n4' });
+    expect(r1.origin).toBe('peer');
+    expect(r2.origin).toBe('peer');
+    expect(r3.origin).toBe('stale-fallback');
+    expect(r3.fallbackReason).toMatch(/rate limit/i);
+  });
+
+  it('client falls back to local compute when no usable response', async () => {
+    const adapter = ddAdapter('fed:test', 6);
+    getRegistry().register(adapter);
+    const client = new FederationClient({
+      installationId: 'inst-B',
+      transport: {
+        async send() { return null; }, // server unreachable
+        onMessage() { return () => {}; },
+      },
+    });
+    const result = await client.fetchPageRank({
+      peer: 'inst-A',
+      graphId: 'fed:test',
+      nodeId: 'n2',
+    });
+    expect(result.origin).toBe('local-fallback');
+    expect(result.result.score).toBeGreaterThanOrEqual(0);
+  });
+});

package/tests/solver-bridge.test.ts

@@ -0,0 +1,255 @@
+/**
+ * ruflo-graph-intelligence — Solver Bridge Tests (ADR-123 Phase 1)
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  coherenceScore,
+  checkCoherence,
+  singleEntryPageRank,
+  conjugateGradient,
+  neumann,
+  solveOnChange,
+  observedComplexity,
+  hashResult,
+  runPageRank,
+} from '../src/infrastructure/solver-bridge.js';
+import { fitsBudget, isEdgeSafe, type SparseMatrix, type PageRankQuery } from '../src/domain/types.js';
+
+/** Build a small DD matrix for tests. */
+function ddMatrix(n: number): SparseMatrix {
+  const entries = [];
+  const nodeIndex: Record<string, number> = {};
+  const indexNode: string[] = [];
+  for (let i = 0; i < n; i++) {
+    nodeIndex[`n${i}`] = i;
+    indexNode.push(`n${i}`);
+    entries.push({ row: i, col: i, value: 5 });
+    if (i > 0) entries.push({ row: i, col: i - 1, value: -1 });
+    if (i < n - 1) entries.push({ row: i, col: i + 1, value: -1 });
+  }
+  return {
+    graphId: `test-dd-${n}`,
+    size: n,
+    entries,
+    nodeIndex,
+    indexNode,
+    capturedAt: '2026-05-19T00:00:00Z',
+  };
+}
+
+describe('coherence', () => {
+  it('reports positive coherence for a clean DD matrix', () => {
+    const m = ddMatrix(8);
+    const score = coherenceScore(m);
+    expect(score).toBeGreaterThan(0);
+    expect(score).toBeLessThanOrEqual(1);
+  });
+
+  it('passes the gate when threshold is below score', () => {
+    const m = ddMatrix(8);
+    const r = checkCoherence(m, 0.1);
+    expect(r.passed).toBe(true);
+    expect(r.score).toBeGreaterThan(0.1);
+  });
+
+  it('rejects when threshold exceeds score', () => {
+    const m = ddMatrix(8);
+    const r = checkCoherence(m, 0.99);
+    expect(r.passed).toBe(false);
+  });
+
+  it('reports −∞ for a zero-diagonal matrix', () => {
+    const m: SparseMatrix = {
+      graphId: 'singular',
+      size: 2,
+      entries: [{ row: 0, col: 1, value: 1 }],
+      nodeIndex: { a: 0, b: 1 },
+      indexNode: ['a', 'b'],
+      capturedAt: 't',
+    };
+    expect(coherenceScore(m)).toBe(-Infinity);
+  });
+});
+
+describe('complexity class budget', () => {
+  it('logarithmic fits within linear', () => {
+    expect(fitsBudget('logarithmic', 'linear')).toBe(true);
+  });
+
+  it('linearithmic does NOT fit within linear', () => {
+    expect(fitsBudget('linearithmic', 'linear')).toBe(false);
+  });
+
+  it('polylogarithmic is edge-safe', () => {
+    expect(isEdgeSafe('polylogarithmic')).toBe(true);
+  });
+
+  it('linear is NOT edge-safe', () => {
+    expect(isEdgeSafe('linear')).toBe(false);
+  });
+
+  it('observedComplexity reports logarithmic when iterations ≤ log2(n)', () => {
+    const obs = observedComplexity(3, 100);
+    expect(['constant', 'logarithmic']).toContain(obs);
+  });
+
+  it('observedComplexity reports linear when iterations ≈ n', () => {
+    expect(observedComplexity(100, 100)).toBe('linear');
+  });
+});
+
+describe('singleEntryPageRank', () => {
+  it('returns a non-negative score for a registered node', () => {
+    const m = ddMatrix(10);
+    const query: PageRankQuery = {
+      graphId: m.graphId,
+      nodeId: 'n5',
+      alpha: 0.85,
+      epsilon: 1e-3,
+      seedNodes: [],
+      maxComplexityClass: 'linear',
+      coherenceThreshold: 0,
+    };
+    const { score, iterations } = singleEntryPageRank(m, query);
+    expect(score).toBeGreaterThanOrEqual(0);
+    expect(iterations).toBeGreaterThan(0);
+  });
+
+  it('returns 0 for an unknown node', () => {
+    const m = ddMatrix(10);
+    const { score } = singleEntryPageRank(m, {
+      graphId: m.graphId,
+      nodeId: 'absent',
+      alpha: 0.85,
+      epsilon: 1e-3,
+      seedNodes: [],
+      maxComplexityClass: 'linear',
+      coherenceThreshold: 0,
+    });
+    expect(score).toBe(0);
+  });
+
+  it('honours personalized seed nodes', () => {
+    const m = ddMatrix(10);
+    const seeded = singleEntryPageRank(m, {
+      graphId: m.graphId,
+      nodeId: 'n0',
+      alpha: 0.85,
+      epsilon: 1e-3,
+      seedNodes: ['n0'],
+      maxComplexityClass: 'linear',
+      coherenceThreshold: 0,
+    });
+    const unseeded = singleEntryPageRank(m, {
+      graphId: m.graphId,
+      nodeId: 'n0',
+      alpha: 0.85,
+      epsilon: 1e-3,
+      seedNodes: [],
+      maxComplexityClass: 'linear',
+      coherenceThreshold: 0,
+    });
+    expect(seeded.score).toBeGreaterThan(unseeded.score);
+  });
+});
+
+describe('conjugateGradient', () => {
+  it('solves A·x = b on a DD system to residual < 1e-6', () => {
+    const m = ddMatrix(8);
+    const b = Array.from({ length: 8 }, () => 1);
+    const { x, residualNorm, iterations } = conjugateGradient(m, b, { epsilon: 1e-8, maxIter: 50 });
+    expect(x).toHaveLength(8);
+    expect(residualNorm).toBeLessThan(1e-6);
+    expect(iterations).toBeLessThan(50);
+  });
+});
+
+describe('neumann', () => {
+  it('converges on a DD system', () => {
+    const m = ddMatrix(8);
+    const b = Array.from({ length: 8 }, () => 1);
+    const { residualNorm, iterations } = neumann(m, b, { epsilon: 1e-6, maxIter: 200 });
+    expect(iterations).toBeLessThan(200);
+    expect(residualNorm).toBeLessThan(1e-3);
+  });
+});
+
+describe('solveOnChange', () => {
+  it('produces x ≈ x_full when delta points at the same RHS', () => {
+    const m = ddMatrix(8);
+    const b = Array.from({ length: 8 }, () => 1);
+    const baseline = conjugateGradient(m, b, { epsilon: 1e-8 });
+
+    const prev = new Array<number>(8).fill(0);
+    const delta = { indices: Array.from({ length: 8 }, (_, i) => i), values: b };
+    const { x } = solveOnChange(m, prev, delta, { epsilon: 1e-8, algorithm: 'cg' });
+
+    for (let i = 0; i < 8; i++) {
+      expect(Math.abs(x[i]! - baseline.x[i]!)).toBeLessThan(1e-3);
+    }
+  });
+
+  it('handles sparse delta (only one node updated)', () => {
+    const m = ddMatrix(8);
+    const prev = new Array<number>(8).fill(0.1);
+    const delta = { indices: [3], values: [0.5] };
+    const { x, iterations } = solveOnChange(m, prev, delta, { epsilon: 1e-8, algorithm: 'cg' });
+    expect(iterations).toBeLessThan(50);
+    expect(x).toHaveLength(8);
+  });
+});
+
+describe('hashResult', () => {
+  it('is deterministic for the same inputs', () => {
+    const a = hashResult({ graphId: 'g', nodeId: 'n', alpha: 0.85, epsilon: 1e-3, seedNodes: [], score: 0.123 });
+    const b = hashResult({ graphId: 'g', nodeId: 'n', alpha: 0.85, epsilon: 1e-3, seedNodes: [], score: 0.123 });
+    expect(a).toBe(b);
+  });
+
+  it('differs when content differs', () => {
+    const a = hashResult({ graphId: 'g', nodeId: 'n', alpha: 0.85, epsilon: 1e-3, seedNodes: [], score: 0.1 });
+    const b = hashResult({ graphId: 'g', nodeId: 'n', alpha: 0.85, epsilon: 1e-3, seedNodes: [], score: 0.2 });
+    expect(a).not.toBe(b);
+  });
+
+  it('treats seedNodes order as canonical', () => {
+    const a = hashResult({ graphId: 'g', nodeId: 'n', alpha: 0.85, epsilon: 1e-3, seedNodes: ['a', 'b'], score: 0.1 });
+    const b = hashResult({ graphId: 'g', nodeId: 'n', alpha: 0.85, epsilon: 1e-3, seedNodes: ['b', 'a'], score: 0.1 });
+    expect(a).toBe(b);
+  });
+});
+
+describe('runPageRank — error paths', () => {
+  it('throws coherence-rejected when threshold not met', () => {
+    const m = ddMatrix(8);
+    expect(() =>
+      runPageRank(m, {
+        graphId: m.graphId,
+        nodeId: 'n0',
+        alpha: 0.85,
+        epsilon: 1e-3,
+        seedNodes: [],
+        maxComplexityClass: 'linear',
+        coherenceThreshold: 0.99,
+      }),
+    ).toThrow();
+  });
+
+  it('returns a populated result on the happy path', () => {
+    const m = ddMatrix(8);
+    const result = runPageRank(m, {
+      graphId: m.graphId,
+      nodeId: 'n3',
+      alpha: 0.85,
+      epsilon: 1e-3,
+      seedNodes: [],
+      maxComplexityClass: 'linear',
+      coherenceThreshold: 0,
+    });
+    expect(result.score).toBeGreaterThanOrEqual(0);
+    expect(result.complexityClass).toBeDefined();
+    expect(result.coherence.passed).toBe(true);
+    expect(result.resultHash).toMatch(/^[0-9a-f]{64}$/);
+  });
+});

package/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "tests"]
+}

package/vitest.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    include: ['tests/**/*.test.ts'],
+    environment: 'node',
+    globals: false,
+  },
+});