@grafema/types 0.2.5-beta → 0.2.7

package/src/rfdb.ts

@@ -46,6 +46,7 @@ export type RFDBCommand =
   | 'datalogClearRules'
   | 'datalogQuery'
   | 'checkGuarantee'
+  | 'executeDatalog'
   // Protocol v2 - Multi-Database Commands
   | 'hello'
   | 'createDatabase'
@@ -55,7 +56,14 @@ export type RFDBCommand =
   | 'listDatabases'
   | 'currentDatabase'
   // Schema declaration
-  | 'declareFields';
+  | 'declareFields'
+  // Snapshot operations
+  | 'diffSnapshots'
+  | 'tagSnapshot'
+  | 'findSnapshot'
+  | 'listSnapshots'
+  // Batch operations
+  | 'commitBatch';
 
 // === WIRE FORMAT ===
 // Nodes as sent over the wire
@@ -66,6 +74,7 @@ export interface WireNode {
   file: string;
   exported: boolean;
   metadata: string; // JSON string
+  semanticId?: string; // Protocol v3: human-readable semantic ID
 }
 
 // Edges as sent over the wire
@@ -79,6 +88,7 @@ export interface WireEdge {
 // === REQUEST TYPES ===
 export interface RFDBRequest {
   cmd: RFDBCommand;
+  requestId?: string;
   [key: string]: unknown;
 }
 
@@ -170,6 +180,7 @@ export interface CountEdgesByTypeRequest extends RFDBRequest {
 
 // === RESPONSE TYPES ===
 export interface RFDBResponse {
+  requestId?: string;
   error?: string;
   [key: string]: unknown;
 }
@@ -227,6 +238,52 @@ export interface PingResponse extends RFDBResponse {
   version: string;
 }
 
+// === STREAMING RESPONSE TYPES ===
+
+/**
+ * A chunk of nodes in a streaming QueryNodes response.
+ *
+ * Sent by the server when the result set exceeds the streaming threshold
+ * and the client negotiated protocol version >= 3.
+ * Multiple NodesChunk messages share the same requestId. The client
+ * accumulates chunks until `done === true`.
+ *
+ * Discrimination: if a response has a `done` field, it is a streaming chunk.
+ * If it does not, it is a legacy single-shot `Nodes { nodes }` response.
+ */
+export interface NodesChunkResponse extends RFDBResponse {
+  nodes: WireNode[];
+  /** true = last chunk for this requestId; false = more chunks coming */
+  done: boolean;
+  /** 0-based chunk index for ordering verification */
+  chunkIndex: number;
+}
+
+// === BATCH OPERATIONS ===
+
+export interface CommitDelta {
+  changedFiles: string[];
+  nodesAdded: number;
+  nodesRemoved: number;
+  edgesAdded: number;
+  edgesRemoved: number;
+  changedNodeTypes: string[];
+  changedEdgeTypes: string[];
+}
+
+export interface CommitBatchRequest extends RFDBRequest {
+  cmd: 'commitBatch';
+  changedFiles: string[];
+  nodes: WireNode[];
+  edges: WireEdge[];
+  tags?: string[];
+}
+
+export interface CommitBatchResponse extends RFDBResponse {
+  ok: boolean;
+  delta: CommitDelta;
+}
+
 // === PROTOCOL V2 - MULTI-DATABASE RESPONSES ===
 
 export interface HelloResponse extends RFDBResponse {
@@ -274,6 +331,7 @@ export interface AttrQuery {
   name?: string;
   file?: string;
   exported?: boolean;
+  /** @deprecated Node-level version filter is legacy. In v2, use snapshot/tag APIs for history. */
   version?: string;
   /** Extra fields are matched against node metadata JSON (e.g. object, method, async) */
   [key: string]: string | boolean | number | undefined;
@@ -299,10 +357,94 @@ export interface DatalogResult {
   bindings: DatalogBinding;
 }
 
+// === SNAPSHOT TYPES ===
+
+/**
+ * Reference to a snapshot — either by version number or by tag key/value pair.
+ *
+ * When used as a number, refers to the snapshot at that version.
+ * When used as an object, resolves the snapshot tagged with the given key/value.
+ */
+export type SnapshotRef = number | { tag: string; value: string };
+
+/**
+ * Aggregate statistics for a snapshot (mirrors Rust ManifestStats).
+ *
+ * Wire format: camelCase (Rust snake_case fields mapped via serde rename).
+ */
+export interface SnapshotStats {
+  totalNodes: number;
+  totalEdges: number;
+  nodeSegmentCount: number;
+  edgeSegmentCount: number;
+}
+
+/**
+ * Segment descriptor — describes a single data segment in a snapshot.
+ *
+ * Simplified view of Rust SegmentDescriptor. Exposes fields relevant to
+ * client-side diff analysis. Internal fields (segmentType, shardId) omitted.
+ *
+ * Wire format: camelCase. HashSet<String> serializes as string[].
+ */
+export interface SegmentInfo {
+  segmentId: number;
+  recordCount: number;
+  byteSize: number;
+  nodeTypes: string[];
+  filePaths: string[];
+  edgeTypes: string[];
+}
+
+/**
+ * Diff between two snapshots (from -> to).
+ *
+ * Shows which segments were added/removed and stats for both versions.
+ * Mirrors Rust SnapshotDiff (storage_v2/manifest.rs).
+ */
+export interface SnapshotDiff {
+  fromVersion: number;
+  toVersion: number;
+  addedNodeSegments: SegmentInfo[];
+  removedNodeSegments: SegmentInfo[];
+  addedEdgeSegments: SegmentInfo[];
+  removedEdgeSegments: SegmentInfo[];
+  statsFrom: SnapshotStats;
+  statsTo: SnapshotStats;
+}
+
+/**
+ * Lightweight snapshot information for list operations.
+ *
+ * Mirrors Rust SnapshotInfo (storage_v2/manifest.rs).
+ * createdAt is Unix epoch seconds (u64 in Rust).
+ */
+export interface SnapshotInfo {
+  version: number;
+  createdAt: number;
+  tags: Record<string, string>;
+  stats: SnapshotStats;
+}
+
+// Snapshot response types
+
+export interface DiffSnapshotsResponse extends RFDBResponse {
+  diff: SnapshotDiff;
+}
+
+export interface FindSnapshotResponse extends RFDBResponse {
+  version: number | null;
+}
+
+export interface ListSnapshotsResponse extends RFDBResponse {
+  snapshots: SnapshotInfo[];
+}
+
 // === CLIENT INTERFACE ===
 export interface IRFDBClient {
   readonly socketPath: string;
   readonly connected: boolean;
+  readonly supportsStreaming: boolean;
 
   // Connection
   connect(): Promise<void>;
@@ -325,6 +467,7 @@ export interface IRFDBClient {
   findByType(nodeType: NodeType): Promise<string[]>;
   findByAttr(query: Record<string, unknown>): Promise<string[]>;
   queryNodes(query: AttrQuery): AsyncGenerator<WireNode, void, unknown>;
+  queryNodesStream(query: AttrQuery): AsyncGenerator<WireNode, void, unknown>;
   getAllNodes(query?: AttrQuery): Promise<WireNode[]>;
   getAllEdges(): Promise<WireEdge[]>;
   isEndpoint(id: string): Promise<boolean>;
@@ -353,6 +496,14 @@ export interface IRFDBClient {
   datalogClearRules(): Promise<RFDBResponse>;
   datalogQuery(query: string): Promise<DatalogResult[]>;
   checkGuarantee(ruleSource: string): Promise<DatalogResult[]>;
+  executeDatalog(source: string): Promise<DatalogResult[]>;
+
+  // Batch operations
+  beginBatch(): void;
+  commitBatch(tags?: string[]): Promise<CommitDelta>;
+  abortBatch(): void;
+  isBatching(): boolean;
+  findDependentFiles(changedFiles: string[]): Promise<string[]>;
 
   // Protocol v2 - Multi-Database
   hello(protocolVersion?: number): Promise<HelloResponse>;
@@ -362,4 +513,10 @@ export interface IRFDBClient {
   dropDatabase(name: string): Promise<RFDBResponse>;
   listDatabases(): Promise<ListDatabasesResponse>;
   currentDatabase(): Promise<CurrentDatabaseResponse>;
+
+  // Snapshot operations
+  diffSnapshots(from: SnapshotRef, to: SnapshotRef): Promise<SnapshotDiff>;
+  tagSnapshot(version: number, tags: Record<string, string>): Promise<void>;
+  findSnapshot(tagKey: string, tagValue: string): Promise<number | null>;
+  listSnapshots(filterTag?: string): Promise<SnapshotInfo[]>;
 }

package/src/routing.ts

@@ -0,0 +1,96 @@
+/**
+ * Routing Types — cross-service URL mapping for infrastructure-level routing.
+ *
+ * The RoutingMap is source-agnostic. It doesn't know where rules came from
+ * (config.yaml, nginx.conf, k8s manifests). It only knows:
+ * "request from service A with path P routes to service B with path P'"
+ */
+
+import type { Resource } from './resources.js';
+
+/**
+ * A routing rule describes how requests are transformed between services.
+ * Source-agnostic — can come from config.yaml, nginx.conf, k8s, etc.
+ */
+export interface RoutingRule {
+  /** Service where requests originate (matches ServiceDefinition.name) */
+  from: string;
+  /** Service where routes are defined (matches ServiceDefinition.name) */
+  to: string;
+  /** Path prefix to strip from request URL before matching.
+   *  e.g., stripPrefix: '/api' transforms '/api/users' -> '/users' */
+  stripPrefix?: string;
+  /** Path prefix to add to request URL before matching.
+   *  e.g., addPrefix: '/v2' transforms '/users' -> '/v2/users' */
+  addPrefix?: string;
+  /** Source of this rule (for debugging/traceability) */
+  source?: string;
+  /** Priority — lower numbers match first. Default: 0 */
+  priority?: number;
+}
+
+/**
+ * Context for matching a request against the routing map.
+ */
+export interface MatchContext {
+  /** Service name where the request originates */
+  fromService: string;
+  /** Original request URL (before any transformation) */
+  requestUrl: string;
+  /** HTTP method (optional, for future method-based routing) */
+  method?: string;
+}
+
+/**
+ * Result of a routing match — the transformed URL to use for matching.
+ */
+export interface MatchResult {
+  /** Transformed URL to match against route paths */
+  transformedUrl: string;
+  /** Service name where the route should be found */
+  targetService: string;
+  /** The rule that matched */
+  rule: RoutingRule;
+}
+
+/**
+ * RoutingMap Resource — abstract routing table built by multiple builder plugins.
+ *
+ * Resource ID: 'routing:map'
+ */
+export interface RoutingMap extends Resource {
+  readonly id: 'routing:map';
+
+  /**
+   * Add a routing rule. Called by builder plugins during ENRICHMENT phase.
+   * Duplicate rules (same from/to/strip/add) are silently deduplicated.
+   */
+  addRule(rule: RoutingRule): void;
+
+  /** Add multiple rules at once. */
+  addRules(rules: RoutingRule[]): void;
+
+  /**
+   * Find matching route transformation for a request context.
+   *
+   * If multiple rules match, returns the most specific one:
+   * 1. Rules with longer stripPrefix match first (more specific)
+   * 2. Among equal-length prefixes, lower priority number wins
+   * 3. If still tied, first-added wins
+   *
+   * @returns MatchResult if a rule matches, null if no rule applies
+   */
+  findMatch(context: MatchContext): MatchResult | null;
+
+  /** Find ALL matching rules for a from/to service pair. */
+  findRulesForPair(fromService: string, toService: string): RoutingRule[];
+
+  /** Get all rules (for debugging/logging). */
+  getAllRules(): RoutingRule[];
+
+  /** Get count of rules (for metrics). */
+  get ruleCount(): number;
+}
+
+/** Well-known Resource ID for the RoutingMap */
+export const ROUTING_MAP_RESOURCE_ID = 'routing:map' as const;