mycelia-kernel-plugin 1.2.0 → 1.4.0

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/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/index.js

@@ -34,11 +34,29 @@ export { useListeners } from './hooks/listeners/use-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();
+  };
+}
+
+

package/src/qwik/index.js

@@ -0,0 +1,178 @@
+/**
+ * Mycelia Plugin System - Qwik Bindings
+ * 
+ * Qwik utilities that make the Mycelia Plugin System feel natural
+ * inside Qwik applications using signals and context.
+ * 
+ * @example
+ * ```tsx
+ * import { MyceliaProvider, useFacet, useListener } from 'mycelia-kernel-plugin/qwik';
+ * 
+ * const buildSystem = () => useBase('app')
+ *   .use(useDatabase)
+ *   .build();
+ * 
+ * export default component$(() => {
+ *   return (
+ *     <MyceliaProvider build={buildSystem}>
+ *       <MyComponent />
+ *     </MyceliaProvider>
+ *   );
+ * });
+ * 
+ * export const MyComponent = component$(() => {
+ *   const db = useFacet('database');
+ *   useListener('user:created', (msg) => console.log(msg));
+ *   // ...
+ * });
+ * ```
+ */
+
+import { createContextId, useContextProvider, useContext, useSignal, useStore, useTask$, component$, Slot } from '@builder.io/qwik';
+
+// ============================================================================
+// Core Bindings: Provider + Basic Hooks
+// ============================================================================
+
+const MyceliaContextId = createContextId('mycelia');
+
+/**
+ * MyceliaProvider - Provides Mycelia system to Qwik component tree
+ * 
+ * @param {Object} props
+ * @param {Function} props.build - Async function that returns a built system
+ * @param {import('@builder.io/qwik').QRL} props.children - Child components
+ * @param {import('@builder.io/qwik').QRL} [props.fallback] - Optional loading/fallback component
+ * 
+ * @example
+ * ```tsx
+ * export default component$(() => {
+ *   return (
+ *     <MyceliaProvider build={buildSystem}>
+ *       <App />
+ *     </MyceliaProvider>
+ *   );
+ * });
+ * ```
+ */
+export const MyceliaProvider = component$(({ build, fallback = null }) => {
+  const system = useSignal(null);
+  const error = useSignal(null);
+  const loading = useSignal(true);
+
+  useTask$(async () => {
+    try {
+      const builtSystem = await build();
+      system.value = builtSystem;
+      error.value = null;
+    } catch (err) {
+      error.value = err;
+      system.value = null;
+    } finally {
+      loading.value = false;
+    }
+  });
+
+  const context = {
+    system,
+    error,
+    loading
+  };
+
+  useContextProvider(MyceliaContextId, context);
+
+  if (error.value) {
+    throw error.value; // Let error boundaries handle it
+  }
+
+  if (loading.value) {
+    return fallback || <div>Loading...</div>;
+  }
+
+  return <Slot />;
+});
+
+/**
+ * useMycelia - Get the Mycelia system from context
+ * 
+ * @returns {Object} The Mycelia system instance
+ * @throws {Error} If used outside MyceliaProvider
+ * 
+ * @example
+ * ```tsx
+ * export const MyComponent = component$(() => {
+ *   const system = useMycelia();
+ *   // Use system.find(), system.listeners, etc.
+ * });
+ * ```
+ */
+export function useMycelia() {
+  const context = useContext(MyceliaContextId);
+  if (!context) {
+    throw new Error('useMycelia must be used within a MyceliaProvider');
+  }
+  return context.system.value;
+}
+
+/**
+ * useMyceliaContext - Get the full Mycelia context (system, loading, error)
+ * 
+ * @returns {Object} Context object with system, loading, and error signals
+ * @throws {Error} If used outside MyceliaProvider
+ * 
+ * @example
+ * ```tsx
+ * export const MyComponent = component$(() => {
+ *   const { system, loading, error } = useMyceliaContext();
+ *   if (loading.value) return <div>Loading...</div>;
+ *   if (error.value) return <div>Error: {error.value.message}</div>;
+ *   return <div>System: {system.value.name}</div>;
+ * });
+ * ```
+ */
+export function useMyceliaContext() {
+  const context = useContext(MyceliaContextId);
+  if (!context) {
+    throw new Error('useMyceliaContext must be used within a MyceliaProvider');
+  }
+  return context;
+}
+
+/**
+ * useFacet - Get a facet by kind from the system (reactive signal)
+ * 
+ * @param {string} kind - Facet kind identifier
+ * @returns {import('@builder.io/qwik').Signal} Signal containing the facet instance, or null if not found
+ * 
+ * @example
+ * ```tsx
+ * export const UserList = component$(() => {
+ *   const db = useFacet('database');
+ *   // Use db.value.query(), etc.
+ * });
+ * ```
+ */
+export function useFacet(kind) {
+  const context = useMyceliaContext();
+  const facet = useSignal(null);
+
+  useTask$(({ track }) => {
+    const system = track(() => context.system.value);
+    facet.value = system?.find?.(kind) ?? null;
+  });
+
+  return facet;
+}
+
+// Re-export listener helpers
+export { useListener, useEventStream } from './listeners.js';
+
+// Re-export queue helpers
+export { useQueueStatus, useQueueDrain } from './queues.js';
+
+// Re-export builder helpers
+export { createQwikSystemBuilder } from './builders.js';
+
+// Re-export facet signal generator
+export { createFacetSignal } from './signals.js';
+

package/src/qwik/listeners.js

@@ -0,0 +1,96 @@
+/**
+ * Qwik Listener Helpers
+ */
+
+import { useTask$, useSignal } from '@builder.io/qwik';
+import { useMycelia } from './index.js';
+
+// Note: Qwik's useTask$ requires proper serialization
+// Event handlers should be QRL-wrapped for proper serialization
+
+/**
+ * useListener - Register an event listener with automatic cleanup
+ * 
+ * @param {string} eventName - Event name/path to listen for
+ * @param {Function} handler - Handler function: (message) => void
+ * 
+ * @example
+ * ```tsx
+ * export const AuditLog = component$(() => {
+ *   useListener('user:created', (msg) => {
+ *     console.log('User created:', msg.body);
+ *   });
+ *   // ...
+ * });
+ * ```
+ */
+export function useListener(eventName, handler) {
+  const system = useMycelia();
+  const listeners = system.listeners; // useListeners facet
+
+  useTask$(({ cleanup }) => {
+    if (!listeners || !listeners.hasListeners?.()) {
+      return;
+    }
+
+    const wrappedHandler = (msg) => {
+      handler(msg);
+    };
+
+    listeners.on(eventName, wrappedHandler);
+
+    cleanup(() => {
+      listeners.off?.(eventName, wrappedHandler);
+    });
+  });
+}
+
+/**
+ * useEventStream - Subscribe to events and keep them in Qwik signal
+ * 
+ * @param {string} eventName - Event name/path to listen for
+ * @param {Object} [options={}] - Options
+ * @param {boolean} [options.accumulate=false] - If true, accumulate events in array
+ * @returns {import('@builder.io/qwik').Signal} Signal containing latest event value, array of events, or null
+ * 
+ * @example
+ * ```tsx
+ * export const EventList = component$(() => {
+ *   const events = useEventStream('todo:created', { accumulate: true });
+ *   return (
+ *     <ul>
+ *       {events.value?.map(e => <li key={e.id}>{e.text}</li>)}
+ *     </ul>
+ *   );
+ * });
+ * ```
+ */
+export function useEventStream(eventName, options = {}) {
+  const { accumulate = false } = options;
+  const value = useSignal(accumulate ? [] : null);
+  const system = useMycelia();
+  const listeners = system.listeners;
+
+  useTask$(({ cleanup }) => {
+    if (!listeners || !listeners.hasListeners?.()) {
+      return;
+    }
+
+    const handler = (msg) => {
+      if (accumulate) {
+        value.value = [...value.value, msg.body];
+      } else {
+        value.value = msg.body;
+      }
+    };
+
+    listeners.on(eventName, handler);
+
+    cleanup(() => {
+      listeners.off?.(eventName, handler);
+    });
+  });
+
+  return value;
+}
+