@grafema/core 0.1.0-alpha.1

package/src/api/GraphAPI.ts

@@ -0,0 +1,305 @@
+/**
+ * Clean Graph API for visualization
+ * Reads everything directly from RFDB (no caches)
+ */
+
+import { createServer, Server, IncomingMessage, ServerResponse } from 'http';
+import { parse as parseUrl } from 'url';
+
+// Node type constants
+const NODE_TYPES = {
+  SERVICE: 2,
+  FUNCTION: 3,
+  CLASS: 4,
+  MODULE: 8,
+} as const;
+
+// Edge type constants
+const EDGE_TYPES = {
+  CONTAINS: 1,
+  DEPENDS_ON: 2,
+  CALLS: 3,
+  IMPORTS: 8,
+} as const;
+
+/**
+ * Native node from engine
+ */
+interface NativeNode {
+  id: bigint;
+  kind: number;
+  exported: boolean;
+  version: number;
+  name_offset?: number;
+}
+
+/**
+ * Native edge from engine
+ */
+interface NativeEdge {
+  src: bigint;
+  dst: bigint;
+  etype: number;
+  version: number;
+}
+
+/**
+ * Engine interface
+ */
+interface GraphEngine {
+  findByType(type: number): bigint[];
+  getNode(id: bigint): NativeNode | null;
+  nodeExists(id: bigint): boolean;
+  getOutgoingEdges(id: bigint, types: number[] | null): NativeEdge[];
+}
+
+/**
+ * Backend interface
+ */
+interface GraphBackend {
+  engine: GraphEngine;
+  _bigIntToId(id: bigint): string;
+  _idToBigInt(id: string): bigint;
+  _numberToNodeType(kind: number): string;
+  _numberToEdgeType(etype: number): string;
+}
+
+/**
+ * Formatted node for API response
+ */
+interface FormattedNode {
+  id: string;
+  type: string;
+  name: string;
+  exported: boolean;
+  version: number;
+}
+
+/**
+ * Formatted edge for API response
+ */
+interface FormattedEdge {
+  src: string;
+  dst: string;
+  type: string;
+  version: number;
+}
+
+export class GraphAPI {
+  private backend: GraphBackend;
+  private port: number;
+  private server: Server | null;
+
+  constructor(backend: GraphBackend, port: number = 3000) {
+    this.backend = backend;
+    this.port = port;
+    this.server = null;
+  }
+
+  /**
+   * Start API server
+   */
+  start(): this {
+    this.server = createServer((req, res) => {
+      this.handleRequest(req, res);
+    });
+
+    this.server.listen(this.port, () => {
+      console.log(`\n🚀 Graph API Server started`);
+      console.log(`📊 http://localhost:${this.port}`);
+      console.log(`\nEndpoints:`);
+      console.log(`  GET /api/services - List all services`);
+      console.log(`  GET /api/node/:id - Get node by ID`);
+      console.log(`  GET /api/node/:id/children - Get node children (via CONTAINS edges)`);
+      console.log(`  GET /api/node/:id/edges - Get all edges from node`);
+      console.log(`\nPress Ctrl+C to stop\n`);
+    });
+
+    return this;
+  }
+
+  /**
+   * Stop server
+   */
+  stop(): void {
+    if (this.server) {
+      this.server.close();
+      console.log('Graph API Server stopped');
+    }
+  }
+
+  /**
+   * Handle HTTP request
+   */
+  async handleRequest(req: IncomingMessage, res: ServerResponse): Promise<void> {
+    const { pathname } = parseUrl(req.url || '', true);
+
+    // CORS headers
+    res.setHeader('Access-Control-Allow-Origin', '*');
+    res.setHeader('Content-Type', 'application/json');
+
+    try {
+      // GET /api/services
+      if (pathname === '/api/services') {
+        await this.handleGetServices(req, res);
+        return;
+      }
+
+      // GET /api/node/:id
+      const nodeMatch = pathname?.match(/^\/api\/node\/([^\/]+)$/);
+      if (nodeMatch) {
+        await this.handleGetNode(req, res, decodeURIComponent(nodeMatch[1]));
+        return;
+      }
+
+      // GET /api/node/:id/children
+      const childrenMatch = pathname?.match(/^\/api\/node\/([^\/]+)\/children$/);
+      if (childrenMatch) {
+        await this.handleGetChildren(req, res, decodeURIComponent(childrenMatch[1]));
+        return;
+      }
+
+      // GET /api/node/:id/edges
+      const edgesMatch = pathname?.match(/^\/api\/node\/([^\/]+)\/edges$/);
+      if (edgesMatch) {
+        await this.handleGetEdges(req, res, decodeURIComponent(edgesMatch[1]));
+        return;
+      }
+
+      // 404
+      res.writeHead(404);
+      res.end(JSON.stringify({ error: 'Endpoint not found' }));
+    } catch (error) {
+      console.error('API error:', error);
+      res.writeHead(500);
+      res.end(JSON.stringify({ error: (error as Error).message }));
+    }
+  }
+
+  /**
+   * GET /api/services
+   * Returns all SERVICE nodes
+   */
+  async handleGetServices(req: IncomingMessage, res: ServerResponse): Promise<void> {
+    // Find all SERVICE nodes from RFDB
+    const serviceIds = this.backend.engine.findByType(NODE_TYPES.SERVICE);
+
+    const services = serviceIds.map(id => {
+      const node = this.backend.engine.getNode(id);
+      if (!node) return null;
+
+      return {
+        id: this.backend._bigIntToId(node.id),
+        type: 'SERVICE',
+        name: this.getNodeName(node),
+        exported: node.exported,
+        version: node.version,
+      };
+    }).filter(Boolean) as FormattedNode[];
+
+    res.writeHead(200);
+    res.end(JSON.stringify(services));
+  }
+
+  /**
+   * GET /api/node/:id
+   * Returns single node by ID
+   */
+  async handleGetNode(req: IncomingMessage, res: ServerResponse, nodeId: string): Promise<void> {
+    const node = this.backend.engine.getNode(this.backend._idToBigInt(nodeId));
+
+    if (!node) {
+      res.writeHead(404);
+      res.end(JSON.stringify({ error: 'Node not found' }));
+      return;
+    }
+
+    res.writeHead(200);
+    res.end(JSON.stringify({
+      id: this.backend._bigIntToId(node.id),
+      type: this.backend._numberToNodeType(node.kind),
+      name: this.getNodeName(node),
+      exported: node.exported,
+      version: node.version,
+    }));
+  }
+
+  /**
+   * GET /api/node/:id/children
+   * Returns children via CONTAINS edges
+   */
+  async handleGetChildren(req: IncomingMessage, res: ServerResponse, nodeId: string): Promise<void> {
+    const nodeIdBigInt = this.backend._idToBigInt(nodeId);
+
+    // Check node exists
+    if (!this.backend.engine.nodeExists(nodeIdBigInt)) {
+      res.writeHead(404);
+      res.end(JSON.stringify({ error: 'Node not found' }));
+      return;
+    }
+
+    // Get outgoing CONTAINS edges
+    const edges = this.backend.engine.getOutgoingEdges(nodeIdBigInt, [EDGE_TYPES.CONTAINS]);
+
+    const children = edges.map(edge => {
+      const childNode = this.backend.engine.getNode(edge.dst);
+      if (!childNode) return null;
+
+      return {
+        id: this.backend._bigIntToId(childNode.id),
+        type: this.backend._numberToNodeType(childNode.kind),
+        name: this.getNodeName(childNode),
+        exported: childNode.exported,
+        version: childNode.version,
+      };
+    }).filter(Boolean) as FormattedNode[];
+
+    res.writeHead(200);
+    res.end(JSON.stringify({
+      nodeId,
+      childCount: children.length,
+      children
+    }));
+  }
+
+  /**
+   * GET /api/node/:id/edges
+   * Returns all outgoing edges from node
+   */
+  async handleGetEdges(req: IncomingMessage, res: ServerResponse, nodeId: string): Promise<void> {
+    const nodeIdBigInt = this.backend._idToBigInt(nodeId);
+
+    // Check node exists
+    if (!this.backend.engine.nodeExists(nodeIdBigInt)) {
+      res.writeHead(404);
+      res.end(JSON.stringify({ error: 'Node not found' }));
+      return;
+    }
+
+    // Get all outgoing edges
+    const edges = this.backend.engine.getOutgoingEdges(nodeIdBigInt, null);
+
+    const formattedEdges: FormattedEdge[] = edges.map(edge => ({
+      src: this.backend._bigIntToId(edge.src),
+      dst: this.backend._bigIntToId(edge.dst),
+      type: this.backend._numberToEdgeType(edge.etype),
+      version: edge.version,
+    }));
+
+    res.writeHead(200);
+    res.end(JSON.stringify({
+      nodeId,
+      edgeCount: formattedEdges.length,
+      edges: formattedEdges
+    }));
+  }
+
+  /**
+   * Get node name from name_offset (TODO: implement string table lookup)
+   */
+  private getNodeName(node: NativeNode): string {
+    // TODO: Lookup in string table
+    // For now return placeholder
+    return `Node_${node.id.toString().substring(0, 8)}`;
+  }
+}

package/src/api/GuaranteeAPI.ts

@@ -0,0 +1,401 @@
+/**
+ * GuaranteeAPI - CRUD API for contract-based guarantees
+ *
+ * Contract-based guarantees use JSON schema validation instead of Datalog rules.
+ * They have namespaced types: guarantee:queue, guarantee:api, guarantee:permission
+ *
+ * This API complements GuaranteeManager which handles Datalog-based GUARANTEE nodes.
+ */
+
+import type { ValidateFunction, ErrorObject } from 'ajv';
+import { GuaranteeNode, type GuaranteeNodeRecord, type GuaranteePriority, type GuaranteeStatus, type GuaranteeType } from '../core/nodes/GuaranteeNode.js';
+
+// Schema validator interface
+interface SchemaValidator {
+  compile(schema: Record<string, unknown>): ValidateFunction;
+}
+
+// Lazy-loaded Ajv instance to avoid import issues
+let ajvInstance: SchemaValidator | null = null;
+
+async function getAjv(): Promise<SchemaValidator> {
+  if (!ajvInstance) {
+    const AjvModule = await import('ajv');
+    // Handle both ESM default export and CJS module.exports
+    const AjvClass = AjvModule.default || AjvModule;
+    // Use Function constructor pattern to avoid TS2351
+    const createAjv = AjvClass as unknown as new (opts: { allErrors: boolean }) => SchemaValidator;
+    ajvInstance = new createAjv({ allErrors: true });
+  }
+  return ajvInstance;
+}
+
+/**
+ * Graph interface for GuaranteeAPI
+ */
+export interface GuaranteeGraphBackend {
+  addNode(node: Record<string, unknown>): Promise<void>;
+  getNode(id: string): Promise<Record<string, unknown> | null>;
+  deleteNode(id: string): Promise<void>;
+  queryNodes(filter: { type: string }): AsyncIterable<Record<string, unknown>>;
+  addEdge(edge: { type: string; src: string; dst: string }): Promise<void>;
+  deleteEdge(src: string, dst: string, type: string): Promise<void>;
+  getOutgoingEdges(nodeId: string, types: string[]): Promise<Array<{ src: string; dst: string; type: string }>>;
+  getIncomingEdges(nodeId: string, types: string[]): Promise<Array<{ src: string; dst: string; type: string }>>;
+}
+
+/**
+ * Input for creating a guarantee
+ */
+export interface CreateGuaranteeInput {
+  type: 'guarantee:queue' | 'guarantee:api' | 'guarantee:permission';
+  name: string;
+  priority?: GuaranteePriority;
+  status?: GuaranteeStatus;
+  owner?: string;
+  schema?: Record<string, unknown>;
+  condition?: string;
+  description?: string;
+  governs?: string[]; // Node IDs that this guarantee governs
+}
+
+/**
+ * Input for updating a guarantee
+ */
+export interface UpdateGuaranteeInput {
+  priority?: GuaranteePriority;
+  status?: GuaranteeStatus;
+  owner?: string;
+  schema?: Record<string, unknown>;
+  condition?: string;
+  description?: string;
+}
+
+/**
+ * Filter for finding guarantees
+ */
+export interface GuaranteeFilter {
+  type?: GuaranteeType | GuaranteeType[];
+  priority?: GuaranteePriority | GuaranteePriority[];
+  status?: GuaranteeStatus | GuaranteeStatus[];
+  owner?: string;
+}
+
+/**
+ * Result of checking a guarantee
+ */
+export interface CheckGuaranteeResult {
+  id: string;
+  name: string;
+  passed: boolean;
+  errors: string[];
+  validatedCount: number;
+}
+
+/**
+ * GuaranteeAPI - CRUD operations for contract-based guarantees
+ */
+export class GuaranteeAPI {
+  private graph: GuaranteeGraphBackend;
+  private schemaCache: Map<string, ValidateFunction>;
+
+  constructor(graph: GuaranteeGraphBackend) {
+    this.graph = graph;
+    this.schemaCache = new Map();
+  }
+
+  /**
+   * Create a new contract-based guarantee
+   */
+  async createGuarantee(input: CreateGuaranteeInput): Promise<GuaranteeNodeRecord> {
+    // Parse type to get namespace
+    const parsed = GuaranteeNode.parseId(`${input.type}#${input.name}`);
+    if (!parsed) {
+      throw new Error(`Invalid guarantee type: ${input.type}`);
+    }
+
+    // Create the guarantee node
+    const node = GuaranteeNode.create(parsed.namespace, input.name, {
+      priority: input.priority,
+      status: input.status,
+      owner: input.owner,
+      schema: input.schema,
+      condition: input.condition,
+      description: input.description,
+    });
+
+    // Validate before saving
+    const errors = GuaranteeNode.validate(node);
+    if (errors.length > 0) {
+      throw new Error(`Invalid guarantee: ${errors.join(', ')}`);
+    }
+
+    // Save to graph
+    await this.graph.addNode(node as unknown as Record<string, unknown>);
+
+    // Create GOVERNS edges if specified
+    if (input.governs && input.governs.length > 0) {
+      for (const targetId of input.governs) {
+        await this.addGoverns(node.id, targetId);
+      }
+    }
+
+    return node;
+  }
+
+  /**
+   * Get a guarantee by ID
+   */
+  async getGuarantee(id: string): Promise<GuaranteeNodeRecord | null> {
+    const node = await this.graph.getNode(id);
+    if (!node) return null;
+
+    // Verify it's a guarantee type
+    if (!GuaranteeNode.isGuaranteeType(node.type as string)) {
+      return null;
+    }
+
+    return node as unknown as GuaranteeNodeRecord;
+  }
+
+  /**
+   * Find guarantees matching filter
+   */
+  async findGuarantees(filter: GuaranteeFilter = {}): Promise<GuaranteeNodeRecord[]> {
+    const guarantees: GuaranteeNodeRecord[] = [];
+    const types = this.normalizeTypeFilter(filter.type);
+
+    for (const type of types) {
+      for await (const node of this.graph.queryNodes({ type })) {
+        const g = node as unknown as GuaranteeNodeRecord;
+
+        // Apply additional filters
+        if (filter.priority) {
+          const priorities = Array.isArray(filter.priority) ? filter.priority : [filter.priority];
+          if (!priorities.includes(g.priority)) continue;
+        }
+
+        if (filter.status) {
+          const statuses = Array.isArray(filter.status) ? filter.status : [filter.status];
+          if (!statuses.includes(g.status)) continue;
+        }
+
+        if (filter.owner && g.owner !== filter.owner) continue;
+
+        guarantees.push(g);
+      }
+    }
+
+    return guarantees;
+  }
+
+  /**
+   * Update a guarantee
+   */
+  async updateGuarantee(id: string, updates: UpdateGuaranteeInput): Promise<GuaranteeNodeRecord> {
+    const existing = await this.getGuarantee(id);
+    if (!existing) {
+      throw new Error(`Guarantee not found: ${id}`);
+    }
+
+    // Apply updates
+    const updated: GuaranteeNodeRecord = {
+      ...existing,
+      ...updates,
+      updatedAt: Date.now(),
+    };
+
+    // Validate
+    const errors = GuaranteeNode.validate(updated);
+    if (errors.length > 0) {
+      throw new Error(`Invalid guarantee after update: ${errors.join(', ')}`);
+    }
+
+    // Delete old and add new (upsert)
+    await this.graph.deleteNode(id);
+    await this.graph.addNode(updated as unknown as Record<string, unknown>);
+
+    return updated;
+  }
+
+  /**
+   * Delete a guarantee
+   */
+  async deleteGuarantee(id: string): Promise<boolean> {
+    const existing = await this.getGuarantee(id);
+    if (!existing) {
+      return false;
+    }
+
+    // Delete GOVERNS edges
+    const edges = await this.graph.getOutgoingEdges(id, ['GOVERNS']);
+    for (const edge of edges) {
+      await this.graph.deleteEdge(edge.src, edge.dst, 'GOVERNS');
+    }
+
+    // Delete the node
+    await this.graph.deleteNode(id);
+    return true;
+  }
+
+  /**
+   * Add GOVERNS edge from guarantee to a node
+   */
+  async addGoverns(guaranteeId: string, nodeId: string): Promise<void> {
+    // Verify guarantee exists
+    const guarantee = await this.getGuarantee(guaranteeId);
+    if (!guarantee) {
+      throw new Error(`Guarantee not found: ${guaranteeId}`);
+    }
+
+    // Verify target node exists
+    const targetNode = await this.graph.getNode(nodeId);
+    if (!targetNode) {
+      throw new Error(`Target node not found: ${nodeId}`);
+    }
+
+    // Create GOVERNS edge
+    await this.graph.addEdge({
+      type: 'GOVERNS',
+      src: guaranteeId,
+      dst: nodeId,
+    });
+  }
+
+  /**
+   * Remove GOVERNS edge
+   */
+  async removeGoverns(guaranteeId: string, nodeId: string): Promise<void> {
+    await this.graph.deleteEdge(guaranteeId, nodeId, 'GOVERNS');
+  }
+
+  /**
+   * Get nodes governed by a guarantee
+   */
+  async getGoverned(guaranteeId: string): Promise<string[]> {
+    const edges = await this.graph.getOutgoingEdges(guaranteeId, ['GOVERNS']);
+    return edges.map(e => e.dst);
+  }
+
+  /**
+   * Get guarantees governing a node
+   */
+  async getGoverningGuarantees(nodeId: string): Promise<GuaranteeNodeRecord[]> {
+    const edges = await this.graph.getIncomingEdges(nodeId, ['GOVERNS']);
+    const guarantees: GuaranteeNodeRecord[] = [];
+
+    for (const edge of edges) {
+      const g = await this.getGuarantee(edge.src);
+      if (g) guarantees.push(g);
+    }
+
+    return guarantees;
+  }
+
+  /**
+   * Check a guarantee using JSON schema validation
+   * Returns validation results for governed nodes
+   */
+  async checkGuarantee(id: string): Promise<CheckGuaranteeResult> {
+    const guarantee = await this.getGuarantee(id);
+    if (!guarantee) {
+      throw new Error(`Guarantee not found: ${id}`);
+    }
+
+    const result: CheckGuaranteeResult = {
+      id,
+      name: guarantee.name,
+      passed: true,
+      errors: [],
+      validatedCount: 0,
+    };
+
+    // If no schema defined, consider it passing
+    if (!guarantee.schema) {
+      return result;
+    }
+
+    // Get or compile schema validator
+    let validate: ValidateFunction | undefined = this.schemaCache.get(id);
+    if (!validate) {
+      try {
+        const ajv = await getAjv();
+        validate = ajv.compile(guarantee.schema);
+        this.schemaCache.set(id, validate);
+      } catch (e) {
+        result.passed = false;
+        result.errors.push(`Invalid schema: ${(e as Error).message}`);
+        return result;
+      }
+    }
+
+    // Get governed nodes and validate them
+    const governedIds = await this.getGoverned(id);
+    // At this point validate is guaranteed to be defined (we returned if compile failed)
+    const validator: ValidateFunction = validate;
+    for (const nodeId of governedIds) {
+      const node = await this.graph.getNode(nodeId);
+      if (!node) continue;
+
+      result.validatedCount++;
+      const valid = validator(node);
+      if (!valid) {
+        result.passed = false;
+        const errors = validator.errors as ErrorObject[] | null | undefined;
+        if (errors) {
+          for (const err of errors) {
+            result.errors.push(`${nodeId}: ${err.instancePath} ${err.message}`);
+          }
+        }
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Check all guarantees
+   */
+  async checkAllGuarantees(): Promise<{
+    total: number;
+    passed: number;
+    failed: number;
+    results: CheckGuaranteeResult[];
+  }> {
+    const guarantees = await this.findGuarantees();
+    const results: CheckGuaranteeResult[] = [];
+    let passed = 0;
+    let failed = 0;
+
+    for (const g of guarantees) {
+      const result = await this.checkGuarantee(g.id);
+      results.push(result);
+      if (result.passed) passed++;
+      else failed++;
+    }
+
+    return {
+      total: guarantees.length,
+      passed,
+      failed,
+      results,
+    };
+  }
+
+  /**
+   * Normalize type filter to array of types
+   */
+  private normalizeTypeFilter(type?: GuaranteeType | GuaranteeType[]): GuaranteeType[] {
+    if (!type) {
+      return GuaranteeNode.getTypes();
+    }
+    return Array.isArray(type) ? type : [type];
+  }
+
+  /**
+   * Clear schema cache (useful after schema updates)
+   */
+  clearSchemaCache(): void {
+    this.schemaCache.clear();
+  }
+}