mycelia-kernel-plugin 1.3.0 → 1.4.1

package/src/builder/utils.js

@@ -9,20 +9,35 @@ import {
   executeHooksAndCreateFacets,
   validateHookDependencies,
 } from './hook-processor.js';
+import { instrumentBuildPhase } from '../utils/instrumentation.js';
 
 // Re-export deepMerge for backward compatibility
 export { deepMerge } from './context-resolver.js';
 
 /**
- * VERIFY (pure):
- * - resolve ctx (pure)
- * - collect hooks (defaults + user)
- * - instantiate facets
- * - validate + topo-sort (with caching)
+ * VERIFY (pure, side-effect-free):
+ * 
+ * This is the first phase of the two-phase build process. It:
+ * 1. Resolves context (pure operation)
+ * 2. Collects hooks (defaults + user)
+ * 3. Orders hooks by dependencies (topological sort)
+ * 4. Executes hooks to create facets (temporary, for dependency lookups)
+ * 5. Validates facets against contracts
+ * 6. Builds dependency graph and sorts facets (with caching)
+ * 
+ * Key property: This phase is pure - it doesn't mutate the subsystem state.
+ * Facets are temporarily added to api.__facets for dependency lookups only.
+ * 
+ * @param {BaseSubsystem} subsystem - Subsystem to verify
+ * @param {Object} ctx - Context to merge
+ * @param {DependencyGraphCache} graphCache - Optional cache for dependency graphs
+ * @returns {Object} Build plan with { resolvedCtx, orderedKinds, facetsByKind, graphCache }
  */
 export function verifySubsystemBuild(subsystem, ctx = {}, graphCache = null) {
+  // Step 1: Resolve context (deep merge with subsystem.ctx)
   const resolvedCtx = resolveCtx(subsystem, ctx);
 
+  // Step 2: Collect all hooks (defaults + user)
   // Check whether the defaults are defined as a DefaultHooks instance or an array of hooks. 
   // If it's a DefaultHooks instance, use the list() method to get the array of hooks. 
   const defaults = Array.isArray(subsystem.defaultHooks)
@@ -32,22 +47,28 @@ export function verifySubsystemBuild(subsystem, ctx = {}, graphCache = null) {
   const user = Array.isArray(subsystem.hooks) ? subsystem.hooks : [];
   const hooks = [...defaults, ...user];
 
-  // Extract hook metadata
+  // Step 3: Extract hook metadata (kind, required, overwrite, etc.)
   const hooksByKind = extractHookMetadata(hooks);
 
-  // Order hooks based on dependencies
+  // Step 4: Order hooks based on their dependencies (topological sort)
+  // This ensures hooks are executed in the correct order
   const orderedHooks = orderHooksByDependencies(hooks);
 
-  // Execute hooks and create facets
+  // Step 5: Execute hooks and create facets
+  // Facets are created here temporarily so later hooks can access them via subsystem.find()
+  // They will be properly initialized/attached in the execute phase
   const { facetsByKind } = executeHooksAndCreateFacets(orderedHooks, resolvedCtx, subsystem, hooksByKind);
 
-  // Validate facets against their contracts (before dependency graph building)
+  // Step 6: Validate facets against their contracts (before dependency graph building)
+  // This ensures all facets satisfy their declared contracts
   validateFacets(facetsByKind, resolvedCtx, subsystem, defaultContractRegistry);
 
-  // Validate hook.required dependencies exist
+  // Step 7: Validate hook.required dependencies exist
+  // Double-check that all declared dependencies are satisfied
   validateHookDependencies(hooksByKind, facetsByKind, subsystem);
 
-  // Create cache key from sorted facet kinds
+  // Step 8: Create cache key from sorted facet kinds
+  // This key is used to cache the dependency graph computation
   const kinds = Object.keys(facetsByKind);
   const cacheKey = graphCache ? createCacheKey(kinds) : null;
 
@@ -56,21 +77,25 @@ export function verifySubsystemBuild(subsystem, ctx = {}, graphCache = null) {
     resolvedCtx.graphCache = graphCache;
   }
 
-  // Check cache before building graph
+  // Step 9: Check cache before building graph
+  // If we've computed this dependency graph before, reuse the result
   if (graphCache && cacheKey) {
     const cached = graphCache.get(cacheKey);
     if (cached) {
       if (cached.valid) {
         // Return cached result (skip graph building and sorting)
+        // This significantly speeds up repeated builds with the same dependency structure
         return { resolvedCtx, orderedKinds: cached.orderedKinds, facetsByKind, graphCache };
       } else {
-        // Throw cached error
+        // Throw cached error (don't recompute known-invalid graph)
         throw new Error(cached.error || 'Cached dependency graph error');
       }
     }
   }
 
-  // Build graph and sort (will cache result in topoSort)
+  // Step 10: Build dependency graph and sort facets
+  // This computes the initialization order based on facet dependencies
+  // The result will be cached in topoSort for future use
   const graph = buildDepGraph(hooksByKind, facetsByKind, subsystem);
   const orderedKinds = topoSort(graph, graphCache, cacheKey);
 
@@ -79,17 +104,35 @@ export function verifySubsystemBuild(subsystem, ctx = {}, graphCache = null) {
 
 /**
  * EXECUTE (transactional):
- * - assign resolved ctx
- * - add/init/attach facets via FacetManager.addMany
- * - build children
+ * 
+ * This is the second phase of the two-phase build process. It:
+ * 1. Assigns resolved context to subsystem
+ * 2. Separates facets into new vs overwrite
+ * 3. Removes overwritten facets
+ * 4. Adds/initializes/attaches facets via FacetManager.addMany (transactional)
+ * 5. Builds child subsystems recursively
+ * 
+ * Key property: This phase is transactional - if any step fails, all changes are rolled back.
+ * Facets are properly initialized (onInit callbacks) and attached to the subsystem.
+ * 
+ * @param {BaseSubsystem} subsystem - Subsystem to build
+ * @param {Object} plan - Build plan from verifySubsystemBuild
  */
 export async function buildSubsystem(subsystem, plan) {
+  // Instrument the build phase if enabled
+  return instrumentBuildPhase(subsystem, async () => {
+    return buildSubsystemInternal(subsystem, plan);
+  });
+}
+
+async function buildSubsystemInternal(subsystem, plan) {
   if (!plan) throw new Error('buildSubsystem: invalid plan');
   const { resolvedCtx, orderedKinds, facetsByKind } = plan;
   if (!Array.isArray(orderedKinds)) throw new Error('buildSubsystem: invalid plan');
   if (!facetsByKind || typeof facetsByKind !== 'object' || Array.isArray(facetsByKind)) throw new Error('buildSubsystem: invalid plan');
   
   // Validate consistency: if one is non-empty, the other must match
+  // This ensures the plan is internally consistent
   const hasOrderedKinds = orderedKinds.length > 0;
   const hasFacetsByKind = Object.keys(facetsByKind).length > 0;
   
@@ -99,14 +142,17 @@ export async function buildSubsystem(subsystem, plan) {
   if (hasOrderedKinds && !hasFacetsByKind) throw new Error('buildSubsystem: invalid plan');
   // Both empty is valid (no facets to add)
 
+  // Step 1: Assign resolved context to subsystem
   subsystem.ctx = resolvedCtx;
 
-  // Separate facets into new and overwrite
+  // Step 2: Separate facets into new and overwrite categories
+  // This allows us to handle overwrites correctly (remove old, add new)
   const facetsToAdd = {};
   const kindsToAdd = [];
   const facetsToOverwrite = {};
   const kindsToOverwrite = [];
   
+  // Process facets in dependency order (from topological sort)
   for (const kind of orderedKinds) {
     const facet = facetsByKind[kind];
     const existingFacet = subsystem.api.__facets.find(kind);
@@ -118,13 +164,14 @@ export async function buildSubsystem(subsystem, plan) {
     } else if (existingFacet === facet) {
       // Same facet instance - this was added during verify phase for dependency lookups
       // It needs to be properly initialized/attached, so add it
+      // This handles the case where facets are temporarily added in verify phase
       facetsToAdd[kind] = facet;
       kindsToAdd.push(kind);
     } else {
       // Different facet instance - check if we can overwrite
       const canOverwrite = facet.shouldOverwrite?.() === true;
       if (canOverwrite) {
-        // Remove old facet first, then add new one
+        // Mark for overwrite: remove old facet first, then add new one
         facetsToOverwrite[kind] = facet;
         kindsToOverwrite.push(kind);
       } else {
@@ -134,7 +181,8 @@ export async function buildSubsystem(subsystem, plan) {
     }
   }
 
-  // First, remove overwritten facets
+  // Step 3: Remove overwritten facets first (before adding new ones)
+  // This ensures clean state before adding replacements
   for (const kind of kindsToOverwrite) {
     subsystem.api.__facets.remove(kind);
     // Also remove from subsystem property if it exists
@@ -142,16 +190,22 @@ export async function buildSubsystem(subsystem, plan) {
       try {
         delete subsystem[kind];
       } catch {
-        // Best-effort cleanup
+        // Best-effort cleanup (property might be non-configurable)
       }
     }
   }
 
-  // Then add all facets (new + overwritten)
+  // Step 4: Add all facets (new + overwritten) in a single transactional operation
+  // This ensures atomicity - if any facet fails to initialize, all are rolled back
   const allFacets = { ...facetsToAdd, ...facetsToOverwrite };
   const allKinds = [...kindsToAdd, ...kindsToOverwrite];
   
   if (allKinds.length > 0) {
+    // addMany is transactional - it will:
+    // 1. Register all facets
+    // 2. Initialize them (call onInit callbacks) in parallel within dependency levels
+    // 3. Attach them to the subsystem
+    // 4. Roll back everything if any initialization fails
     await subsystem.api.__facets.addMany(allKinds, allFacets, {
       init: true,
       attach: true,
@@ -160,6 +214,8 @@ export async function buildSubsystem(subsystem, plan) {
     });
   }
 
+  // Step 5: Build child subsystems recursively
+  // This allows nested plugin systems with their own dependency graphs
   await buildChildren(subsystem);
 }
 

package/src/contract/contracts/listeners.contract.js

@@ -19,6 +19,7 @@ import { createFacetContract } from '../facet-contract.js';
  * Required methods:
  * - on: Register a listener for a specific message path
  * - off: Unregister a listener for a specific message path
+ * - emit: Emit an event to listeners for a specific path
  * - hasListeners: Check if listeners are enabled
  * - enableListeners: Enable listeners and initialize ListenerManager
  * - disableListeners: Disable listeners (but keep manager instance)
@@ -37,6 +38,7 @@ export const listenersContract = createFacetContract({
   requiredMethods: [
     'on',
     'off',
+    'emit',
     'hasListeners',
     'enableListeners',
     'disableListeners'

package/src/core/facet.js

@@ -1,4 +1,5 @@
 import { getDefaultVersion, isValidSemver } from '../utils/semver.js';
+import { instrumentFacetInit, instrumentDisposeCallback } from '../utils/instrumentation.js';
 
 export class Facet {
   #kind;
@@ -121,15 +122,27 @@ export class Facet {
 
   async init(ctx, api, subsystem) {
     if (this.#isInit) return;
-    if (this.#initCallback) {
+    
+    // Use instrumentation if available and enabled, otherwise call callback directly
+    if (subsystem && typeof instrumentFacetInit === 'function') {
+      // Instrumentation will handle timing and call the callback
+      await instrumentFacetInit(this, ctx, api, subsystem, this.#initCallback);
+    } else if (this.#initCallback) {
+      // No instrumentation - call callback directly
       await this.#initCallback({ ctx, api, subsystem, facet: this });
     }
+    
     this.#isInit = true;
     Object.freeze(this);
   }
 
-  async dispose() {
-    if (this.#disposeCallback) {
+  async dispose(subsystem) {
+    // Use instrumentation if available and enabled, otherwise call callback directly
+    if (subsystem && this.#disposeCallback && typeof instrumentDisposeCallback === 'function') {
+      // Instrumentation will handle timing and call the callback
+      await instrumentDisposeCallback(this, subsystem, this.#disposeCallback);
+    } else if (this.#disposeCallback) {
+      // No instrumentation - call callback directly
       await this.#disposeCallback(this);
     }
   }

package/src/hooks/listeners/use-simple-listeners.js

@@ -0,0 +1,172 @@
+/**
+ * useSimpleListeners Hook
+ * 
+ * Provides simple listener management functionality to subsystems using mitt.
+ * A lightweight alternative to useListeners that wraps the mitt event emitter.
+ * 
+ * @param {Object} ctx - Context object containing config.listeners for listener configuration
+ * @param {Object} api - Subsystem API being built
+ * @param {BaseSubsystem} subsystem - Subsystem instance
+ * @returns {Facet} Facet object with listener methods
+ */
+import mitt from 'mitt';
+import { Facet } from '../../core/facet.js';
+import { createHook } from '../../core/create-hook.js';
+import { getDebugFlag } from '../../utils/debug-flag.js';
+import { createLogger } from '../../utils/logger.js';
+
+export const useSimpleListeners = createHook({
+  kind: 'listeners',
+  version: '1.0.0',
+  overwrite: false,
+  required: [],
+  attach: true,
+  source: import.meta.url,
+  contract: 'listeners',
+  // eslint-disable-next-line no-unused-vars
+  fn: (ctx, api, _subsystem) => {
+    const { name } = api;
+    const config = ctx.config?.listeners || {};
+    const debug = getDebugFlag(config, ctx);
+    
+    // Listeners are optional - can be enabled/disabled
+    let emitter = null;
+    let listenersEnabled = false;
+    
+    return new Facet('listeners', { attach: true, source: import.meta.url, contract: 'listeners' })
+      .add({
+      
+      /**
+       * Check if listeners are enabled
+       * @returns {boolean} True if listeners are enabled
+       */
+      hasListeners() {
+        return listenersEnabled && emitter !== null;
+      },
+      
+      /**
+       * Enable listeners
+       * @param {Object} [listenerOptions={}] - Options (currently unused, for API compatibility)
+       */
+      enableListeners(listenerOptions = {}) {
+        if (emitter === null) {
+          emitter = mitt();
+        }
+        listenersEnabled = true;
+      },
+      
+      /**
+       * Disable listeners
+       */
+      disableListeners() {
+        listenersEnabled = false;
+      },
+      
+      /**
+       * Register a listener for a specific path
+       * @param {string} path - Message path to listen for
+       * @param {Function} handler - Handler function
+       * @param {Object} [options={}] - Registration options (for API compatibility)
+       * @returns {boolean} Success status
+       */
+      on(path, handler, options = {}) {
+        // Check if listeners are enabled
+        if (!listenersEnabled || emitter === null) {
+          const runtimeDebug = options.debug !== undefined ? options.debug : debug;
+          if (runtimeDebug) {
+            const runtimeLogger = createLogger(runtimeDebug, `useSimpleListeners ${name}`);
+            runtimeLogger.warn('Cannot register listener - listeners not enabled');
+          }
+          return false;
+        }
+        
+        // Validate handler is a function
+        if (typeof handler !== 'function') {
+          if (debug) {
+            const runtimeLogger = createLogger(debug, `useSimpleListeners ${name}`);
+            runtimeLogger.warn('Handler must be a function');
+          }
+          return false;
+        }
+        
+        // Register with mitt
+        emitter.on(path, handler);
+        return true;
+      },
+      
+      /**
+       * Unregister a listener for a specific path
+       * @param {string} path - Message path
+       * @param {Function} handler - Handler function to remove
+       * @param {Object} [options={}] - Unregistration options (for API compatibility)
+       * @returns {boolean} Success status
+       */
+      off(path, handler, options = {}) {
+        // Check if listeners are enabled
+        if (!listenersEnabled || emitter === null) {
+          const runtimeDebug = options.debug !== undefined ? options.debug : debug;
+          if (runtimeDebug) {
+            const runtimeLogger = createLogger(runtimeDebug, `useSimpleListeners ${name}`);
+            runtimeLogger.warn('Cannot unregister listener - listeners not enabled');
+          }
+          return false;
+        }
+        
+        // Validate handler is a function
+        if (typeof handler !== 'function') {
+          if (debug) {
+            const runtimeLogger = createLogger(debug, `useSimpleListeners ${name}`);
+            runtimeLogger.warn('Handler must be a function');
+          }
+          return false;
+        }
+        
+        // Unregister from mitt
+        emitter.off(path, handler);
+        return true;
+      },
+      
+      /**
+       * Emit an event to listeners for a specific path
+       * @param {string} path - Message path to emit to
+       * @param {any} message - Message/data to send to listeners
+       * @returns {number} Number of listeners notified, or 0 if listeners not enabled
+       * 
+       * @example
+       * // Emit event to listeners
+       * const notified = subsystem.listeners.emit('layers/create', message);
+       */
+      emit(path, message) {
+        // Check if listeners are enabled
+        if (!listenersEnabled || emitter === null) {
+          if (debug) {
+            const runtimeLogger = createLogger(debug, `useSimpleListeners ${name}`);
+            runtimeLogger.warn('Cannot emit event - listeners not enabled');
+          }
+          return 0;
+        }
+        
+        // Get listeners count before emitting (mitt doesn't return count)
+        const listeners = emitter.all.get(path);
+        const count = listeners ? listeners.length : 0;
+        
+        // Emit to mitt
+        emitter.emit(path, message);
+        
+        return count;
+      },
+      
+      /**
+       * Expose emitter property for direct access
+       * Returns null if listeners are not enabled
+       */
+      get listeners() {
+        return emitter;
+      },
+      
+      // Expose emitter for internal use (compatible with listeners contract)
+      _listenerManager: () => emitter
+      });
+  }
+});
+

package/src/index.js

@@ -31,14 +31,33 @@ export * from './contract/contracts/index.js';
 
 // Hook exports
 export { useListeners } from './hooks/listeners/use-listeners.js';
+export { useSimpleListeners } from './hooks/listeners/use-simple-listeners.js';
 export { useQueue } from './hooks/queue/use-queue.js';
 export { useSpeak } from './hooks/speak/use-speak.js';
 
+// Framework bindings are available via subpath exports:
+// - 'mycelia-kernel-plugin/react' for React bindings
+// - 'mycelia-kernel-plugin/vue' for Vue bindings
+// - 'mycelia-kernel-plugin/svelte' for Svelte bindings
+// - 'mycelia-kernel-plugin/angular' for Angular bindings
+// - 'mycelia-kernel-plugin/qwik' for Qwik bindings
+// - 'mycelia-kernel-plugin/solid' for Solid.js bindings
+// 
+// They are not re-exported from the main entry point to avoid
+// requiring framework dependencies when using the core system.
+
 // Utility exports
 export { createLogger, createSubsystemLogger } from './utils/logger.js';
 export { getDebugFlag } from './utils/debug-flag.js';
 export { findFacet } from './utils/find-facet.js';
 export { useBase } from './utils/use-base.js';
+export { 
+  isInstrumentationEnabled,
+  instrumentHookExecution,
+  instrumentFacetInit,
+  instrumentDisposeCallback,
+  instrumentBuildPhase
+} from './utils/instrumentation.js';
 export { 
   parseVersion, 
   isValidSemver, 

package/src/manager/facet-manager.js

@@ -1,5 +1,6 @@
 import { FacetManagerTransaction } from './facet-manager-transaction.js';
 import { createSubsystemLogger } from '../utils/logger.js';
+import { instrumentFacetInit, instrumentDisposeCallback } from '../utils/instrumentation.js';
 
 export class FacetManager {
   #facets = new Map(); // Map<kind, Array<facet>> - stores arrays of facets per kind, sorted by orderIndex
@@ -80,6 +81,7 @@ export class FacetManager {
     // 2) Init now
     try {
       if (opts.init && typeof facet.init === 'function') {
+        // facet.init() will handle instrumentation internally
         await facet.init(opts.ctx, opts.api, this.#subsystem);
       }
     } catch (err) {
@@ -546,14 +548,20 @@ export class FacetManager {
       if (Array.isArray(facets)) {
         for (const facet of facets) {
           if (typeof facet.dispose === 'function') {
-            try { await facet.dispose(subsystem); }
+            try { 
+              // facet.dispose() will handle instrumentation internally
+              await facet.dispose(subsystem);
+            }
             catch (e) { errors.push({ kind, error: e }); }
           }
         }
       } else {
         // Legacy: single facet
         if (typeof facets.dispose === 'function') {
-          try { await facets.dispose(subsystem); }
+          try { 
+            // facet.dispose() will handle instrumentation internally
+            await facets.dispose(subsystem);
+          }
           catch (e) { errors.push({ kind, error: e }); }
         }
       }

package/src/qwik/builders.js

@@ -0,0 +1,39 @@
+/**
+ * Qwik Builder Helpers
+ */
+
+/**
+ * createQwikSystemBuilder - Create a reusable system builder function for Qwik
+ * 
+ * @param {string} name - System name
+ * @param {Function} configure - Configuration function: (builder) => builder
+ * @returns {Function} Build function: () => Promise<System>
+ * 
+ * @example
+ * ```ts
+ * import { useBase } from 'mycelia-kernel-plugin';
+ * 
+ * const buildTodoSystem = createQwikSystemBuilder('todo-app', (b) =>
+ *   b
+ *     .config('database', { host: 'localhost' })
+ *     .use(useDatabase)
+ *     .use(useListeners)
+ * );
+ * 
+ * // Then use in Provider
+ * <MyceliaProvider build={buildTodoSystem}>
+ *   <App />
+ * </MyceliaProvider>
+ * ```
+ */
+export function createQwikSystemBuilder(name, configure) {
+  return async function build() {
+    // Import useBase - users should have it available
+    const { useBase } = await import('../utils/use-base.js');
+    let builder = useBase(name);
+    builder = configure(builder);
+    return builder.build();
+  };
+}
+
+