mycelia-kernel-plugin 1.3.0 → 1.4.1

package/src/angular/index.js

@@ -0,0 +1,189 @@
+/**
+ * Mycelia Plugin System - Angular Bindings
+ * 
+ * Angular utilities that make the Mycelia Plugin System feel natural
+ * inside Angular applications using dependency injection and RxJS.
+ * 
+ * @example
+ * ```ts
+ * import { MyceliaModule, useFacet, useListener } from 'mycelia-kernel-plugin/angular';
+ * import { NgModule } from '@angular/core';
+ * 
+ * const buildSystem = () => useBase('app')
+ *   .use(useDatabase)
+ *   .build();
+ * 
+ * @NgModule({
+ *   imports: [MyceliaModule.forRoot({ build: buildSystem })]
+ * })
+ * export class AppModule {}
+ * 
+ * // In component
+ * @Component({...})
+ * export class MyComponent {
+ *   constructor(private mycelia: MyceliaService) {
+ *     const db = this.mycelia.useFacet('database');
+ *     this.mycelia.useListener('user:created', (msg) => console.log(msg));
+ *   }
+ * }
+ * ```
+ */
+
+// Note: This is a TypeScript-friendly JavaScript module
+// Angular applications typically use TypeScript, but we provide JS bindings
+// for compatibility. Type definitions should be provided separately.
+
+/**
+ * MyceliaService - Injectable service that provides Mycelia system
+ * 
+ * This service should be provided at the root level using MyceliaModule.
+ * 
+ * @example
+ * ```ts
+ * @Injectable({ providedIn: 'root' })
+ * export class MyceliaService {
+ *   private system$ = new BehaviorSubject(null);
+ *   
+ *   constructor(@Inject(MYCELIA_BUILD_TOKEN) private buildFn: () => Promise<any>) {
+ *     this.initialize();
+ *   }
+ *   
+ *   async initialize() {
+ *     const system = await this.buildFn();
+ *     this.system$.next(system);
+ *   }
+ * }
+ * ```
+ */
+
+// For JavaScript/CommonJS compatibility, we export factory functions
+// that can be used with Angular's dependency injection system
+
+/**
+ * createMyceliaService - Factory function to create Mycelia service
+ * 
+ * @param {Function} build - Async function that returns a built system
+ * @returns {Object} Service object with system observable and helper methods
+ * 
+ * @example
+ * ```ts
+ * const myceliaService = createMyceliaService(buildSystem);
+ * ```
+ */
+export function createMyceliaService(build) {
+  let system = null;
+  let systemSubject = null;
+  let errorSubject = null;
+  let loadingSubject = null;
+
+  // Initialize system
+  (async () => {
+    try {
+      loadingSubject?.next?.(true);
+      system = await build();
+      systemSubject?.next?.(system);
+      errorSubject?.next?.(null);
+    } catch (err) {
+      errorSubject?.next?.(err);
+      systemSubject?.next?.(null);
+    } finally {
+      loadingSubject?.next?.(false);
+    }
+  })();
+
+  return {
+    /**
+     * Get system observable (requires RxJS BehaviorSubject)
+     * @returns {Object} Observable-like object
+     */
+    get system$() {
+      if (!systemSubject) {
+        // Lazy initialization - requires RxJS
+        const { BehaviorSubject } = require('rxjs');
+        systemSubject = new BehaviorSubject(system);
+      }
+      return systemSubject.asObservable();
+    },
+
+    /**
+     * Get error observable
+     * @returns {Object} Observable-like object
+     */
+    get error$() {
+      if (!errorSubject) {
+        const { BehaviorSubject } = require('rxjs');
+        errorSubject = new BehaviorSubject(null);
+      }
+      return errorSubject.asObservable();
+    },
+
+    /**
+     * Get loading observable
+     * @returns {Object} Observable-like object
+     */
+    get loading$() {
+      if (!loadingSubject) {
+        const { BehaviorSubject } = require('rxjs');
+        loadingSubject = new BehaviorSubject(true);
+      }
+      return loadingSubject.asObservable();
+    },
+
+    /**
+     * Get current system synchronously
+     * @returns {Object|null} Current system instance
+     */
+    getSystem() {
+      return system;
+    },
+
+    /**
+     * Get a facet by kind
+     * @param {string} kind - Facet kind identifier
+     * @returns {Object|null} Facet instance or null
+     */
+    useFacet(kind) {
+      return system?.find?.(kind) ?? null;
+    },
+
+    /**
+     * Register an event listener
+     * @param {string} eventName - Event name/path
+     * @param {Function} handler - Handler function
+     * @returns {Function} Unsubscribe function
+     */
+    useListener(eventName, handler) {
+      const listeners = system?.listeners;
+      if (!listeners || !listeners.hasListeners?.()) {
+        return () => {};
+      }
+
+      listeners.on(eventName, handler);
+      return () => {
+        listeners.off?.(eventName, handler);
+      };
+    },
+
+    /**
+     * Dispose the system
+     * @returns {Promise<void>}
+     */
+    async dispose() {
+      if (system && typeof system.dispose === 'function') {
+        await system.dispose().catch(() => {
+          // Ignore disposal errors
+        });
+      }
+      system = null;
+      systemSubject?.complete?.();
+      errorSubject?.complete?.();
+      loadingSubject?.complete?.();
+    }
+  };
+}
+
+// Re-export helper functions
+export { useFacet, useListener, useEventStream } from './helpers.js';
+export { createAngularSystemBuilder } from './builders.js';
+export { createFacetService } from './services.js';
+

package/src/angular/services.js

@@ -0,0 +1,32 @@
+/**
+ * Angular Service Generators
+ */
+
+/**
+ * createFacetService - Generate a service for a specific facet kind
+ * 
+ * @param {string} kind - Facet kind identifier
+ * @returns {Function} Service factory: (myceliaService) => Observable<Facet>
+ * 
+ * @example
+ * ```ts
+ * // In services/todo.service.ts
+ * export const TodoService = createFacetService('todoStore');
+ * 
+ * // In component
+ * @Component({...})
+ * export class TodoListComponent {
+ *   todos$ = TodoService(this.mycelia);
+ * }
+ * ```
+ */
+export function createFacetService(kind) {
+  return function(myceliaService) {
+    const { map } = require('rxjs/operators');
+    return myceliaService.system$.pipe(
+      map(system => system?.find?.(kind) ?? null)
+    );
+  };
+}
+
+

package/src/builder/dependency-graph.js

@@ -17,6 +17,16 @@ export function createCacheKey(kinds) {
 /**
  * Build a dependency graph from hook metadata and facet dependencies.
  * 
+ * Creates a directed graph where:
+ * - Vertices = facet kinds
+ * - Edges = dependencies (if A depends on B, edge goes from B -> A)
+ * 
+ * The graph is represented as:
+ * - graph: Map<depKind, Set<dependentKinds>> - adjacency list
+ * - indeg: Map<kind, number> - in-degree count (how many dependencies)
+ * 
+ * This graph is used by topological sort to determine initialization order.
+ * 
  * @param {Object} hooksByKind - Object mapping hook kinds to hook metadata
  * @param {Object} facetsByKind - Object mapping facet kinds to Facet instances
  * @param {BaseSubsystem} subsystem - Subsystem instance (optional, for future use)
@@ -24,16 +34,21 @@ export function createCacheKey(kinds) {
  */
 export function buildDepGraph(hooksByKind, facetsByKind, subsystem = null) {
   const kinds = Object.keys(facetsByKind);
+  
+  // Initialize graph data structures:
+  // - graph: adjacency list (dep -> Set of dependents)
+  // - indeg: in-degree counter (how many incoming edges)
   const graph = new Map(); // dep -> Set(of dependents)
   const indeg = new Map(); // kind -> indegree
 
+  // Initialize all vertices with empty adjacency lists and zero indegree
   for (const k of kinds) {
     graph.set(k, new Set());
     indeg.set(k, 0);
   }
 
-  // First, add dependencies from hook metadata (hook.required)
-  // hooksByKind now contains arrays of hooks per kind
+  // Phase 1: Add dependencies from hook metadata (hook.required)
+  // hooksByKind now contains arrays of hooks per kind (multiple hooks can create same facet)
   for (const [kind, hookList] of Object.entries(hooksByKind)) {
     if (!Array.isArray(hookList)) continue;
     
@@ -43,7 +58,9 @@ export function buildDepGraph(hooksByKind, facetsByKind, subsystem = null) {
     const hookDeps = (lastHook?.required && Array.isArray(lastHook.required)) ? lastHook.required : [];
     const hookOverwrite = lastHook?.overwrite === true;
     
+    // Process each dependency declared by the hook
     for (const dep of hookDeps) {
+      // Special case: overwrite hooks may require their own kind
       // Skip self-dependency for overwrite hooks (they need the original facet to exist,
       // but they're replacing it, so no cycle in facet dependency graph)
       if (dep === kind && hookOverwrite) {
@@ -55,10 +72,15 @@ export function buildDepGraph(hooksByKind, facetsByKind, subsystem = null) {
         // But don't add the dependency edge (no cycle in facet graph)
         continue;
       }
+      
+      // Validate dependency exists
       if (!facetsByKind[dep]) {
         const src = lastHook?.source || kind;
         throw new Error(`Hook '${kind}' (from ${src}) requires missing facet '${dep}'.`);
       }
+      
+      // Add edge: dep -> kind (if not already present)
+      // This means "kind depends on dep", so dep must be initialized first
       if (!graph.get(dep).has(kind)) {
         graph.get(dep).add(kind);
         indeg.set(kind, (indeg.get(kind) || 0) + 1);
@@ -66,14 +88,18 @@ export function buildDepGraph(hooksByKind, facetsByKind, subsystem = null) {
     }
   }
 
-  // Then, add dependencies from facet metadata (facet.getDependencies())
+  // Phase 2: Add dependencies from facet metadata (facet.getDependencies())
+  // Facets can declare additional dependencies at runtime (beyond hook.required)
   for (const [kind, facet] of Object.entries(facetsByKind)) {
     const facetDeps = (typeof facet.getDependencies === 'function' && facet.getDependencies()) || [];
     for (const dep of facetDeps) {
+      // Validate dependency exists
       if (!facetsByKind[dep]) {
         const src = facet.getSource?.() || kind;
         throw new Error(`Facet '${kind}' (from ${src}) depends on missing '${dep}'.`);
       }
+      
+      // Add edge: dep -> kind (if not already present)
       if (!graph.get(dep).has(kind)) {
         graph.get(dep).add(kind);
         indeg.set(kind, (indeg.get(kind) || 0) + 1);
@@ -87,6 +113,17 @@ export function buildDepGraph(hooksByKind, facetsByKind, subsystem = null) {
 /**
  * Kahn topological sort with diagnostics and caching.
  * 
+ * Implements Kahn's algorithm for topological sorting (O(V + E) complexity).
+ * This algorithm finds a linear ordering of vertices such that for every directed
+ * edge (u, v), vertex u comes before v in the ordering.
+ * 
+ * Algorithm steps:
+ * 1. Find all vertices with no incoming edges (indegree = 0)
+ * 2. Add them to a queue
+ * 3. Process queue: remove vertex, add to result, decrement indegree of neighbors
+ * 4. If any neighbor's indegree becomes 0, add it to the queue
+ * 5. If result length < total vertices, a cycle exists
+ * 
  * @param {Object} graphData - Dependency graph data { graph, indeg, kinds }
  * @param {DependencyGraphCache} graphCache - Optional cache for storing results
  * @param {string} cacheKey - Optional cache key
@@ -94,7 +131,7 @@ export function buildDepGraph(hooksByKind, facetsByKind, subsystem = null) {
  * @throws {Error} If a dependency cycle is detected
  */
 export function topoSort({ graph, indeg, kinds }, graphCache = null, cacheKey = null) {
-  // Check cache if provided
+  // Check cache if provided - avoid recomputing if we've seen this graph before
   if (graphCache && cacheKey) {
     const cached = graphCache.get(cacheKey);
     if (cached) {
@@ -106,24 +143,42 @@ export function topoSort({ graph, indeg, kinds }, graphCache = null, cacheKey =
     }
   }
 
+  // Step 1: Initialize queue with all vertices that have no incoming edges
+  // These are the "roots" of the dependency graph - they can be processed first
   const q = [];
-  for (const k of kinds) if ((indeg.get(k) || 0) === 0) q.push(k);
+  for (const k of kinds) {
+    if ((indeg.get(k) || 0) === 0) {
+      q.push(k);
+    }
+  }
 
+  // Step 2: Process queue using Kahn's algorithm
   const ordered = [];
   while (q.length) {
+    // Remove a vertex with no incoming edges
     const n = q.shift();
     ordered.push(n);
+    
+    // Step 3: For each neighbor (dependent) of this vertex:
+    // - Decrement its indegree (one less dependency to wait for)
+    // - If indegree becomes 0, add it to queue (ready to process)
     for (const m of graph.get(n)) {
-      indeg.set(m, indeg.get(m) - 1);
-      if (indeg.get(m) === 0) q.push(m);
+      const newIndeg = indeg.get(m) - 1;
+      indeg.set(m, newIndeg);
+      if (newIndeg === 0) {
+        q.push(m);
+      }
     }
   }
 
+  // Step 4: Check for cycles
+  // If we couldn't process all vertices, there's a circular dependency
+  // The "stuck" vertices are those still with indegree > 0 (part of a cycle)
   if (ordered.length !== kinds.length) {
     const stuck = kinds.filter(k => (indeg.get(k) || 0) > 0);
     const error = `Facet dependency cycle detected among: ${stuck.join(', ')}`;
     
-    // Cache invalid result
+    // Cache invalid result so we don't recompute the same invalid graph
     if (graphCache && cacheKey) {
       graphCache.set(cacheKey, false, null, error);
     }
@@ -131,7 +186,8 @@ export function topoSort({ graph, indeg, kinds }, graphCache = null, cacheKey =
     throw new Error(error);
   }
 
-  // Cache valid result
+  // Step 5: Cache valid result for future use
+  // This significantly speeds up repeated builds with the same dependency structure
   if (graphCache && cacheKey) {
     graphCache.set(cacheKey, true, ordered, null);
   }

package/src/builder/hook-processor.js

@@ -5,6 +5,7 @@
  */
 
 import { Facet } from '../core/facet.js';
+import { instrumentHookExecution } from '../utils/instrumentation.js';
 
 /**
  * Order hooks based on their dependencies using topological sort.
@@ -44,32 +45,39 @@ export function orderHooksByDependencies(hooks) {
   }
 
   // Build dependency graph using hook IDs
+  // This graph tracks hook-to-hook dependencies (not facet-to-facet)
+  // We need this because multiple hooks can create the same facet kind
   const hookDepGraph = new Map(); // hookId -> Set(dependent hookIds)
   const hookIndeg = new Map(); // hookId -> indegree
   
-  // Initialize graph
+  // Initialize graph: all hooks start with no dependencies
   for (const { hookId } of hookArray) {
     hookDepGraph.set(hookId, new Set());
     hookIndeg.set(hookId, 0);
   }
   
   // Add edges: if hook A requires kind X, find the hook(s) that create X
+  // This creates a dependency: "hook A must run after hook that creates X"
   for (const { hookId, kind, required, overwrite, index } of hookArray) {
     for (const depKind of required) {
       const depHookIds = kindToHookIds.get(depKind) || [];
       
       if (depHookIds.length === 0) {
         // Dependency not in our hook list (might be external or not yet created)
+        // Skip - we'll validate this later in validateHookDependencies
         continue;
       }
       
+      // Special case: overwrite hooks requiring their own kind
       // If this hook requires its own kind (overwrite scenario)
       if (depKind === kind && overwrite) {
         // Find the previous hook of this kind (the one it's overwriting)
+        // Overwrite hooks must run AFTER the hook they're replacing
         if (index > 0) {
           const previousHookId = `${kind}:${index - 1}`;
           if (hookIdMap.has(previousHookId)) {
-            // Overwrite hook depends on the previous hook of same kind
+            // Add edge: previousHook -> currentHook
+            // This ensures the overwrite hook runs after the original
             hookDepGraph.get(previousHookId).add(hookId);
             hookIndeg.set(hookId, (hookIndeg.get(hookId) || 0) + 1);
           }
@@ -79,27 +87,35 @@ export function orderHooksByDependencies(hooks) {
       
       // For other dependencies, depend on the LAST hook that creates that kind
       // (the most recent/enhanced version)
+      // This ensures hooks always depend on the final version of a facet
       if (depHookIds.length > 0) {
         const lastDepHookId = depHookIds[depHookIds.length - 1];
+        // Add edge: lastDepHook -> currentHook
         hookDepGraph.get(lastDepHookId).add(hookId);
         hookIndeg.set(hookId, (hookIndeg.get(hookId) || 0) + 1);
       }
     }
   }
   
-  // Topological sort on hook IDs
+  // Topological sort on hook IDs using Kahn's algorithm
+  // This determines the order in which hooks should be executed
   const orderedHookIds = [];
   const queue = [];
+  
+  // Step 1: Find all hooks with no dependencies (indegree = 0)
   for (const { hookId } of hookArray) {
     if (hookIndeg.get(hookId) === 0) {
       queue.push(hookId);
     }
   }
   
+  // Step 2: Process queue - remove hooks with no dependencies, add to result
   while (queue.length > 0) {
     const hookId = queue.shift();
     orderedHookIds.push(hookId);
     
+    // Step 3: For each dependent hook, decrement its indegree
+    // If indegree becomes 0, it's ready to process (add to queue)
     for (const dependent of hookDepGraph.get(hookId)) {
       const newIndeg = hookIndeg.get(dependent) - 1;
       hookIndeg.set(dependent, newIndeg);
@@ -109,6 +125,11 @@ export function orderHooksByDependencies(hooks) {
     }
   }
   
+  // Note: We don't check for cycles here because:
+  // 1. Hook-level cycles are less common (hooks are usually independent)
+  // 2. Facet-level cycles are caught in buildDepGraph/topoSort
+  // 3. If a cycle exists, orderedHookIds.length < hookArray.length
+  
   // Build ordered hooks array
   const orderedHooks = [];
   for (const hookId of orderedHookIds) {
@@ -146,7 +167,8 @@ export function executeHooksAndCreateFacets(orderedHooks, resolvedCtx, subsystem
 
     let facet;
     try {
-      facet = hook(resolvedCtx, subsystem.api, subsystem);
+      // Instrument hook execution for timing
+      facet = instrumentHookExecution(hook, resolvedCtx, subsystem.api, subsystem);
     } catch (error) {
       throw new Error(`Hook '${hookKind}' (from ${hookSource}) failed during execution: ${error.message}`);
     }