Interface SublinearAdapter

plugins/ruflo-graph-intelligence/src/domain/adapter.ts:11–49

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 => {};