mycelia-kernel-plugin 1.0.0

package/src/hooks/queue/circular-buffer.js

@@ -0,0 +1,231 @@
+/**
+ * CircularBuffer Class
+ * 
+ * A high-performance circular buffer implementation for O(1) enqueue/dequeue operations.
+ * Replaces array-based queue to eliminate O(n) Array.shift() overhead.
+ * 
+ * Performance improvements over array-based queue:
+ * - Enqueue: O(1) vs O(1) (same)
+ * - Dequeue: O(1) vs O(n) (10-100x faster for large queues)
+ * - Memory: Predictable vs variable (better for GC)
+ * - Cache: Better locality vs scattered
+ * 
+ * @example
+ * // Create buffer with capacity 1000
+ * const buffer = new CircularBuffer(1000);
+ * 
+ * @example
+ * // Use buffer
+ * buffer.enqueue({ msg: message, options: {} });
+ * const item = buffer.dequeue();
+ * 
+ * @example
+ * // Check status
+ * console.log('Full:', buffer.isFull());
+ * console.log('Size:', buffer.size());
+ */
+export class CircularBuffer {
+  /**
+   * Create a new CircularBuffer instance
+   * 
+   * @param {number} capacity - Maximum number of items the buffer can hold
+   * 
+   * @example
+   * const buffer = new CircularBuffer(1000);
+   */
+  constructor(capacity) {
+    if (!capacity || capacity <= 0) {
+      throw new Error('CircularBuffer: capacity must be positive');
+    }
+    
+    this.capacity = capacity;
+    this.buffer = new Array(capacity);
+    this.head = 0;  // Read position
+    this.tail = 0;  // Write position
+    this._size = 0; // Current number of items
+  }
+  
+  /**
+   * Add an item to the buffer
+   * 
+   * Time complexity: O(1)
+   * 
+   * @param {any} item - Item to enqueue
+   * @returns {boolean} True if successfully enqueued, false if buffer is full
+   * 
+   * @example
+   * const success = buffer.enqueue({ msg: message, options: {} });
+   * if (!success) {
+   *   console.log('Buffer is full');
+   * }
+   */
+  enqueue(item) {
+    if (this.isFull()) {
+      return false;
+    }
+    
+    this.buffer[this.tail] = item;
+    this.tail = (this.tail + 1) % this.capacity;
+    this._size++;
+    return true;
+  }
+  
+  /**
+   * Remove and return the oldest item from the buffer
+   * 
+   * Time complexity: O(1)
+   * 
+   * @returns {any|null} The oldest item, or null if buffer is empty
+   * 
+   * @example
+   * const item = buffer.dequeue();
+   * if (item) {
+   *   console.log('Got item:', item);
+   * }
+   */
+  dequeue() {
+    if (this.isEmpty()) {
+      return null;
+    }
+    
+    const item = this.buffer[this.head];
+    this.buffer[this.head] = null; // Allow garbage collection
+    this.head = (this.head + 1) % this.capacity;
+    this._size--;
+    return item;
+  }
+  
+  /**
+   * Remove the oldest item without returning it (for drop-oldest policy)
+   * 
+   * Time complexity: O(1)
+   * 
+   * @returns {boolean} True if item was dropped, false if buffer was empty
+   * 
+   * @example
+   * if (buffer.isFull()) {
+   *   buffer.dropOldest();
+   *   buffer.enqueue(newItem);
+   * }
+   */
+  dropOldest() {
+    if (this.isEmpty()) {
+      return false;
+    }
+    
+    this.buffer[this.head] = null; // Allow garbage collection
+    this.head = (this.head + 1) % this.capacity;
+    this._size--;
+    return true;
+  }
+  
+  /**
+   * Peek at the oldest item without removing it
+   * 
+   * Time complexity: O(1)
+   * 
+   * @returns {any|null} The oldest item, or null if buffer is empty
+   * 
+   * @example
+   * const next = buffer.peek();
+   * console.log('Next item:', next);
+   */
+  peek() {
+    if (this.isEmpty()) {
+      return null;
+    }
+    return this.buffer[this.head];
+  }
+  
+  /**
+   * Check if buffer is full
+   * 
+   * @returns {boolean} True if buffer is at capacity
+   */
+  isFull() {
+    return this._size === this.capacity;
+  }
+  
+  /**
+   * Check if buffer is empty
+   * 
+   * @returns {boolean} True if buffer has no items
+   */
+  isEmpty() {
+    return this._size === 0;
+  }
+  
+  /**
+   * Get current number of items in buffer
+   * 
+   * @returns {number} Number of items
+   */
+  size() {
+    return this._size;
+  }
+  
+  /**
+   * Get buffer capacity
+   * 
+   * @returns {number} Maximum capacity
+   */
+  getCapacity() {
+    return this.capacity;
+  }
+  
+  /**
+   * Clear all items from buffer
+   * 
+   * Time complexity: O(n) - must clear references for GC
+   * 
+   * @example
+   * buffer.clear();
+   * console.log('Size:', buffer.size()); // 0
+   */
+  clear() {
+    // Clear references to allow garbage collection
+    for (let i = 0; i < this.capacity; i++) {
+      this.buffer[i] = null;
+    }
+    this.head = 0;
+    this.tail = 0;
+    this._size = 0;
+  }
+  
+  /**
+   * Convert buffer to array (for debugging/inspection)
+   * 
+   * Time complexity: O(n)
+   * 
+   * @returns {Array} Array of items in order (oldest to newest)
+   * 
+   * @example
+   * console.log('Items:', buffer.toArray());
+   */
+  toArray() {
+    const result = [];
+    let count = this._size;
+    let index = this.head;
+    
+    while (count > 0) {
+      result.push(this.buffer[index]);
+      index = (index + 1) % this.capacity;
+      count--;
+    }
+    
+    return result;
+  }
+  
+  /**
+   * Get utilization percentage
+   * 
+   * @returns {number} Percentage full (0-100)
+   * 
+   * @example
+   * console.log('Buffer is', buffer.utilization(), '% full');
+   */
+  utilization() {
+    return (this._size / this.capacity) * 100;
+  }
+}
+

package/src/hooks/queue/subsystem-queue-manager.js

@@ -0,0 +1,198 @@
+/**
+ * SubsystemQueueManager Class
+ * 
+ * Manages the message queue for a subsystem. Handles queue initialization,
+ * operations (enqueue, dequeue, clear), status queries, and statistics.
+ * 
+ * This class isolates queue management concerns from BaseSubsystem,
+ * providing a clean interface for queue operations.
+ * 
+ * @example
+ * // Created internally by BaseSubsystem
+ * const queueManager = new SubsystemQueueManager({
+ *   capacity: 1000,
+ *   policy: 'drop-oldest',
+ *   debug: true,
+ *   subsystemName: 'canvas',
+ *   onQueueFull: () => statistics.recordQueueFull()
+ * });
+ * 
+ * // Enqueue a message
+ * const success = queueManager.enqueue({ msg: message, options: {} });
+ * 
+ * // Get queue status
+ * const status = queueManager.getStatus();
+ * 
+ * // Dequeue next message
+ * const next = queueManager.dequeue();
+ */
+import { BoundedQueue } from './bounded-queue.js';
+
+export class SubsystemQueueManager {
+  /**
+   * Create a new SubsystemQueueManager instance
+   * 
+   * @param {Object} options - Configuration options
+   * @param {number} [options.capacity=1000] - Queue capacity
+   * @param {string} [options.policy='drop-oldest'] - Queue overflow policy
+   * @param {boolean} [options.debug=false] - Enable debug logging
+   * @param {string} options.subsystemName - Subsystem name for logging
+   * @param {Function} [options.onQueueFull] - Callback when queue becomes full: () => void
+   * 
+   * @example
+   * const queueManager = new SubsystemQueueManager({
+   *   capacity: 2000,
+   *   policy: 'drop-oldest',
+   *   debug: true,
+   *   subsystemName: 'canvas',
+   *   onQueueFull: () => console.log('Queue is full!')
+   * });
+   */
+  constructor(options) {
+    if (!options.subsystemName || typeof options.subsystemName !== 'string') {
+      throw new Error('SubsystemQueueManager: subsystemName is required');
+    }
+    
+    this.subsystemName = options.subsystemName;
+    this.debug = options.debug || false;
+    
+    // Initialize bounded queue
+    this.queue = new BoundedQueue(
+      options.capacity || 1000,
+      options.policy || 'drop-oldest'
+    );
+    
+    // Set queue debug mode
+    this.queue.setDebug(this.debug);
+    
+    // Listen to queue full events
+    if (options.onQueueFull) {
+      this.queue.on('full', options.onQueueFull);
+    }
+    
+    if (this.debug) {
+      console.log(`SubsystemQueueManager ${this.subsystemName}: Initialized with capacity ${this.queue.getCapacity()}`);
+    }
+  }
+
+  /**
+   * Enqueue a message-options pair
+   * 
+   * @param {{msg: Message, options: Object}} pair - Message-options pair to enqueue
+   * @returns {boolean} True if successfully enqueued
+   * 
+   * @example
+   * const success = queueManager.enqueue({ msg: message, options: {} });
+   */
+  enqueue(pair) {
+    return this.queue.enqueue(pair);
+  }
+
+  /**
+   * Dequeue the next message-options pair
+   * 
+   * @returns {{msg: Message, options: Object}|null} Next pair or null if empty
+   * 
+   * @example
+   * const next = queueManager.dequeue();
+   * if (next) {
+   *   const { msg, options } = next;
+   * }
+   */
+  dequeue() {
+    return this.queue.dequeue();
+  }
+
+  /**
+   * Get current queue size
+   * 
+   * @returns {number} Number of messages in queue
+   */
+  size() {
+    return this.queue.size();
+  }
+
+  /**
+   * Get queue capacity
+   * 
+   * @returns {number} Maximum queue capacity
+   */
+  getCapacity() {
+    return this.queue.getCapacity();
+  }
+
+  /**
+   * Check if queue is empty
+   * 
+   * @returns {boolean} True if queue is empty
+   */
+  isEmpty() {
+    return this.queue.isEmpty();
+  }
+
+  /**
+   * Check if queue is full
+   * 
+   * @returns {boolean} True if queue is full
+   */
+  isFull() {
+    return this.queue.isFull();
+  }
+
+  /**
+   * Clear all messages from the queue
+   * 
+   * @example
+   * queueManager.clear();
+   */
+  clear() {
+    this.queue.clear();
+    if (this.debug) {
+      console.log(`SubsystemQueueManager ${this.subsystemName}: Queue cleared`);
+    }
+  }
+
+  /**
+   * Get queue status information
+   * 
+   * @param {Object} [additionalState={}] - Additional state to include (e.g., isProcessing, isPaused)
+   * @returns {Object} Queue status object
+   * 
+   * @example
+   * const status = queueManager.getStatus({ isProcessing: true, isPaused: false });
+   * // Returns: { size, capacity, utilization, isEmpty, isFull, isProcessing, isPaused }
+   */
+  getStatus(additionalState = {}) {
+    const size = this.queue.size();
+    const capacity = this.queue.getCapacity();
+    
+    return {
+      size,
+      capacity,
+      utilization: size / capacity,
+      isEmpty: this.queue.isEmpty(),
+      isFull: this.queue.isFull(),
+      ...additionalState
+    };
+  }
+
+  /**
+   * Get queue statistics
+   * 
+   * @returns {Object} Queue statistics from underlying BoundedQueue
+   */
+  getStatistics() {
+    return this.queue.getStatistics();
+  }
+
+  /**
+   * Get the underlying BoundedQueue instance
+   * (for direct access when needed)
+   * 
+   * @returns {BoundedQueue} The underlying queue instance
+   */
+  getQueue() {
+    return this.queue;
+  }
+}
+

package/src/hooks/queue/use-queue.js

@@ -0,0 +1,96 @@
+/**
+ * useQueue Hook
+ * 
+ * Provides queue management functionality to subsystems.
+ * Wraps SubsystemQueueManager and exposes queue operations.
+ * 
+ * @param {Object} ctx - Context object containing config.queue for queue configuration
+ * @param {Object} api - Subsystem API being built
+ * @param {BaseSubsystem} subsystem - Subsystem instance
+ * @returns {Facet} Facet object with queue methods
+ */
+import { SubsystemQueueManager } from './subsystem-queue-manager.js';
+import { Facet } from '../../core/facet.js';
+import { createHook } from '../../core/create-hook.js';
+import { getDebugFlag } from '../../utils/debug-flag.js';
+import { findFacet } from '../../utils/find-facet.js';
+
+export const useQueue = createHook({
+  kind: 'queue',
+  version: '1.0.0',
+  overwrite: false,
+  required: [], // statistics is optional, not required
+  attach: true,
+  source: import.meta.url,
+  contract: 'queue',
+  // eslint-disable-next-line no-unused-vars
+  fn: (ctx, api, _subsystem) => {
+    const { name } = api;
+    const config = ctx.config?.queue || {};
+    
+    // Get statistics hook if available (for onQueueFull callback)
+    const statisticsResult = findFacet(api.__facets, 'statistics');
+    const statisticsFacet = statisticsResult ? statisticsResult.facet : null;
+    
+    // Create queue manager
+    const queueManager = new SubsystemQueueManager({
+      capacity: config.capacity || 1000,
+      policy: config.policy || 'drop-oldest',
+      debug: getDebugFlag(config, ctx),
+      subsystemName: name,
+      onQueueFull: () => {
+        if (statisticsFacet?._statistics) {
+          statisticsFacet._statistics.recordQueueFull();
+        }
+      }
+    });
+    
+    // Get underlying queue for direct access
+    const queue = queueManager.getQueue();
+    
+    return new Facet('queue', { attach: true, source: import.meta.url, contract: 'queue' })
+    .add({
+      /**
+       * Get queue status
+       * @param {Object} [additionalState={}] - Additional state (e.g., isProcessing, isPaused)
+       * @returns {Object} Queue status object
+       */
+      getQueueStatus(additionalState = {}) {
+        return queueManager.getStatus(additionalState);
+      },
+      
+      /**
+       * Expose queue property for direct access
+       * Must have .capacity and methods like .remove()
+       */
+      queue,
+      
+      /**
+       * Clear all messages from the queue
+       */
+      clearQueue() {
+        queueManager.clear();
+      },
+      
+      /**
+       * Check if queue has messages to process
+       * @returns {boolean} True if queue has messages
+       */
+      hasMessagesToProcess() {
+        return !queueManager.isEmpty();
+      },
+      
+      /**
+       * Select next message to process
+       * @returns {{msg: Message, options: Object}|null} Message-options pair or null
+       */
+      selectNextMessage() {
+        return queueManager.dequeue();
+      },
+      
+      // Expose queue manager for internal use by other hooks
+      _queueManager: queueManager
+    });
+  }
+});
+

package/src/hooks/speak/use-speak.js

@@ -0,0 +1,79 @@
+/**
+ * useSpeak Hook
+ * 
+ * Provides speaking/printing functionality to subsystems.
+ * A simple "hello world" example hook that implements the speak contract.
+ * 
+ * @param {Object} ctx - Context object containing config.speak for speak configuration
+ * @param {Object} api - Subsystem API being built
+ * @param {BaseSubsystem} subsystem - Subsystem instance
+ * @returns {Facet} Facet object with speak methods
+ */
+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 useSpeak = createHook({
+  kind: 'speak',
+  version: '1.0.0',
+  overwrite: false,
+  required: [],
+  attach: true,
+  source: import.meta.url,
+  contract: 'speak',
+  // eslint-disable-next-line no-unused-vars
+  fn: (ctx, api, _subsystem) => {
+    const { name } = api;
+    const config = ctx.config?.speak || {};
+    const debug = getDebugFlag(config, ctx);
+    const logger = createLogger(debug, `useSpeak ${name}`);
+    
+    // Default output function (can be overridden via config)
+    const outputFn = config.output || console.log;
+    const prefix = config.prefix || '';
+    
+    return new Facet('speak', { attach: true, source: import.meta.url, contract: 'speak' })
+      .add({
+        /**
+         * Say a message (without newline)
+         * @param {string} message - Message to say
+         * @returns {void}
+         * 
+         * @example
+         * subsystem.speak.say('Hello');
+         * subsystem.speak.say(' World');
+         * // Output: "Hello World"
+         */
+        say(message) {
+          if (typeof message !== 'string') {
+            throw new Error('speak.say() requires a string message');
+          }
+          outputFn(prefix + message);
+          if (debug) {
+            logger.log(`Said: ${message}`);
+          }
+        },
+        
+        /**
+         * Say a message with a newline
+         * @param {string} message - Message to say
+         * @returns {void}
+         * 
+         * @example
+         * subsystem.speak.sayLine('Hello, World!');
+         * // Output: "Hello, World!\n"
+         */
+        sayLine(message) {
+          if (typeof message !== 'string') {
+            throw new Error('speak.sayLine() requires a string message');
+          }
+          outputFn(prefix + message);
+          if (debug) {
+            logger.log(`Said line: ${message}`);
+          }
+        }
+      });
+  }
+});
+

package/src/index.js

@@ -0,0 +1,49 @@
+/**
+ * Mycelia Plugin System
+ * 
+ * Main entry point for the plugin system.
+ * Exports all core classes, hooks, and utilities.
+ */
+
+// Core exports
+export { createHook } from './core/create-hook.js';
+export { Facet } from './core/facet.js';
+
+// Manager exports
+export { FacetManager } from './manager/facet-manager.js';
+export { FacetManagerTransaction } from './manager/facet-manager-transaction.js';
+
+// Builder exports
+export { SubsystemBuilder } from './builder/subsystem-builder.js';
+export { DependencyGraphCache } from './builder/dependency-graph-cache.js';
+
+// System exports
+export { BaseSubsystem } from './system/base-subsystem.js';
+export { StandalonePluginSystem } from './system/standalone-plugin-system.js';
+export { collectChildren, buildChildren, disposeChildren } from './system/base-subsystem.utils.js';
+
+// Contract exports
+export { FacetContract, createFacetContract } from './contract/facet-contract.js';
+export { FacetContractRegistry, defaultContractRegistry } from './contract/index.js';
+
+// Export all contracts
+export * from './contract/contracts/index.js';
+
+// Hook exports
+export { useListeners } from './hooks/listeners/use-listeners.js';
+export { useQueue } from './hooks/queue/use-queue.js';
+export { useSpeak } from './hooks/speak/use-speak.js';
+
+// Utility exports
+export { createLogger, createSubsystemLogger } from './utils/logger.js';
+export { getDebugFlag } from './utils/debug-flag.js';
+export { findFacet } from './utils/find-facet.js';
+export { 
+  parseVersion, 
+  isValidSemver, 
+  compareVersions, 
+  satisfiesRange, 
+  getDefaultVersion, 
+  validateVersion 
+} from './utils/semver.js';
+

package/src/manager/facet-manager-transaction.js

@@ -0,0 +1,45 @@
+export class FacetManagerTransaction {
+  #txnStack = []; // tracks nested transaction frames
+  #facetManager;
+  #subsystem;
+
+  constructor(facetManager, subsystem) {
+    this.#facetManager = facetManager;
+    this.#subsystem = subsystem;
+  }
+
+  /** Begin a transaction frame */
+  beginTransaction() {
+    this.#txnStack.push({ added: [] });
+  }
+
+  /** Commit current transaction frame */
+  commit() {
+    if (!this.#txnStack.length) throw new Error('FacetManagerTransaction.commit: no active transaction');
+    this.#txnStack.pop();
+  }
+
+  /** Roll back current transaction frame: dispose + remove in reverse add order */
+  async rollback() {
+    if (!this.#txnStack.length) throw new Error('FacetManagerTransaction.rollback: no active transaction');
+    const frame = this.#txnStack.pop();
+    for (let i = frame.added.length - 1; i >= 0; i--) {
+      const k = frame.added[i];
+      const facet = this.#facetManager.find(k);
+      try { facet?.dispose?.(this.#subsystem); } catch { /* best-effort disposal */ }
+      this.#facetManager.remove(k);
+    }
+  }
+
+  /** Track addition in current transaction frame */
+  trackAddition(kind) {
+    const frame = this.#txnStack[this.#txnStack.length - 1];
+    if (frame) frame.added.push(kind);
+  }
+
+  /** Check if there's an active transaction */
+  hasActiveTransaction() {
+    return this.#txnStack.length > 0;
+  }
+}
+