ruflo-graph-intelligence 0.1.0-alpha.1

package/src/domain/signed-artifact.ts

@@ -0,0 +1,80 @@
+/**
+ * Signed PageRank Artifact (Phase 7 — beyond-SOTA, ADR-123)
+ *
+ * RuFlo gains a primitive no competing memory framework can ship: a portable,
+ * Ed25519-signed PageRank result that carries enough metadata for a remote
+ * peer to verify provenance + budget compliance + input stability without
+ * trusting the producer. Federation peers exchange these instead of
+ * re-walking graphs.
+ *
+ * Schema mirrors the ADR-123 Architecture diagram with the upstream 1.7.0
+ * additions: `complexity_class` (budget compliance) + `coherence_score`
+ * (DD-margin at compute time).
+ */
+
+import { z } from 'zod';
+import {
+  ComplexityClassSchema,
+  PageRankResultSchema,
+  type PageRankResult,
+} from './types.js';
+
+export const ARTIFACT_ENVELOPE_VERSION = '1.0.0';
+export const ARTIFACT_ENVELOPE_KIND = 'pagerank';
+
+export const SignedPageRankPayloadSchema = z.object({
+  envelopeVersion: z.literal(ARTIFACT_ENVELOPE_VERSION),
+  kind: z.literal(ARTIFACT_ENVELOPE_KIND),
+  installationId: z.string().min(1),
+  /** Witness key ID (key version, not key identity per ADR-103). */
+  witnessKeyId: z.string().min(1),
+  /** Ed25519 public key (hex, 32 bytes). */
+  publicKey: z.string().regex(/^[0-9a-f]{64}$/),
+  /** Adapter graph id (e.g. `ruflo-federation:trust-mesh`). */
+  graphId: z.string().min(1),
+  /** SHA-256 of the input matrix's `contentHash`. */
+  graphHash: z.string().regex(/^[0-9a-f]{64}$/),
+  /** Wall-clock at compute time. */
+  graphTimestamp: z.string(),
+  algorithm: z.enum(['forward-push', 'backward-push', 'bidirectional', 'cg', 'neumann']),
+  alpha: z.number().positive().lt(1),
+  epsilon: z.number().positive(),
+  /** Query node — None for full-vector artifacts. */
+  queryNode: z.string().optional(),
+  /** Seed nodes (PPR). Empty for plain PR. */
+  seedNodes: z.array(z.string()),
+  /** Result (single-entry or full-vector). */
+  result: PageRankResultSchema,
+  /** Class the solver actually achieved (echoes result.complexityClass). */
+  complexityClass: ComplexityClassSchema,
+  /** Coherence margin at compute time (echoes result.coherence.score). */
+  coherenceScore: z.number(),
+  /** Hash of `result` (echoes result.resultHash). */
+  resultHash: z.string().regex(/^[0-9a-f]{64}$/),
+  /** When the envelope was sealed. */
+  sealedAt: z.string(),
+  /** Solver version used. */
+  solverVersion: z.string().default('sublinear-time-solver@1.7.0'),
+});
+export type SignedPageRankPayload = z.infer<typeof SignedPageRankPayloadSchema>;
+
+export const SignedPageRankEnvelopeSchema = z.object({
+  payload: SignedPageRankPayloadSchema,
+  signature: z.string().regex(/^[0-9a-f]{128}$/),
+  algorithm: z.literal('ed25519'),
+});
+export type SignedPageRankEnvelope = z.infer<typeof SignedPageRankEnvelopeSchema>;
+
+export interface ArtifactVerificationResult {
+  valid: boolean;
+  signatureValid: boolean;
+  schemaValid: boolean;
+  /** True iff graphHash + resultHash + signature all check out. */
+  integrityValid: boolean;
+  publicKey?: string;
+  /** Complexity class echo — callers can budget against this. */
+  complexityClass?: PageRankResult['complexityClass'];
+  /** Coherence margin echo — callers can sanity-check input stability. */
+  coherenceScore?: number;
+  reason?: string;
+}

package/src/domain/types.ts

@@ -0,0 +1,215 @@
+/**
+ * ruflo-graph-intelligence — Domain Types (ADR-123)
+ *
+ * Core type contract: SparseMatrix shape, ComplexityClass budget, coherence
+ * threshold, signed PR artifact envelope. These are the wire types every
+ * adapter, MCP tool, and federation peer agrees on.
+ */
+
+import { z } from 'zod';
+
+// ============================================================================
+// SparseMatrix — the adapter handover shape
+// ============================================================================
+
+export const SparseEntrySchema = z.object({
+  row: z.number().int().nonnegative(),
+  col: z.number().int().nonnegative(),
+  value: z.number().finite(),
+});
+export type SparseEntry = z.infer<typeof SparseEntrySchema>;
+
+export const SparseMatrixSchema = z.object({
+  /** Stable identifier — e.g. "ruflo-federation:trust-mesh:2026-05-19T01:00:00Z". */
+  graphId: z.string().min(1),
+  /** Number of rows / columns (square). */
+  size: z.number().int().positive(),
+  /** Non-zero entries. */
+  entries: z.array(SparseEntrySchema),
+  /** Node-id → row-index lookup so callers can talk in domain identifiers. */
+  nodeIndex: z.record(z.number().int().nonnegative()),
+  /** Reverse lookup row-index → node-id. */
+  indexNode: z.array(z.string()),
+  /** When the snapshot was taken (ISO). */
+  capturedAt: z.string(),
+  /** Optional content hash for memoization + signed-artifact integrity. */
+  contentHash: z.string().regex(/^[0-9a-f]{64}$/).optional(),
+});
+export type SparseMatrix = z.infer<typeof SparseMatrixSchema>;
+
+// ============================================================================
+// Complexity class — runtime governance budget
+// ============================================================================
+
+/**
+ * 12-tier upstream `sublinear-time-solver@1.7.0` taxonomy. Ordered.
+ * Lower-cost classes are at the top; Adaptive wraps a (default, worst) pair.
+ */
+export const ComplexityClassSchema = z.enum([
+  'constant',         // O(1)
+  'logarithmic',      // O(log n)
+  'polylogarithmic',  // O((log n)^k)
+  'sublinear',        // O(n^α) for α < 1
+  'linear',           // O(n)
+  'linearithmic',     // O(n log n)
+  'polynomial',       // O(n^k)
+  'exponential',      // O(2^n)
+  'doubleExponential',// O(2^(2^n))
+  'adaptive',         // see adaptiveBound
+  'unknown',
+  'unbounded',
+]);
+export type ComplexityClass = z.infer<typeof ComplexityClassSchema>;
+
+/** For Adaptive: default + worst-case both reported. */
+export interface AdaptiveBound {
+  default: ComplexityClass;
+  worst: ComplexityClass;
+}
+
+/** Ordering — index = cost rank, so `rank('logarithmic') < rank('linear')`. */
+const COMPLEXITY_RANK: Record<ComplexityClass, number> = {
+  constant: 0,
+  logarithmic: 1,
+  polylogarithmic: 2,
+  sublinear: 3,
+  linear: 4,
+  linearithmic: 5,
+  polynomial: 6,
+  exponential: 7,
+  doubleExponential: 8,
+  adaptive: 4, // worst-case treated as Linear for budget comparisons by default
+  unknown: 8,
+  unbounded: 9,
+};
+
+/** Is `actual` within `budget`? */
+export function fitsBudget(actual: ComplexityClass, budget: ComplexityClass): boolean {
+  return COMPLEXITY_RANK[actual] <= COMPLEXITY_RANK[budget];
+}
+
+/** Pi-Zero-safe ≈ at most polylogarithmic. */
+export function isEdgeSafe(c: ComplexityClass): boolean {
+  return COMPLEXITY_RANK[c] <= COMPLEXITY_RANK['polylogarithmic'];
+}
+
+// ============================================================================
+// Coherence — DD margin for graph stability monitoring
+// ============================================================================
+
+export const CoherenceReportSchema = z.object({
+  /** Per-row margin (min over rows of (|diag| − Σ|off|) / |diag|). Range (−∞, 1]. */
+  score: z.number(),
+  /** Did the matrix pass the configured threshold? */
+  passed: z.boolean(),
+  /** Threshold used. 0 = gate disabled (wire-compatible default). */
+  threshold: z.number(),
+});
+export type CoherenceReport = z.infer<typeof CoherenceReportSchema>;
+
+// ============================================================================
+// PageRank query + result
+// ============================================================================
+
+export const PageRankQuerySchema = z.object({
+  graphId: z.string(),
+  /** Single-entry query — the node we want the PR score for. */
+  nodeId: z.string(),
+  /** Damping factor. Default 0.85. */
+  alpha: z.number().positive().lt(1).default(0.85),
+  /** ε convergence target. Default 1e-3. */
+  epsilon: z.number().positive().default(1e-3),
+  /** For personalized PR — seed nodes weighted as the restart distribution. */
+  seedNodes: z.array(z.string()).default([]),
+  /** Budget gate. Default `linear` (tier-2-safe). */
+  maxComplexityClass: ComplexityClassSchema.default('linear'),
+  /** DD-margin floor. 0 = disabled. */
+  coherenceThreshold: z.number().default(0),
+});
+export type PageRankQuery = z.infer<typeof PageRankQuerySchema>;
+
+export const PageRankResultSchema = z.object({
+  graphId: z.string(),
+  nodeId: z.string(),
+  score: z.number(),
+  alpha: z.number(),
+  epsilon: z.number(),
+  iterations: z.number().int().nonnegative(),
+  /** Class the solver actually used. */
+  complexityClass: ComplexityClassSchema,
+  /** Coherence report attached at compute time. */
+  coherence: CoherenceReportSchema,
+  computedAt: z.string(),
+  /** Hash of (graphId, nodeId, alpha, epsilon, seedNodes, score). Stable for memoization. */
+  resultHash: z.string().regex(/^[0-9a-f]{64}$/),
+});
+export type PageRankResult = z.infer<typeof PageRankResultSchema>;
+
+// ============================================================================
+// Solve (full vector)
+// ============================================================================
+
+export const SolveQuerySchema = z.object({
+  graphId: z.string(),
+  rhs: z.array(z.number()),
+  algorithm: z.enum(['cg', 'neumann', 'random-walk']).default('cg'),
+  maxComplexityClass: ComplexityClassSchema.default('linear'),
+  coherenceThreshold: z.number().default(0),
+});
+export type SolveQuery = z.infer<typeof SolveQuerySchema>;
+
+export const SolveResultSchema = z.object({
+  graphId: z.string(),
+  x: z.array(z.number()),
+  residualNorm: z.number(),
+  iterations: z.number().int().nonnegative(),
+  complexityClass: ComplexityClassSchema,
+  coherence: CoherenceReportSchema,
+  computedAt: z.string(),
+});
+export type SolveResult = z.infer<typeof SolveResultSchema>;
+
+// ============================================================================
+// Incremental solve (Wedge 12 — streaming)
+// ============================================================================
+
+export const SparseDeltaSchema = z.object({
+  indices: z.array(z.number().int().nonnegative()),
+  values: z.array(z.number()),
+});
+export type SparseDelta = z.infer<typeof SparseDeltaSchema>;
+
+export const SolveOnChangeQuerySchema = z.object({
+  graphId: z.string(),
+  prevSolution: z.array(z.number()),
+  delta: SparseDeltaSchema,
+  algorithm: z.enum(['cg', 'neumann']).default('cg'),
+  maxComplexityClass: ComplexityClassSchema.default('linear'),
+});
+export type SolveOnChangeQuery = z.infer<typeof SolveOnChangeQuerySchema>;
+
+// ============================================================================
+// Structured errors
+// ============================================================================
+
+export const GraphIntelErrorKindSchema = z.enum([
+  'complexity-budget-exceeded',
+  'coherence-rejected',
+  'graph-not-found',
+  'invalid-input',
+  'solver-failed',
+  'not-applicable',
+]);
+export type GraphIntelErrorKind = z.infer<typeof GraphIntelErrorKindSchema>;
+
+export interface GraphIntelError {
+  kind: GraphIntelErrorKind;
+  message: string;
+  recoverable: boolean;
+  /** If `complexity-budget-exceeded`: what class was needed vs requested. */
+  requiredClass?: ComplexityClass;
+  requestedClass?: ComplexityClass;
+  /** If `coherence-rejected`: actual vs threshold. */
+  coherence?: number;
+  threshold?: number;
+}

package/src/index.ts

@@ -0,0 +1,105 @@
+/**
+ * ruflo-graph-intelligence — RuFlo Graph Intelligence Engine (ADR-123)
+ *
+ * Real-time relationship intelligence with complexity-aware execution.
+ *
+ * Three-layer architecture:
+ *   Neural Layer        — adaptive learning (existing — @claude-flow/neural)
+ *   Graph Intelligence  — relationship reasoning (this plugin)
+ *   Complexity Layer    — runtime governance (this plugin)
+ *
+ * Built on `sublinear-time-solver@1.7.0`.
+ */
+
+// Domain
+export * from './domain/types.js';
+export {
+  AdapterRegistry,
+  getRegistry,
+  resetRegistry,
+  noopUnsubscribe,
+  type SublinearAdapter,
+} from './domain/adapter.js';
+
+// Infrastructure
+export {
+  coherenceScore,
+  checkCoherence,
+  singleEntryPageRank,
+  conjugateGradient,
+  neumann,
+  solveOnChange,
+  hashResult,
+  observedComplexity,
+  runPageRank,
+  runSolve,
+  runSolveOnChange,
+} from './infrastructure/solver-bridge.js';
+
+// MCP tools
+export { graphIntelligenceTools, type MCPTool } from './mcp-tools/index.js';
+
+// Adapters (per-wedge integrations)
+export * from './adapters/index.js';
+
+// JL embedding (ADR-121 follow-up)
+export { jlEmbed, computeTargetDim, type JLEmbedOptions, type JLEmbedResult } from './infrastructure/jl-embed.js';
+
+// Streaming bridge (Wedge 12)
+export {
+  StreamingBridge,
+  type StreamingBridgeOptions,
+  type StreamingUpdate,
+} from './application/streaming-bridge.js';
+
+// Federation protocol (Phase 8 — beyond-SOTA)
+export {
+  PrArtifactRequestSchema,
+  PrArtifactResponseSchema,
+  PrArtifactDeltaSchema,
+  PrArtifactStaleSchema,
+  FederationMessageSchema,
+  type PrArtifactRequest,
+  type PrArtifactResponse,
+  type PrArtifactDelta,
+  type PrArtifactStale,
+  type FederationMessage,
+  type FederationTransport,
+} from './domain/federation-protocol.js';
+export {
+  FederationServer,
+  type FederationServerOptions,
+} from './application/federation-server.js';
+export {
+  FederationClient,
+  inProcessTransport,
+  type FederationClientOptions,
+  type FetchPrResult,
+} from './application/federation-client.js';
+
+// Signed PR artifacts (Phase 7 — beyond-SOTA)
+export {
+  ARTIFACT_ENVELOPE_VERSION,
+  ARTIFACT_ENVELOPE_KIND,
+  SignedPageRankEnvelopeSchema,
+  SignedPageRankPayloadSchema,
+  type SignedPageRankEnvelope,
+  type SignedPageRankPayload,
+  type ArtifactVerificationResult,
+} from './domain/signed-artifact.js';
+export {
+  generateWitnessKey,
+  loadWitnessKey,
+  resolveWitnessKey,
+  sealArtifact,
+  verifyArtifact,
+  canonicalJSON,
+  sha256Hex,
+  type WitnessKey,
+  type SealArtifactInput,
+} from './infrastructure/witness-signer.js';
+
+// Default export
+import { graphIntelligenceTools } from './mcp-tools/index.js';
+import { getRegistry } from './domain/adapter.js';
+export default { tools: graphIntelligenceTools, registry: getRegistry };

package/src/infrastructure/jl-embed.ts

@@ -0,0 +1,98 @@
+/**
+ * Johnson-Lindenstrauss embedding (Wedge: ADR-121 follow-up, ADR-123 Phase 6)
+ *
+ * Replaces `@claude-flow/embeddings`' hand-rolled hand-rolled JL with a
+ * tested implementation that obeys the Achlioptas / Dasgupta-Gupta bound
+ * `target_dim ≤ original_dim − 1`. Matches the upstream
+ * `sublinear-time-solver@1.7.0` JL contract.
+ */
+
+import { createHash } from 'node:crypto';
+
+/** Deterministic Gaussian RNG seeded by content hash so embeddings are reproducible. */
+function* gaussianStream(seed: string): IterableIterator<number> {
+  // Box-Muller from a deterministic PRNG seeded by the hash.
+  let counter = 0;
+  while (true) {
+    const h = createHash('sha256').update(seed + ':' + counter++).digest();
+    // Two 32-bit floats in [0,1) per hash
+    const u1 = (h.readUInt32BE(0) >>> 0) / 0x100000000;
+    const u2 = (h.readUInt32BE(4) >>> 0) / 0x100000000;
+    const r = Math.sqrt(-2 * Math.log(Math.max(u1, 1e-12)));
+    const theta = 2 * Math.PI * u2;
+    yield r * Math.cos(theta);
+    yield r * Math.sin(theta);
+  }
+}
+
+/** Cap target dim at `n − 1` (Achlioptas / Dasgupta-Gupta). */
+export function computeTargetDim(originalDim: number, requestedDim: number, epsilon: number): number {
+  const cap = Math.max(1, originalDim - 1);
+  const k = Math.min(cap, requestedDim);
+  // Documentation: the literature bound is k ≥ 4 log(n) / ε². We honour the
+  // user's requested target unless it exceeds the cap.
+  return Math.max(1, Math.min(cap, k));
+}
+
+export interface JLEmbedOptions {
+  targetDim: number;
+  epsilon?: number;
+  /** Seed for the projection matrix. Default 'ruflo-jl-v1' so it's reproducible. */
+  seed?: string;
+}
+
+export interface JLEmbedResult {
+  projected: number[][];
+  targetDim: number;
+  /** ε from the input, echoed for reporting. */
+  epsilon: number;
+  /** Confirmed within k ≤ n − 1 bound. */
+  withinAchlioptasBound: boolean;
+}
+
+/** Project a list of vectors to `targetDim` via a random Gaussian matrix. */
+export function jlEmbed(vectors: number[][], options: JLEmbedOptions): JLEmbedResult {
+  if (vectors.length === 0) {
+    return {
+      projected: [],
+      targetDim: 0,
+      epsilon: options.epsilon ?? 0.1,
+      withinAchlioptasBound: true,
+    };
+  }
+  const originalDim = vectors[0]!.length;
+  const target = computeTargetDim(originalDim, options.targetDim, options.epsilon ?? 0.1);
+  const seed = options.seed ?? 'ruflo-jl-v1';
+
+  // Construct the k × n projection matrix R, then project each vector.
+  const stream = gaussianStream(seed);
+  const R = new Array<Float64Array>(target);
+  for (let i = 0; i < target; i++) {
+    const row = new Float64Array(originalDim);
+    for (let j = 0; j < originalDim; j++) row[j] = stream.next().value as number;
+    R[i] = row;
+  }
+
+  // Scaling: each entry has Var = 1, so multiply by 1/√k to keep ‖Rv‖² ≈ ‖v‖²
+  const scale = 1 / Math.sqrt(target);
+  const projected: number[][] = [];
+  for (const v of vectors) {
+    if (v.length !== originalDim) {
+      throw new Error(`jlEmbed: vector dim ${v.length} ≠ expected ${originalDim}`);
+    }
+    const out = new Array<number>(target);
+    for (let i = 0; i < target; i++) {
+      let s = 0;
+      const row = R[i]!;
+      for (let j = 0; j < originalDim; j++) s += row[j]! * v[j]!;
+      out[i] = s * scale;
+    }
+    projected.push(out);
+  }
+  return {
+    projected,
+    targetDim: target,
+    epsilon: options.epsilon ?? 0.1,
+    withinAchlioptasBound: target <= Math.max(1, originalDim - 1),
+  };
+}