ruflo-graph-intelligence 0.1.0-alpha.1

package/src/application/federation-client.ts

@@ -0,0 +1,147 @@
+/**
+ * Federation Client for PR Artifacts (Phase 8 — beyond-SOTA, ADR-123)
+ *
+ * Sends `pr_artifact_request` to peers, verifies inbound `pr_artifact_response`
+ * envelopes via Phase 7 verifier with the consumer's trust list, falls back
+ * to local recompute on stale/untrusted responses.
+ */
+
+import { verifyArtifact } from '../infrastructure/witness-signer.js';
+import { runPageRank } from '../infrastructure/solver-bridge.js';
+import { getRegistry } from '../domain/adapter.js';
+import type {
+  FederationMessage,
+  FederationTransport,
+  PrArtifactRequest,
+  PrArtifactResponse,
+  PrArtifactStale,
+} from '../domain/federation-protocol.js';
+import type { ArtifactVerificationResult } from '../domain/signed-artifact.js';
+import type { PageRankResult } from '../domain/types.js';
+
+export interface FederationClientOptions {
+  installationId: string;
+  transport: FederationTransport;
+  /** Public keys we trust. Empty = trust any valid signature. */
+  trustedPublicKeys?: string[];
+}
+
+export interface FetchPrResult {
+  /** How the result was obtained. */
+  origin: 'peer' | 'local-fallback' | 'stale-fallback' | 'untrusted-fallback';
+  result: PageRankResult;
+  /** If origin === 'peer', the verification report. */
+  verification?: ArtifactVerificationResult;
+  /** Optional reason when we fell back. */
+  fallbackReason?: string;
+}
+
+export class FederationClient {
+  private readonly installationId: string;
+  private readonly transport: FederationTransport;
+  private readonly trustedPublicKeys: string[];
+
+  constructor(options: FederationClientOptions) {
+    this.installationId = options.installationId;
+    this.transport = options.transport;
+    this.trustedPublicKeys = options.trustedPublicKeys ?? [];
+  }
+
+  /**
+   * Fetch a single-entry PR score for `nodeId` over `graphId`. Tries the
+   * peer first; on stale/untrusted/missing, falls back to local recompute.
+   */
+  async fetchPageRank(input: {
+    peer: string;
+    graphId: string;
+    nodeId: string;
+    alpha?: number;
+    epsilon?: number;
+    seedNodes?: string[];
+    lastKnownGraphHash?: string;
+    lastKnownResultHash?: string;
+  }): Promise<FetchPrResult> {
+    const request: PrArtifactRequest = {
+      type: 'pr_artifact_request',
+      fromInstallation: this.installationId,
+      graphId: input.graphId,
+      queryNode: input.nodeId,
+      alpha: input.alpha ?? 0.85,
+      epsilon: input.epsilon ?? 1e-3,
+      seedNodes: input.seedNodes ?? [],
+      lastKnownGraphHash: input.lastKnownGraphHash,
+      lastKnownResultHash: input.lastKnownResultHash,
+    };
+    const response = await this.transport.send(input.peer, request);
+    if (response && response.type === 'pr_artifact_response') {
+      const verification = verifyArtifact(response.envelope, {
+        trustedPublicKeys: this.trustedPublicKeys.length > 0 ? this.trustedPublicKeys : undefined,
+      });
+      if (verification.valid) {
+        return {
+          origin: 'peer',
+          result: response.envelope.payload.result,
+          verification,
+        };
+      }
+      return {
+        origin: 'untrusted-fallback',
+        result: await this.localCompute(input),
+        verification,
+        fallbackReason: verification.reason ?? 'verification failed',
+      };
+    }
+    if (response && response.type === 'pr_artifact_stale') {
+      return {
+        origin: 'stale-fallback',
+        result: await this.localCompute(input),
+        fallbackReason: response.reason,
+      };
+    }
+    // No usable response
+    return {
+      origin: 'local-fallback',
+      result: await this.localCompute(input),
+      fallbackReason: 'no usable response from peer',
+    };
+  }
+
+  private async localCompute(input: {
+    graphId: string;
+    nodeId: string;
+    alpha?: number;
+    epsilon?: number;
+    seedNodes?: string[];
+  }): Promise<PageRankResult> {
+    const adapter = getRegistry().get(input.graphId);
+    if (!adapter) {
+      throw new Error(`localCompute: no adapter for graphId=${input.graphId}`);
+    }
+    const matrix = await adapter.exportAsSparseMatrix();
+    return runPageRank(matrix, {
+      graphId: input.graphId,
+      nodeId: input.nodeId,
+      alpha: input.alpha ?? 0.85,
+      epsilon: input.epsilon ?? 1e-3,
+      seedNodes: input.seedNodes ?? [],
+      maxComplexityClass: 'polynomial',
+      coherenceThreshold: 0,
+    });
+  }
+}
+
+/**
+ * Helper: an in-process transport stitching a client to a server. Useful for
+ * testing the Phase 8 round-trip without spinning up real ADR-104 wiring.
+ */
+export function inProcessTransport(server: { handle: (msg: FederationMessage) => Promise<FederationMessage | null> }): FederationTransport {
+  return {
+    async send(_to, msg) {
+      return server.handle(msg);
+    },
+    onMessage() {
+      // not used in the in-process variant
+      return () => {};
+    },
+  };
+}

package/src/application/federation-server.ts

@@ -0,0 +1,158 @@
+/**
+ * Federation Server for PR Artifacts (Phase 8 — beyond-SOTA, ADR-123)
+ *
+ * Receives `pr_artifact_request` messages and serves either a fresh signed
+ * artifact (if the holder has one cached or computes one on demand) or a
+ * stale-rejection. The server uses Phase 7's sealArtifact for signing and
+ * Phase 2-6 adapters for graph access.
+ *
+ * Pluggable via FederationTransport so ADR-104's real wire layer fits in
+ * unchanged.
+ */
+
+import { sealArtifact, type WitnessKey } from '../infrastructure/witness-signer.js';
+import { runPageRank } from '../infrastructure/solver-bridge.js';
+import { getRegistry } from '../domain/adapter.js';
+import type {
+  FederationMessage,
+  FederationTransport,
+  PrArtifactRequest,
+  PrArtifactResponse,
+  PrArtifactStale,
+} from '../domain/federation-protocol.js';
+
+export interface FederationServerOptions {
+  installationId: string;
+  witnessKey: WitnessKey;
+  witnessKeyId: string;
+  transport: FederationTransport;
+  /** Per-graph rate-limit budget — requests per peer per minute. */
+  rateLimitPerPeerPerMinute?: number;
+}
+
+interface RateBucket {
+  count: number;
+  resetAt: number;
+}
+
+export class FederationServer {
+  private readonly installationId: string;
+  private readonly witnessKey: WitnessKey;
+  private readonly witnessKeyId: string;
+  private readonly transport: FederationTransport;
+  private readonly rateLimit: number;
+  private rateBuckets = new Map<string, RateBucket>();
+  private unsubscribe?: () => void;
+
+  constructor(options: FederationServerOptions) {
+    this.installationId = options.installationId;
+    this.witnessKey = options.witnessKey;
+    this.witnessKeyId = options.witnessKeyId;
+    this.transport = options.transport;
+    this.rateLimit = options.rateLimitPerPeerPerMinute ?? 60;
+  }
+
+  start(): void {
+    this.unsubscribe = this.transport.onMessage((m) => this.handle(m));
+  }
+
+  stop(): void {
+    this.unsubscribe?.();
+  }
+
+  /** Public test seam — handles a single inbound message. */
+  async handle(msg: FederationMessage): Promise<FederationMessage | null> {
+    if (msg.type !== 'pr_artifact_request') return null;
+    return this.handleRequest(msg);
+  }
+
+  private async handleRequest(req: PrArtifactRequest): Promise<FederationMessage> {
+    // Rate-limit per peer
+    if (!this.checkRate(req.fromInstallation)) {
+      return {
+        type: 'pr_artifact_stale',
+        fromInstallation: this.installationId,
+        graphId: req.graphId,
+        currentGraphHash: 'rate-limited'.padEnd(64, '0'),
+        reason: 'rate limit exceeded',
+      } satisfies PrArtifactStale;
+    }
+
+    const adapter = getRegistry().get(req.graphId);
+    if (!adapter) {
+      return {
+        type: 'pr_artifact_stale',
+        fromInstallation: this.installationId,
+        graphId: req.graphId,
+        currentGraphHash: '0'.repeat(64),
+        reason: `no adapter for graphId=${req.graphId}`,
+      } satisfies PrArtifactStale;
+    }
+
+    const matrix = await adapter.exportAsSparseMatrix();
+    const currentGraphHash = matrix.contentHash ?? '0'.repeat(64);
+
+    // Stale-check: if the requester's lastKnownGraphHash differs, send stale
+    if (req.lastKnownGraphHash && req.lastKnownGraphHash !== currentGraphHash) {
+      return {
+        type: 'pr_artifact_stale',
+        fromInstallation: this.installationId,
+        graphId: req.graphId,
+        currentGraphHash,
+        reason: 'graph has changed since requester last cached',
+      } satisfies PrArtifactStale;
+    }
+
+    if (!req.queryNode) {
+      return {
+        type: 'pr_artifact_stale',
+        fromInstallation: this.installationId,
+        graphId: req.graphId,
+        currentGraphHash,
+        reason: 'full-vector requests not yet supported (Phase 8 only)',
+      } satisfies PrArtifactStale;
+    }
+
+    // Compute and seal
+    const prResult = runPageRank(matrix, {
+      graphId: req.graphId,
+      nodeId: req.queryNode,
+      alpha: req.alpha,
+      epsilon: req.epsilon,
+      seedNodes: req.seedNodes,
+      maxComplexityClass: 'polynomial',
+      coherenceThreshold: 0,
+    });
+    const { envelope } = sealArtifact({
+      installationId: this.installationId,
+      witnessKeyId: this.witnessKeyId,
+      graphId: req.graphId,
+      graphHash: currentGraphHash,
+      graphTimestamp: matrix.capturedAt,
+      algorithm: 'forward-push',
+      alpha: req.alpha,
+      epsilon: req.epsilon,
+      queryNode: req.queryNode,
+      seedNodes: req.seedNodes,
+      result: prResult,
+      witnessKey: this.witnessKey,
+    });
+    return {
+      type: 'pr_artifact_response',
+      fromInstallation: this.installationId,
+      envelope,
+    } satisfies PrArtifactResponse;
+  }
+
+  private checkRate(peer: string): boolean {
+    const now = Date.now();
+    const bucket = this.rateBuckets.get(peer);
+    if (!bucket || now >= bucket.resetAt) {
+      this.rateBuckets.set(peer, { count: 1, resetAt: now + 60_000 });
+      return true;
+    }
+    if (bucket.count >= this.rateLimit) return false;
+    bucket.count++;
+    return true;
+  }
+}

package/src/application/streaming-bridge.ts

@@ -0,0 +1,137 @@
+/**
+ * Streaming Bridge — Wedge 12 (ADR-123 Phase 6.5)
+ *
+ * Couples a registered SublinearAdapter with `solve_on_change` so event-driven
+ * graphs (federation trust deltas, span streams, append-only causal breaks,
+ * cost spend events, AIDefence flag updates) pay only `O(nnz(delta) · log N)`
+ * per event rather than recomputing the full vector each tick.
+ *
+ * The bridge maintains the *previous solution* in memory; every push call
+ * applies the delta and returns the updated solution. It also exposes a
+ * `crossoverHeuristic()` that decides whether the cheap delta path is
+ * actually cheaper than a full re-solve given the current density.
+ */
+
+import type { SublinearAdapter } from '../domain/adapter.js';
+import type { ComplexityClass, SparseDelta, SparseMatrix } from '../domain/types.js';
+import { runSolveOnChange, runSolve } from '../infrastructure/solver-bridge.js';
+
+export interface StreamingBridgeOptions {
+  adapter: SublinearAdapter;
+  /** Initial b vector for the base full-solve. */
+  initialRhs: number[];
+  algorithm?: 'cg' | 'neumann';
+  maxComplexityClass?: ComplexityClass;
+  /**
+   * Crossover threshold: prefer `solve_on_change` when
+   * `nnz(delta) / nnz(matrix) < deltaRatioThreshold`. Default 0.05.
+   */
+  deltaRatioThreshold?: number;
+  /** Force full re-solve after N delta updates regardless. Default 50. */
+  refreshEvery?: number;
+}
+
+export interface StreamingUpdate {
+  x: number[];
+  residualNorm: number;
+  iterations: number;
+  /** How this update was computed — informational. */
+  mode: 'delta' | 'full-resolve' | 'cold-start';
+  deltaNnz?: number;
+  appliedAt: string;
+}
+
+export class StreamingBridge {
+  private readonly adapter: SublinearAdapter;
+  private readonly initialRhs: number[];
+  private readonly algorithm: 'cg' | 'neumann';
+  private readonly maxComplexityClass: ComplexityClass;
+  private readonly deltaRatioThreshold: number;
+  private readonly refreshEvery: number;
+
+  private prevSolution: number[] | undefined;
+  private deltaCount = 0;
+  private cachedMatrix: SparseMatrix | undefined;
+
+  constructor(options: StreamingBridgeOptions) {
+    this.adapter = options.adapter;
+    this.initialRhs = options.initialRhs;
+    this.algorithm = options.algorithm ?? 'cg';
+    this.maxComplexityClass = options.maxComplexityClass ?? 'polynomial';
+    this.deltaRatioThreshold = options.deltaRatioThreshold ?? 0.05;
+    this.refreshEvery = options.refreshEvery ?? 50;
+  }
+
+  /** Force a fresh full re-solve and reset the streaming state. */
+  async coldStart(): Promise<StreamingUpdate> {
+    const matrix = await this.adapter.exportAsSparseMatrix();
+    this.cachedMatrix = matrix;
+    const result = runSolve(matrix, {
+      graphId: matrix.graphId,
+      rhs: this.initialRhs,
+      algorithm: this.algorithm,
+      maxComplexityClass: this.maxComplexityClass,
+      coherenceThreshold: 0,
+    });
+    this.prevSolution = result.x;
+    this.deltaCount = 0;
+    return {
+      x: result.x,
+      residualNorm: result.residualNorm,
+      iterations: result.iterations,
+      mode: 'cold-start',
+      appliedAt: new Date().toISOString(),
+    };
+  }
+
+  /**
+   * Apply a delta event. The bridge picks `solve_on_change` if the delta is
+   * sparse enough; otherwise it falls back to a full re-solve.
+   */
+  async pushDelta(delta: SparseDelta): Promise<StreamingUpdate> {
+    if (!this.prevSolution || !this.cachedMatrix) {
+      await this.coldStart();
+    }
+    // Refresh-cap forces a clean re-solve to bound drift error
+    if (this.deltaCount >= this.refreshEvery) {
+      return this.coldStart().then((u) => ({ ...u, mode: 'full-resolve' as const }));
+    }
+
+    const matrix = this.cachedMatrix!;
+    const deltaRatio = delta.indices.length / Math.max(1, matrix.entries.length);
+    if (deltaRatio >= this.deltaRatioThreshold) {
+      // Too dense — full re-solve is cheaper than delta-and-correct
+      return this.coldStart().then((u) => ({ ...u, mode: 'full-resolve' as const }));
+    }
+
+    const result = runSolveOnChange(matrix, {
+      graphId: matrix.graphId,
+      prevSolution: this.prevSolution!,
+      delta,
+      algorithm: this.algorithm,
+      maxComplexityClass: this.maxComplexityClass,
+    });
+    this.prevSolution = result.x;
+    this.deltaCount++;
+    return {
+      x: result.x,
+      residualNorm: result.residualNorm,
+      iterations: result.iterations,
+      mode: 'delta',
+      deltaNnz: delta.indices.length,
+      appliedAt: new Date().toISOString(),
+    };
+  }
+
+  /** Best-effort current solution snapshot. */
+  getCurrentSolution(): readonly number[] | undefined {
+    return this.prevSolution;
+  }
+
+  /** Reset cached state (e.g. after the underlying graph re-grew). */
+  reset(): void {
+    this.prevSolution = undefined;
+    this.cachedMatrix = undefined;
+    this.deltaCount = 0;
+  }
+}

package/src/domain/adapter.ts

@@ -0,0 +1,92 @@
+/**
+ * ruflo-graph-intelligence — Adapter Contract (ADR-123 § Architecture)
+ *
+ * Each owning plugin (browser, federation, knowledge-graph, …) implements
+ * this interface and registers itself at plugin-load time. The registry is
+ * plugin-local — the source plugin understands its own storage layout best.
+ */
+
+import type { SparseMatrix } from './types.js';
+
+export interface SublinearAdapter {
+  /** Stable identifier — `"ruflo-federation:trust-mesh"`, etc. */
+  readonly graphId: string;
+
+  /** Owning plugin's package name; informational. */
+  readonly ownerPlugin: string;
+
+  /**
+   * Export the current graph state as a SparseMatrix.
+   *
+   * `since` is an optional snapshot ISO timestamp — adapters may return
+   * a frozen snapshot at that moment (for reproducibility) instead of
+   * the live state. Adapters that don't support history return the live
+   * state regardless.
+   *
+   * `nodeFilter` is an optional allow-list — adapters that can prune
+   * irrelevant rows should honour it to keep the matrix small. Adapters
+   * that can't filter return the full matrix.
+   */
+  exportAsSparseMatrix(options?: {
+    since?: string;
+    nodeFilter?: ReadonlySet<string>;
+  }): Promise<SparseMatrix>;
+
+  /**
+   * Best-effort streaming hook — adapters that can emit deltas (new
+   * causal events, new federation trust updates, new spans) push
+   * `SparseDelta`s through this listener. Adapters that can't return
+   * `noopUnsubscribe`.
+   */
+  onChange?(listener: (delta: import('./types.js').SparseDelta) => void): () => void;
+
+  /**
+   * Whether this graph is **structurally** non-DD (e.g. asymmetric trust with
+   * negative weights). Adapters that know they need clamping/renormalisation
+   * before submission set this flag so the registry can advise callers.
+   */
+  readonly requiresPreprocessing?: boolean;
+}
+
+/** No-op unsubscribe for adapters that don't support streaming. */
+export const noopUnsubscribe = (): void => {};
+
+/** Plugin-load-time registry — populated via `register()`. */
+export class AdapterRegistry {
+  private adapters = new Map<string, SublinearAdapter>();
+
+  register(adapter: SublinearAdapter): void {
+    if (this.adapters.has(adapter.graphId)) {
+      throw new Error(`adapter ${adapter.graphId} already registered`);
+    }
+    this.adapters.set(adapter.graphId, adapter);
+  }
+
+  unregister(graphId: string): boolean {
+    return this.adapters.delete(graphId);
+  }
+
+  get(graphId: string): SublinearAdapter | undefined {
+    return this.adapters.get(graphId);
+  }
+
+  list(): SublinearAdapter[] {
+    return [...this.adapters.values()];
+  }
+
+  clear(): void {
+    this.adapters.clear();
+  }
+}
+
+/** Singleton registry — same lifetime as the plugin process. */
+let globalRegistry: AdapterRegistry | undefined;
+export function getRegistry(): AdapterRegistry {
+  if (!globalRegistry) globalRegistry = new AdapterRegistry();
+  return globalRegistry;
+}
+
+/** Test hook. */
+export function resetRegistry(): void {
+  globalRegistry = undefined;
+}

package/src/domain/federation-protocol.ts

@@ -0,0 +1,95 @@
+/**
+ * Federation Protocol for PR Artifacts (Phase 8 — beyond-SOTA, ADR-123)
+ *
+ * Wire message types over the ADR-104 federation transport. Peers can ask
+ * for a precomputed signed PageRank vector instead of re-walking the graph,
+ * verify via the Phase 7 signer, and fall back to local recompute when the
+ * artifact is stale (graphHash mismatch) or the holder isn't trusted.
+ */
+
+import { z } from 'zod';
+import { SignedPageRankEnvelopeSchema } from './signed-artifact.js';
+
+// ============================================================================
+// Request types
+// ============================================================================
+
+export const PrArtifactRequestSchema = z.object({
+  type: z.literal('pr_artifact_request'),
+  /** Requesting installation id. */
+  fromInstallation: z.string().min(1),
+  /** Adapter graph id to query. */
+  graphId: z.string().min(1),
+  /** Query node for single-entry PR. Omit for full-vector requests. */
+  queryNode: z.string().optional(),
+  alpha: z.number().positive().lt(1).default(0.85),
+  epsilon: z.number().positive().default(1e-3),
+  seedNodes: z.array(z.string()).default([]),
+  /** Hash of the graph the requester has locally. Holder uses this to decide
+   *  whether to ship a fresh artifact or a delta. */
+  lastKnownGraphHash: z.string().regex(/^[0-9a-f]{64}$/).optional(),
+  /** Hash of any previous PR result the requester has cached. */
+  lastKnownResultHash: z.string().regex(/^[0-9a-f]{64}$/).optional(),
+});
+export type PrArtifactRequest = z.infer<typeof PrArtifactRequestSchema>;
+
+// ============================================================================
+// Response types — either a full artifact, a delta, or a stale-rejection
+// ============================================================================
+
+export const PrArtifactResponseSchema = z.object({
+  type: z.literal('pr_artifact_response'),
+  /** Responding installation id. */
+  fromInstallation: z.string().min(1),
+  /** The Phase 7 signed envelope. */
+  envelope: SignedPageRankEnvelopeSchema,
+});
+export type PrArtifactResponse = z.infer<typeof PrArtifactResponseSchema>;
+
+/** Lightweight delta — only the score difference + new resultHash. */
+export const PrArtifactDeltaSchema = z.object({
+  type: z.literal('pr_artifact_delta'),
+  fromInstallation: z.string().min(1),
+  graphId: z.string().min(1),
+  /** Hash the delta is based on. */
+  baseResultHash: z.string().regex(/^[0-9a-f]{64}$/),
+  /** New resultHash after delta applied. */
+  newResultHash: z.string().regex(/^[0-9a-f]{64}$/),
+  /** Score delta (single-entry) or sparse delta indices+values (vector). */
+  scoreDelta: z.number().optional(),
+  sparseDelta: z.object({
+    indices: z.array(z.number().int().nonnegative()),
+    values: z.array(z.number()),
+  }).optional(),
+});
+export type PrArtifactDelta = z.infer<typeof PrArtifactDeltaSchema>;
+
+export const PrArtifactStaleSchema = z.object({
+  type: z.literal('pr_artifact_stale'),
+  fromInstallation: z.string().min(1),
+  graphId: z.string().min(1),
+  /** The holder's current graph hash so the requester can decide what to do. */
+  currentGraphHash: z.string().regex(/^[0-9a-f]{64}$/),
+  /** Why the request was stale-rejected. */
+  reason: z.string(),
+});
+export type PrArtifactStale = z.infer<typeof PrArtifactStaleSchema>;
+
+export const FederationMessageSchema = z.discriminatedUnion('type', [
+  PrArtifactRequestSchema,
+  PrArtifactResponseSchema,
+  PrArtifactDeltaSchema,
+  PrArtifactStaleSchema,
+]);
+export type FederationMessage = z.infer<typeof FederationMessageSchema>;
+
+// ============================================================================
+// Transport contract — ADR-104 plugs in here
+// ============================================================================
+
+export interface FederationTransport {
+  /** Send a message to a specific peer. Returns the response message. */
+  send(toInstallation: string, message: FederationMessage): Promise<FederationMessage | null>;
+  /** Subscribe to inbound messages. */
+  onMessage(handler: (msg: FederationMessage) => Promise<FederationMessage | null>): () => void;
+}