mycelia-kernel-plugin 1.0.0

package/src/builder/subsystem-builder.js

@@ -0,0 +1,104 @@
+import { verifySubsystemBuild, buildSubsystem as executeBuild, deepMerge } from './utils.js';
+
+export class SubsystemBuilder {
+  #subsystem;
+  #ctx = {};
+  #plan = null;
+  #lastCtxHash = null;
+  #lastGraphCache = null;
+
+  constructor(subsystem) {
+    if (!subsystem) throw new Error('SubsystemBuilder: subsystem is required');
+    this.#subsystem = subsystem;
+    // Note: ctx is resolved in verifySubsystemBuild, not stored here
+  }
+
+  // Simple hash function for context comparison
+  #hashCtx(ctx) {
+    try {
+      return JSON.stringify(ctx);
+    } catch {
+      // If JSON.stringify fails, use a fallback
+      return String(ctx);
+    }
+  }
+
+  withCtx(ctx = {}) {
+    // Shallow merge for most properties
+    const merged = { ...this.#ctx, ...ctx };
+    
+    // Deep merge config objects if both exist
+    if (this.#ctx.config && typeof this.#ctx.config === 'object' && 
+        ctx.config && typeof ctx.config === 'object' &&
+        !Array.isArray(this.#ctx.config) && !Array.isArray(ctx.config)) {
+      merged.config = deepMerge(this.#ctx.config, ctx.config);
+    }
+    
+    this.#ctx = merged;
+    return this;
+  }
+
+  clearCtx() {
+    this.#ctx = {};
+    this.#lastCtxHash = null;
+    this.#plan = null; // Clear plan when context is cleared
+    return this;
+  }
+
+  plan(graphCache = null) {
+    // Determine which graphCache to use (priority: subsystem.ctx > parameter > cached)
+    const subsystemCache = this.#subsystem.ctx?.graphCache;
+    
+    // Check if we have a cached plan and if the context hasn't changed
+    const currentCtxHash = this.#hashCtx(this.#ctx);
+    if (this.#plan && this.#lastCtxHash === currentCtxHash) {
+      // Update lastGraphCache if a new one is provided
+      const cacheToUse = subsystemCache || (graphCache !== null ? graphCache : this.#lastGraphCache);
+      if (cacheToUse !== this.#lastGraphCache) {
+        this.#lastGraphCache = cacheToUse;
+      }
+      // Return this for method chaining
+      return this;
+    }
+    
+    // Use the determined cache (subsystem.ctx takes priority, then parameter, then null)
+    const cacheToUse = subsystemCache || graphCache;
+    const result = verifySubsystemBuild(this.#subsystem, this.#ctx, cacheToUse);
+    // Extract plan and updated graphCache from result
+    const { graphCache: updatedGraphCache, ...plan } = result;
+    this.#plan = plan;
+    this.#lastCtxHash = currentCtxHash;
+    this.#lastGraphCache = updatedGraphCache || cacheToUse;
+    // Return this for method chaining
+    return this;
+  }
+
+  dryRun(graphCache = null) { return this.plan(graphCache); }
+
+  getPlan() { return this.#plan; }
+  
+  getGraphCache() { return this.#lastGraphCache; }
+
+  invalidate() { 
+    this.#plan = null;
+    this.#lastCtxHash = null;
+    this.#lastGraphCache = null;
+    return this;
+  }
+
+  /** Executes verify → transactional facet add/init/attach → build children. No internal guards here. */
+  async build(graphCache = null) {
+    // Create or use cached plan
+    this.plan(graphCache);
+    const plan = this.#plan;
+    if (!plan) {
+      throw new Error('SubsystemBuilder.build: failed to create plan');
+    }
+    // graphCache is already included in plan.resolvedCtx by verifySubsystemBuild
+    // and will be set on subsystem.ctx by buildSubsystem
+    
+    await executeBuild(this.#subsystem, plan);
+    return this.#subsystem;
+  }
+}
+

package/src/builder/utils.js

@@ -0,0 +1,165 @@
+import { buildChildren } from '../system/base-subsystem.utils.js';
+import { defaultContractRegistry } from '../contract/index.js';
+import { resolveCtx } from './context-resolver.js';
+import { createCacheKey, buildDepGraph, topoSort } from './dependency-graph.js';
+import { validateFacets } from './facet-validator.js';
+import {
+  extractHookMetadata,
+  orderHooksByDependencies,
+  executeHooksAndCreateFacets,
+  validateHookDependencies,
+} from './hook-processor.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)
+ */
+export function verifySubsystemBuild(subsystem, ctx = {}, graphCache = null) {
+  const resolvedCtx = resolveCtx(subsystem, ctx);
+
+  // 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)
+    ? subsystem.defaultHooks
+    : (subsystem.defaultHooks?.list?.() || []);
+
+  const user = Array.isArray(subsystem.hooks) ? subsystem.hooks : [];
+  const hooks = [...defaults, ...user];
+
+  // Extract hook metadata
+  const hooksByKind = extractHookMetadata(hooks);
+
+  // Order hooks based on dependencies
+  const orderedHooks = orderHooksByDependencies(hooks);
+
+  // Execute hooks and create facets
+  const { facetsByKind } = executeHooksAndCreateFacets(orderedHooks, resolvedCtx, subsystem, hooksByKind);
+
+  // Validate facets against their contracts (before dependency graph building)
+  validateFacets(facetsByKind, resolvedCtx, subsystem, defaultContractRegistry);
+
+  // Validate hook.required dependencies exist
+  validateHookDependencies(hooksByKind, facetsByKind, subsystem);
+
+  // Create cache key from sorted facet kinds
+  const kinds = Object.keys(facetsByKind);
+  const cacheKey = graphCache ? createCacheKey(kinds) : null;
+
+  // Include graphCache in resolvedCtx so it persists through buildSubsystem
+  if (graphCache) {
+    resolvedCtx.graphCache = graphCache;
+  }
+
+  // Check cache before building graph
+  if (graphCache && cacheKey) {
+    const cached = graphCache.get(cacheKey);
+    if (cached) {
+      if (cached.valid) {
+        // Return cached result (skip graph building and sorting)
+        return { resolvedCtx, orderedKinds: cached.orderedKinds, facetsByKind, graphCache };
+      } else {
+        // Throw cached error
+        throw new Error(cached.error || 'Cached dependency graph error');
+      }
+    }
+  }
+
+  // Build graph and sort (will cache result in topoSort)
+  const graph = buildDepGraph(hooksByKind, facetsByKind, subsystem);
+  const orderedKinds = topoSort(graph, graphCache, cacheKey);
+
+  return { resolvedCtx, orderedKinds, facetsByKind, graphCache };
+}
+
+/**
+ * EXECUTE (transactional):
+ * - assign resolved ctx
+ * - add/init/attach facets via FacetManager.addMany
+ * - build children
+ */
+export async function buildSubsystem(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
+  const hasOrderedKinds = orderedKinds.length > 0;
+  const hasFacetsByKind = Object.keys(facetsByKind).length > 0;
+  
+  // If orderedKinds is empty but facetsByKind has items, that's invalid
+  if (!hasOrderedKinds && hasFacetsByKind) throw new Error('buildSubsystem: invalid plan');
+  // If facetsByKind is empty but orderedKinds has items, that's invalid
+  if (hasOrderedKinds && !hasFacetsByKind) throw new Error('buildSubsystem: invalid plan');
+  // Both empty is valid (no facets to add)
+
+  subsystem.ctx = resolvedCtx;
+
+  // Separate facets into new and overwrite
+  const facetsToAdd = {};
+  const kindsToAdd = [];
+  const facetsToOverwrite = {};
+  const kindsToOverwrite = [];
+  
+  for (const kind of orderedKinds) {
+    const facet = facetsByKind[kind];
+    const existingFacet = subsystem.api.__facets.find(kind);
+    
+    if (!existingFacet) {
+      // New facet - add normally
+      facetsToAdd[kind] = facet;
+      kindsToAdd.push(kind);
+    } 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
+      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
+        facetsToOverwrite[kind] = facet;
+        kindsToOverwrite.push(kind);
+      } else {
+        // Cannot overwrite - skip (keep existing)
+        continue;
+      }
+    }
+  }
+
+  // First, remove overwritten facets
+  for (const kind of kindsToOverwrite) {
+    subsystem.api.__facets.remove(kind);
+    // Also remove from subsystem property if it exists
+    if (kind in subsystem) {
+      try {
+        delete subsystem[kind];
+      } catch {
+        // Best-effort cleanup
+      }
+    }
+  }
+
+  // Then add all facets (new + overwritten)
+  const allFacets = { ...facetsToAdd, ...facetsToOverwrite };
+  const allKinds = [...kindsToAdd, ...kindsToOverwrite];
+  
+  if (allKinds.length > 0) {
+    await subsystem.api.__facets.addMany(allKinds, allFacets, {
+      init: true,
+      attach: true,
+      ctx: resolvedCtx,
+      api: subsystem.api
+    });
+  }
+
+  await buildChildren(subsystem);
+}
+

package/src/contract/contracts/hierarchy.contract.js

@@ -0,0 +1,60 @@
+/**
+ * Hierarchy Facet Contract
+ * 
+ * Defines the contract that hierarchy facets must satisfy.
+ * Ensures all required hierarchy management methods are implemented and validates
+ * internal structure for compatibility with other hooks and BaseSubsystem.
+ * 
+ * @example
+ * import { hierarchyContract } from './hierarchy.contract.mycelia.js';
+ * 
+ * // Enforce contract on a hierarchy facet
+ * hierarchyContract.enforce(ctx, api, subsystem, hierarchyFacet);
+ */
+import { createFacetContract } from '../facet-contract.js';
+
+/**
+ * Hierarchy Facet Contract
+ * 
+ * Required methods:
+ * - addChild: Register a child subsystem under the current subsystem
+ * - removeChild: Remove a registered child subsystem by reference or by name
+ * - getChild: Retrieve a specific child subsystem by name
+ * - listChildren: Return an array of all currently registered child subsystems
+ * - setParent: Set the parent subsystem
+ * - getParent: Get the parent subsystem
+ * - isRoot: Check if this subsystem is a root (has no parent)
+ * - getRoot: Get the root subsystem by traversing up the parent chain
+ * - getLineage: Return the full ancestor chain (from root to node)
+ * 
+ * Required properties:
+ * - children: Getter for direct access to registry instance (returns an object)
+ * 
+ * Custom validation:
+ * - Validates children getter returns an object (not null or primitive)
+ */
+export const hierarchyContract = createFacetContract({
+  name: 'hierarchy',
+  requiredMethods: [
+    'addChild',
+    'removeChild',
+    'getChild',
+    'listChildren',
+    'setParent',
+    'getParent',
+    'isRoot',
+    'getRoot',
+    'getLineage'
+  ],
+  requiredProperties: [
+    'children'
+  ],
+  validate: (ctx, api, subsystem, facet) => {
+    // Validate children getter exists and returns an object
+    const registry = facet.children;
+    if (typeof registry !== 'object' || registry === null) {
+      throw new Error('Hierarchy facet children getter must return an object');
+    }
+  }
+});
+

package/src/contract/contracts/index.js

@@ -0,0 +1,17 @@
+/**
+ * Contract Exports
+ * 
+ * Exports all contract implementations for easy importing.
+ */
+
+export { hierarchyContract } from './hierarchy.contract.js';
+export { listenersContract } from './listeners.contract.js';
+export { processorContract } from './processor.contract.js';
+export { queueContract } from './queue.contract.js';
+export { routerContract } from './router.contract.js';
+export { schedulerContract } from './scheduler.contract.js';
+export { serverContract } from './server.contract.js';
+export { speakContract } from './speak.contract.js';
+export { storageContract } from './storage.contract.js';
+export { websocketContract } from './websocket.contract.js';
+

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

@@ -0,0 +1,66 @@
+/**
+ * Listeners Facet Contract
+ * 
+ * Defines the contract that listeners facets must satisfy.
+ * Ensures all required listener management methods are implemented and validates
+ * internal structure for compatibility with other hooks.
+ * 
+ * @example
+ * import { listenersContract } from './listeners.contract.mycelia.js';
+ * 
+ * // Enforce contract on a listeners facet
+ * listenersContract.enforce(ctx, api, subsystem, listenersFacet);
+ */
+import { createFacetContract } from '../facet-contract.js';
+
+/**
+ * Listeners Facet Contract
+ * 
+ * Required methods:
+ * - on: Register a listener for a specific message path
+ * - off: Unregister a listener for a specific message path
+ * - hasListeners: Check if listeners are enabled
+ * - enableListeners: Enable listeners and initialize ListenerManager
+ * - disableListeners: Disable listeners (but keep manager instance)
+ * 
+ * Required properties:
+ * - listeners: Getter for direct access to ListenerManager instance (can be null)
+ * - _listenerManager: Function accessor that returns ListenerManager or null
+ * 
+ * Custom validation:
+ * - Validates _listenerManager is a function
+ * - Validates listeners property exists
+ * - Validates _listenerManager() returns object or null
+ */
+export const listenersContract = createFacetContract({
+  name: 'listeners',
+  requiredMethods: [
+    'on',
+    'off',
+    'hasListeners',
+    'enableListeners',
+    'disableListeners'
+  ],
+  requiredProperties: [
+    'listeners',
+    '_listenerManager'
+  ],
+  validate: (ctx, api, subsystem, facet) => {
+    // Validate _listenerManager is a function
+    if (typeof facet._listenerManager !== 'function') {
+      throw new Error('Listeners facet _listenerManager must be a function');
+    }
+    
+    // Validate listeners property exists (getter)
+    if (!('listeners' in facet)) {
+      throw new Error('Listeners facet must have listeners property');
+    }
+    
+    // Validate _listenerManager() returns object or null
+    const manager = facet._listenerManager();
+    if (manager !== null && (typeof manager !== 'object' || manager === null)) {
+      throw new Error('Listeners facet _listenerManager() must return an object or null');
+    }
+  }
+});
+

package/src/contract/contracts/processor.contract.js

@@ -0,0 +1,47 @@
+/**
+ * Processor Facet Contract
+ * 
+ * Defines the contract that processor facets must satisfy.
+ * Ensures all required message processing methods are implemented.
+ * 
+ * @example
+ * import { processorContract } from './processor.contract.js';
+ * 
+ * // Enforce contract on a processor facet
+ * processorContract.enforce(ctx, api, subsystem, processorFacet);
+ */
+import { createFacetContract } from '../facet-contract.js';
+
+/**
+ * Processor Facet Contract
+ * 
+ * Required methods:
+ * - accept: Accept a message and place it on the queue (or process immediately for queries)
+ * - processMessage: Process a message through the complete processing pipeline
+ * - processTick: Process a single message from the queue (process one tick)
+ * - processImmediately: Process a message immediately without queuing
+ * 
+ * Required properties:
+ * - None (processor doesn't expose internal properties)
+ * 
+ * Custom validation:
+ * - None (methods are validated by requiredMethods check)
+ */
+export const processorContract = createFacetContract({
+  name: 'processor',
+  requiredMethods: [
+    'accept',
+    'processMessage',
+    'processTick',
+    'processImmediately'
+  ],
+  requiredProperties: [],
+  validate: null
+});
+
+
+
+
+
+
+

package/src/contract/contracts/queue.contract.js

@@ -0,0 +1,58 @@
+/**
+ * Queue Facet Contract
+ * 
+ * Defines the contract that queue facets must satisfy.
+ * Ensures all required queue methods are implemented and validates
+ * internal structure for compatibility with other hooks.
+ * 
+ * @example
+ * import { queueContract } from './queue.contract.js';
+ * 
+ * // Enforce contract on a queue facet
+ * queueContract.enforce(ctx, api, subsystem, queueFacet);
+ */
+import { createFacetContract } from '../facet-contract.js';
+
+/**
+ * Queue Facet Contract
+ * 
+ * Required methods:
+ * - selectNextMessage: Dequeue and return the next message-options pair
+ * - hasMessagesToProcess: Check if queue has messages to process
+ * - getQueueStatus: Get queue status information (size, capacity, utilization, etc.)
+ * 
+ * Required properties:
+ * - _queueManager: Internal queue manager instance (used by useMessageProcessor for enqueueing)
+ * - queue: Direct access to underlying BoundedQueue instance
+ * 
+ * Custom validation:
+ * - Validates _queueManager is an object with enqueue method
+ * - Validates queue property is an object
+ */
+export const queueContract = createFacetContract({
+  name: 'queue',
+  requiredMethods: [
+    'selectNextMessage',
+    'hasMessagesToProcess',
+    'getQueueStatus'
+  ],
+  requiredProperties: [
+    '_queueManager',
+    'queue'
+  ],
+  validate: (ctx, api, subsystem, facet) => {
+    // Validate that _queueManager is an object with enqueue method
+    if (typeof facet._queueManager !== 'object' || facet._queueManager === null) {
+      throw new Error('Queue facet _queueManager must be an object');
+    }
+    if (typeof facet._queueManager.enqueue !== 'function') {
+      throw new Error('Queue facet _queueManager must have enqueue method');
+    }
+    
+    // Validate queue property is an object
+    if (typeof facet.queue !== 'object' || facet.queue === null) {
+      throw new Error('Queue facet queue property must be an object');
+    }
+  }
+});
+

package/src/contract/contracts/router.contract.js

@@ -0,0 +1,53 @@
+/**
+ * Router Facet Contract
+ * 
+ * Defines the contract that router facets must satisfy.
+ * Ensures all required routing methods are implemented and validates
+ * internal structure for compatibility with other hooks.
+ * 
+ * @example
+ * import { routerContract } from './router.contract.js';
+ * 
+ * // Enforce contract on a router facet
+ * routerContract.enforce(ctx, api, subsystem, routerFacet);
+ */
+import { createFacetContract } from '../facet-contract.js';
+
+/**
+ * Router Facet Contract
+ * 
+ * Required methods:
+ * - registerRoute: Register a route pattern with a handler
+ * - match: Match a path against registered routes
+ * - route: Route a message by matching its path and executing the handler
+ * - unregisterRoute: Unregister a route pattern
+ * - hasRoute: Check if a route pattern is registered
+ * - getRoutes: Get all registered routes
+ * 
+ * Required properties:
+ * - _routeRegistry: Internal router instance (used by useMessageProcessor)
+ * 
+ * Custom validation:
+ * - Validates _routeRegistry is an object (not null or primitive)
+ */
+export const routerContract = createFacetContract({
+  name: 'router',
+  requiredMethods: [
+    'registerRoute',
+    'match',
+    'route',
+    'unregisterRoute',
+    'hasRoute',
+    'getRoutes'
+  ],
+  requiredProperties: [
+    '_routeRegistry'
+  ],
+  validate: (ctx, api, subsystem, facet) => {
+    // Validate that _routeRegistry is an object (not null or primitive)
+    if (typeof facet._routeRegistry !== 'object' || facet._routeRegistry === null) {
+      throw new Error('Router facet _routeRegistry must be an object');
+    }
+  }
+});
+

package/src/contract/contracts/scheduler.contract.js

@@ -0,0 +1,65 @@
+/**
+ * Scheduler Facet Contract
+ * 
+ * Defines the contract that scheduler facets must satisfy.
+ * Ensures all required scheduling methods are implemented and validates
+ * internal structure for compatibility with other hooks and BaseSubsystem.
+ * 
+ * @example
+ * import { schedulerContract } from './scheduler.contract.js';
+ * 
+ * // Enforce contract on a scheduler facet
+ * schedulerContract.enforce(ctx, api, subsystem, schedulerFacet);
+ */
+import { createFacetContract } from '../facet-contract.js';
+
+/**
+ * Scheduler Facet Contract
+ * 
+ * Required methods:
+ * - process: Process messages during a time slice
+ * - pauseProcessing: Pause message processing
+ * - resumeProcessing: Resume message processing
+ * - isPaused: Check if processing is paused
+ * - isProcessing: Check if currently processing
+ * - getPriority: Get subsystem priority
+ * - setPriority: Set subsystem priority
+ * - configureScheduler: Configure scheduler options
+ * - getScheduler: Get scheduler instance
+ * 
+ * Required properties:
+ * - _scheduler: Internal scheduler instance (used internally by other hooks)
+ * 
+ * Custom validation:
+ * - Validates _scheduler is an object (not null or primitive)
+ */
+export const schedulerContract = createFacetContract({
+  name: 'scheduler',
+  requiredMethods: [
+    'process',
+    'pauseProcessing',
+    'resumeProcessing',
+    'isPaused',
+    'isProcessing',
+    'getPriority',
+    'setPriority',
+    'configureScheduler',
+    'getScheduler'
+  ],
+  requiredProperties: [
+    '_scheduler'
+  ],
+  validate: (ctx, api, subsystem, facet) => {
+    // Validate _scheduler is an object
+    if (typeof facet._scheduler !== 'object' || facet._scheduler === null) {
+      throw new Error('Scheduler facet _scheduler must be an object');
+    }
+  }
+});
+
+
+
+
+
+
+