mycelia-kernel-plugin 1.0.0

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "mycelia-kernel-plugin",
+  "version": "1.0.0",
+  "description": "A sophisticated, dependency-aware plugin system with transaction safety and lifecycle management",
+  "license": "MIT",
+  "type": "module",
+  "author": {
+    "name": "lesfleursdelanuitdev",
+    "url": "https://github.com/lesfleursdelanuitdev"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lesfleursdelanuitdev/mycelia-kernel-plugin-system.git"
+  },
+  "homepage": "https://github.com/lesfleursdelanuitdev/mycelia-kernel-plugin-system#readme",
+  "bugs": {
+    "url": "https://github.com/lesfleursdelanuitdev/mycelia-kernel-plugin-system/issues"
+  },
+  "keywords": [
+    "plugin-system",
+    "hooks",
+    "facets",
+    "dependency-injection",
+    "lifecycle",
+    "composable",
+    "transaction-safe",
+    "dependency-resolution"
+  ],
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./core": "./src/core/index.js",
+    "./manager": "./src/manager/index.js",
+    "./builder": "./src/builder/index.js",
+    "./system": "./src/system/index.js",
+    "./contract": "./src/contract/index.js",
+    "./contract/contracts": "./src/contract/contracts/index.js"
+  },
+  "files": [
+    "src/",
+    "bin/",
+    "README.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "mycelia-kernel-plugin": "./bin/cli.js"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "test:coverage": "vitest run --coverage"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.36.0",
+    "eslint": "^9.36.0",
+    "globals": "^16.4.0",
+    "vitest": "^2.1.5"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}
+

package/src/builder/context-resolver.js

@@ -0,0 +1,62 @@
+/**
+ * Context Resolver Utilities
+ * 
+ * Handles context resolution and deep merging for subsystem building.
+ */
+
+/**
+ * Deep merge helper for objects (only merges plain objects, not arrays or other types)
+ * @param {object} target - Target object
+ * @param {object} source - Source object
+ * @returns {object} Merged object
+ */
+export function deepMerge(target, source) {
+  const result = { ...target };
+  for (const key in source) {
+    if (Object.prototype.hasOwnProperty.call(source, key)) {
+      const sourceValue = source[key];
+      const targetValue = result[key];
+      
+      // Deep merge if both are plain objects (not arrays, null, or other types)
+      if (
+        sourceValue &&
+        typeof sourceValue === 'object' &&
+        !Array.isArray(sourceValue) &&
+        targetValue &&
+        typeof targetValue === 'object' &&
+        !Array.isArray(targetValue)
+      ) {
+        result[key] = deepMerge(targetValue, sourceValue);
+      } else {
+        // Override with source value
+        result[key] = sourceValue;
+      }
+    }
+  }
+  return result;
+}
+
+/**
+ * Pure ctx resolver (verification stays side-effect free).
+ * 
+ * @param {BaseSubsystem} subsystem - Subsystem instance
+ * @param {Object} ctx - Additional context to merge
+ * @returns {Object} Resolved context object
+ */
+export function resolveCtx(subsystem, ctx) {
+  const base = (subsystem.ctx && typeof subsystem.ctx === 'object') ? subsystem.ctx : {};
+  const extra = (ctx && typeof ctx === 'object') ? ctx : {};
+  
+  // Deep merge ctx.config specifically, shallow merge everything else
+  const merged = { ...base, ...extra };
+  
+  // If both have config objects, deep merge them
+  if (base.config && typeof base.config === 'object' && 
+      extra.config && typeof extra.config === 'object' &&
+      !Array.isArray(base.config) && !Array.isArray(extra.config)) {
+    merged.config = deepMerge(base.config, extra.config);
+  }
+  
+  return merged;
+}
+

package/src/builder/dependency-graph-cache.js

@@ -0,0 +1,105 @@
+/**
+ * DependencyGraphCache Class
+ * 
+ * Bounded LRU (Least Recently Used) cache for dependency graph topological sort results.
+ * Uses Map's insertion order to track access order.
+ * 
+ * On get(): delete and re-insert to move to end (most recent)
+ * On set(): if at capacity, delete first entry (least recent)
+ * 
+ * @example
+ * const cache = new DependencyGraphCache(100);
+ * cache.set('hierarchy,listeners,processor', { valid: true, orderedKinds: [...] });
+ * const result = cache.get('hierarchy,listeners,processor');
+ */
+export class DependencyGraphCache {
+  /**
+   * Create a new DependencyGraphCache
+   * 
+   * @param {number} [capacity=100] - Maximum number of cached entries
+   */
+  constructor(capacity = 100) {
+    if (typeof capacity !== 'number' || capacity < 1) {
+      throw new Error('DependencyGraphCache: capacity must be a positive number');
+    }
+    
+    this.capacity = capacity;
+    this.cache = new Map(); // key (sorted kinds string) → { valid: boolean, orderedKinds?: string[], error?: string }
+  }
+  
+  /**
+   * Get cached result for a key (updates access order)
+   * 
+   * @param {string} key - Cache key (sorted facet kinds string)
+   * @returns {{ valid: boolean, orderedKinds?: string[], error?: string }|null} Cached result or null
+   */
+  get(key) {
+    if (!this.cache.has(key)) {
+      return null;
+    }
+    
+    // Move to end (most recently used) by deleting and re-inserting
+    const value = this.cache.get(key);
+    this.cache.delete(key);
+    this.cache.set(key, value);
+    
+    return value;
+  }
+  
+  /**
+   * Set cached result for a key
+   * 
+   * @param {string} key - Cache key (sorted facet kinds string)
+   * @param {boolean} valid - Whether the result is valid
+   * @param {string[]} [orderedKinds] - Topologically sorted kinds (if valid)
+   * @param {string} [error] - Error message (if invalid)
+   */
+  set(key, valid, orderedKinds = null, error = null) {
+    // If at capacity, remove least recently used (first entry)
+    if (this.cache.size >= this.capacity && !this.cache.has(key)) {
+      const firstKey = this.cache.keys().next().value;
+      this.cache.delete(firstKey);
+    }
+    
+    const value = {
+      valid,
+      ...(valid && orderedKinds ? { orderedKinds } : {}),
+      ...(!valid && error !== null ? { error } : {})
+    };
+    
+    // Remove existing entry if present, then add to end (most recently used)
+    if (this.cache.has(key)) {
+      this.cache.delete(key);
+    }
+    this.cache.set(key, value);
+  }
+  
+  /**
+   * Clear all cached entries
+   */
+  clear() {
+    this.cache.clear();
+  }
+  
+  /**
+   * Get current cache size
+   * 
+   * @returns {number} Number of cached entries
+   */
+  size() {
+    return this.cache.size;
+  }
+
+  /**
+   * Get cache statistics
+   * @returns {{capacity:number,size:number,keys:string[]}}
+   */
+  getStats() {
+    return {
+      capacity: this.capacity,
+      size: this.cache.size,
+      keys: Array.from(this.cache.keys())
+    };
+  }
+}
+

package/src/builder/dependency-graph.js

@@ -0,0 +1,141 @@
+/**
+ * Dependency Graph Utilities
+ * 
+ * Handles building dependency graphs and topological sorting for facet ordering.
+ */
+
+/**
+ * Create cache key from sorted facet kinds
+ * 
+ * @param {string[]} kinds - Array of facet kinds
+ * @returns {string} Cache key (sorted, comma-separated)
+ */
+export function createCacheKey(kinds) {
+  return [...kinds].sort().join(',');
+}
+
+/**
+ * Build a dependency graph from hook metadata and facet dependencies.
+ * 
+ * @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)
+ * @returns {Object} Dependency graph with { graph, indeg, kinds }
+ */
+export function buildDepGraph(hooksByKind, facetsByKind, subsystem = null) {
+  const kinds = Object.keys(facetsByKind);
+  const graph = new Map(); // dep -> Set(of dependents)
+  const indeg = new Map(); // kind -> 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
+  for (const [kind, hookList] of Object.entries(hooksByKind)) {
+    if (!Array.isArray(hookList)) continue;
+    
+    // Use the last hook's metadata for dependency graph (most recent/enhanced version)
+    // The dependency graph is for facets, not hooks, so we use the final facet's dependencies
+    const lastHook = hookList[hookList.length - 1];
+    const hookDeps = (lastHook?.required && Array.isArray(lastHook.required)) ? lastHook.required : [];
+    const hookOverwrite = lastHook?.overwrite === true;
+    
+    for (const dep of hookDeps) {
+      // 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) {
+        // Still validate that the facet exists (the overwrite hook needs it)
+        if (!facetsByKind[dep]) {
+          const src = lastHook?.source || kind;
+          throw new Error(`Hook '${kind}' (from ${src}) requires missing facet '${dep}'.`);
+        }
+        // But don't add the dependency edge (no cycle in facet graph)
+        continue;
+      }
+      if (!facetsByKind[dep]) {
+        const src = lastHook?.source || kind;
+        throw new Error(`Hook '${kind}' (from ${src}) requires missing facet '${dep}'.`);
+      }
+      if (!graph.get(dep).has(kind)) {
+        graph.get(dep).add(kind);
+        indeg.set(kind, (indeg.get(kind) || 0) + 1);
+      }
+    }
+  }
+
+  // Then, add dependencies from facet metadata (facet.getDependencies())
+  for (const [kind, facet] of Object.entries(facetsByKind)) {
+    const facetDeps = (typeof facet.getDependencies === 'function' && facet.getDependencies()) || [];
+    for (const dep of facetDeps) {
+      if (!facetsByKind[dep]) {
+        const src = facet.getSource?.() || kind;
+        throw new Error(`Facet '${kind}' (from ${src}) depends on missing '${dep}'.`);
+      }
+      if (!graph.get(dep).has(kind)) {
+        graph.get(dep).add(kind);
+        indeg.set(kind, (indeg.get(kind) || 0) + 1);
+      }
+    }
+  }
+
+  return { graph, indeg, kinds };
+}
+
+/**
+ * Kahn topological sort with diagnostics and caching.
+ * 
+ * @param {Object} graphData - Dependency graph data { graph, indeg, kinds }
+ * @param {DependencyGraphCache} graphCache - Optional cache for storing results
+ * @param {string} cacheKey - Optional cache key
+ * @returns {string[]} Ordered array of facet kinds
+ * @throws {Error} If a dependency cycle is detected
+ */
+export function topoSort({ graph, indeg, kinds }, graphCache = null, cacheKey = null) {
+  // Check cache if provided
+  if (graphCache && cacheKey) {
+    const cached = graphCache.get(cacheKey);
+    if (cached) {
+      if (cached.valid) {
+        return cached.orderedKinds;
+      } else {
+        throw new Error(cached.error || 'Cached dependency graph error');
+      }
+    }
+  }
+
+  const q = [];
+  for (const k of kinds) if ((indeg.get(k) || 0) === 0) q.push(k);
+
+  const ordered = [];
+  while (q.length) {
+    const n = q.shift();
+    ordered.push(n);
+    for (const m of graph.get(n)) {
+      indeg.set(m, indeg.get(m) - 1);
+      if (indeg.get(m) === 0) q.push(m);
+    }
+  }
+
+  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
+    if (graphCache && cacheKey) {
+      graphCache.set(cacheKey, false, null, error);
+    }
+    
+    throw new Error(error);
+  }
+
+  // Cache valid result
+  if (graphCache && cacheKey) {
+    graphCache.set(cacheKey, true, ordered, null);
+  }
+
+  return ordered;
+}
+

package/src/builder/facet-validator.js

@@ -0,0 +1,43 @@
+/**
+ * Facet Validator Utilities
+ * 
+ * Handles validation of facets against their contracts.
+ */
+
+/**
+ * Validate facets against their contracts
+ * 
+ * Iterates through all collected facets and enforces their contracts if they have one.
+ * Throws immediately if any contract validation fails.
+ * 
+ * @param {Object} facetsByKind - Object mapping facet kinds to Facet instances
+ * @param {Object} resolvedCtx - Resolved context object
+ * @param {BaseSubsystem} subsystem - Subsystem instance
+ * @param {FacetContractRegistry} contractRegistry - Contract registry to use for validation
+ * @throws {Error} If a facet has a contract that doesn't exist in the registry, or if contract enforcement fails
+ */
+export function validateFacets(facetsByKind, resolvedCtx, subsystem, contractRegistry) {
+  for (const [kind, facet] of Object.entries(facetsByKind)) {
+    const contractName = facet.getContract?.();
+    
+    // Skip if facet has no contract
+    if (!contractName || typeof contractName !== 'string' || !contractName.trim()) {
+      continue;
+    }
+    
+    // Check if contract exists in registry
+    if (!contractRegistry.has(contractName)) {
+      const facetSource = facet.getSource?.() || '<unknown>';
+      throw new Error(`Facet '${kind}' (from ${facetSource}) has contract '${contractName}' which is not registered in the contract registry.`);
+    }
+    
+    // Enforce the contract (will throw if validation fails)
+    try {
+      contractRegistry.enforce(contractName, resolvedCtx, subsystem.api, subsystem, facet);
+    } catch (error) {
+      const facetSource = facet.getSource?.() || '<unknown>';
+      throw new Error(`Facet '${kind}' (from ${facetSource}) failed contract validation for '${contractName}': ${error.message}`);
+    }
+  }
+}
+

package/src/builder/hook-processor.js

@@ -0,0 +1,271 @@
+/**
+ * Hook Processor Utilities
+ * 
+ * Handles hook ordering, execution, and facet creation during subsystem verification.
+ */
+
+import { Facet } from '../core/facet.js';
+
+/**
+ * Order hooks based on their dependencies using topological sort.
+ * 
+ * Handles multiple hooks per kind by assigning unique IDs and creating
+ * dependencies between overwrite hooks and their predecessors.
+ * 
+ * @param {Array} hooks - Array of hook functions
+ * @returns {Array} Ordered array of hooks
+ */
+export function orderHooksByDependencies(hooks) {
+  // Extract hook metadata (now returns arrays per kind)
+  const hooksByKind = extractHookMetadata(hooks);
+  
+  // Flatten to get all hooks with unique IDs
+  const hookArray = [];
+  const hookIdMap = new Map(); // hookId -> { hook, kind, required, overwrite, index }
+  const kindToHookIds = new Map(); // kind -> [hookId1, hookId2, ...]
+  
+  // Assign unique IDs to each hook
+  for (const [kind, hookList] of Object.entries(hooksByKind)) {
+    const hookIds = [];
+    for (const hookMeta of hookList) {
+      const hookId = `${kind}:${hookMeta.index}`; // e.g., "router:0", "router:1"
+      hookArray.push({
+        hookId,
+        hook: hookMeta.hook,
+        kind,
+        required: hookMeta.required,
+        overwrite: hookMeta.overwrite,
+        index: hookMeta.index
+      });
+      hookIdMap.set(hookId, hookArray[hookArray.length - 1]);
+      hookIds.push(hookId);
+    }
+    kindToHookIds.set(kind, hookIds);
+  }
+
+  // Build dependency graph using hook IDs
+  const hookDepGraph = new Map(); // hookId -> Set(dependent hookIds)
+  const hookIndeg = new Map(); // hookId -> indegree
+  
+  // Initialize graph
+  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
+  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)
+        continue;
+      }
+      
+      // 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)
+        if (index > 0) {
+          const previousHookId = `${kind}:${index - 1}`;
+          if (hookIdMap.has(previousHookId)) {
+            // Overwrite hook depends on the previous hook of same kind
+            hookDepGraph.get(previousHookId).add(hookId);
+            hookIndeg.set(hookId, (hookIndeg.get(hookId) || 0) + 1);
+          }
+        }
+        continue; // Skip adding other dependencies for self-kind
+      }
+      
+      // For other dependencies, depend on the LAST hook that creates that kind
+      // (the most recent/enhanced version)
+      if (depHookIds.length > 0) {
+        const lastDepHookId = depHookIds[depHookIds.length - 1];
+        hookDepGraph.get(lastDepHookId).add(hookId);
+        hookIndeg.set(hookId, (hookIndeg.get(hookId) || 0) + 1);
+      }
+    }
+  }
+  
+  // Topological sort on hook IDs
+  const orderedHookIds = [];
+  const queue = [];
+  for (const { hookId } of hookArray) {
+    if (hookIndeg.get(hookId) === 0) {
+      queue.push(hookId);
+    }
+  }
+  
+  while (queue.length > 0) {
+    const hookId = queue.shift();
+    orderedHookIds.push(hookId);
+    
+    for (const dependent of hookDepGraph.get(hookId)) {
+      const newIndeg = hookIndeg.get(dependent) - 1;
+      hookIndeg.set(dependent, newIndeg);
+      if (newIndeg === 0) {
+        queue.push(dependent);
+      }
+    }
+  }
+  
+  // Build ordered hooks array
+  const orderedHooks = [];
+  for (const hookId of orderedHookIds) {
+    orderedHooks.push(hookIdMap.get(hookId).hook);
+  }
+  
+  // Add any hooks that weren't in the dependency graph (shouldn't happen, but safety)
+  for (const { hookId, hook } of hookArray) {
+    if (!orderedHookIds.includes(hookId)) {
+      orderedHooks.push(hook);
+    }
+  }
+
+  return orderedHooks;
+}
+
+/**
+ * Execute hooks and create facets.
+ * 
+ * @param {Array} orderedHooks - Ordered array of hooks to execute
+ * @param {Object} resolvedCtx - Resolved context object
+ * @param {BaseSubsystem} subsystem - Subsystem instance
+ * @param {Object} hooksByKind - Object mapping hook kinds to hook metadata
+ * @returns {Object} Object with { facetsByKind, hooksByKind }
+ */
+export function executeHooksAndCreateFacets(orderedHooks, resolvedCtx, subsystem, hooksByKind) {
+  const facetsByKind = Object.create(null);
+
+  // Execute hooks in dependency order and create facets
+  for (const hook of orderedHooks) {
+    if (typeof hook !== 'function') continue;
+
+    const hookKind = hook.kind;
+    const hookSource = hook.source || '<unknown>';
+
+    let facet;
+    try {
+      facet = hook(resolvedCtx, subsystem.api, subsystem);
+    } catch (error) {
+      throw new Error(`Hook '${hookKind}' (from ${hookSource}) failed during execution: ${error.message}`);
+    }
+
+    if (!facet) continue;
+
+    if (!(facet instanceof Facet)) {
+      throw new Error(`Hook '${hookKind}' (from ${hookSource}) did not return a Facet instance (got ${typeof facet}).`);
+    }
+
+    const facetKind = facet.getKind?.();
+    if (!facetKind || typeof facetKind !== 'string') {
+      const facetSrc = facet.getSource?.() || '<unknown>';
+      throw new Error(`Facet from hook '${hookKind}' (source: ${hookSource}) missing valid kind (facet source: ${facetSrc}).`);
+    }
+
+    // Validate hook.kind matches facet.kind
+    if (hookKind !== facetKind) {
+      throw new Error(`Hook '${hookKind}' (from ${hookSource}) returned facet with mismatched kind '${facetKind}'.`);
+    }
+
+    // Check overwrite permission (also check facet.shouldOverwrite for consistency)
+    if (facetsByKind[facetKind]) {
+      // Get overwrite permission from the current hook (not stored metadata)
+      const currentHookOverwrite = hook.overwrite === true;
+      const facetOverwrite = facet.shouldOverwrite?.() === true;
+      if (!currentHookOverwrite && !facetOverwrite) {
+        const prevSrc = facetsByKind[facetKind].getSource?.() || facetKind;
+        throw new Error(`Duplicate facet kind '${facetKind}' from [${prevSrc}] and [${hookSource}]. Neither hook nor facet allows overwrite.`);
+      }
+      // Allow overwrite - replace the existing facet
+      facetsByKind[facetKind] = facet;
+    } else {
+      facetsByKind[facetKind] = facet;
+    }
+    
+    // Make facet available in api.__facets during verification so later hooks can access it via subsystem.find()
+    // This is a temporary registration - facets will be properly added/initialized/attached in buildSubsystem
+    if (subsystem.api && subsystem.api.__facets) {
+      // Use the Proxy setter to add the facet temporarily (without init/attach)
+      subsystem.api.__facets[facetKind] = facet;
+    }
+  }
+
+  return { facetsByKind };
+}
+
+/**
+ * Extract hook metadata from hooks array.
+ * 
+ * Stores multiple hooks per kind in registration order (arrays).
+ * This allows overwrite hooks to depend on previous hooks of the same kind.
+ * 
+ * @param {Array} hooks - Array of hook functions
+ * @returns {Object} Object mapping hook kinds to arrays of hook metadata
+ *   Each entry: { hook, required, source, overwrite, version, index }
+ */
+export function extractHookMetadata(hooks) {
+  const hooksByKind = Object.create(null);
+
+  for (const hook of hooks) {
+    if (typeof hook !== 'function') continue;
+
+    const hookKind = hook.kind;
+    const hookVersion = hook.version || '0.0.0';
+    const hookOverwrite = hook.overwrite === true;
+    const hookRequired = (hook.required && Array.isArray(hook.required)) ? hook.required : [];
+    const hookSource = hook.source || '<unknown>';
+
+    if (!hookKind || typeof hookKind !== 'string') {
+      throw new Error(`Hook missing valid kind property (source: ${hookSource}).`);
+    }
+
+    // Store array of hooks per kind, maintaining registration order
+    if (!hooksByKind[hookKind]) {
+      hooksByKind[hookKind] = [];
+    }
+    
+    hooksByKind[hookKind].push({
+      hook,  // Store the actual hook function
+      required: hookRequired,
+      source: hookSource,
+      overwrite: hookOverwrite,
+      version: hookVersion,
+      index: hooksByKind[hookKind].length  // Track position in array
+    });
+  }
+
+  return hooksByKind;
+}
+
+/**
+ * Validate hook.required dependencies exist.
+ * 
+ * @param {Object} hooksByKind - Object mapping hook kinds to arrays of hook metadata
+ * @param {Object} facetsByKind - Object mapping facet kinds to Facet instances
+ * @param {BaseSubsystem} subsystem - Subsystem instance (optional, for future use)
+ */
+export function validateHookDependencies(hooksByKind, facetsByKind, subsystem) {
+  for (const [kind, hookList] of Object.entries(hooksByKind)) {
+    if (!Array.isArray(hookList)) continue;
+    
+    for (const hookMeta of hookList) {
+      for (const dep of hookMeta.required) {
+        // For self-dependency (overwrite hooks requiring their own kind),
+        // check if there's a previous hook of that kind
+        if (dep === kind && hookMeta.overwrite) {
+          // Check if there's a previous hook (index > 0 means there's a predecessor)
+          if (hookMeta.index === 0) {
+            throw new Error(`Hook '${kind}' (from ${hookMeta.source}) requires '${dep}' but is the first hook of that kind. Overwrite hooks must come after the hook they overwrite.`);
+          }
+          // Previous hook exists, dependency is satisfied
+          continue;
+        }
+        if (!facetsByKind[dep]) {
+          throw new Error(`Hook '${kind}' (from ${hookMeta.source}) requires missing facet '${dep}'.`);
+        }
+      }
+    }
+  }
+}
+

package/src/builder/index.js

@@ -0,0 +1,13 @@
+export { SubsystemBuilder } from './subsystem-builder.js';
+export { DependencyGraphCache } from './dependency-graph-cache.js';
+export { buildDepGraph, topoSort, createCacheKey } from './dependency-graph.js';
+export { validateFacets } from './facet-validator.js';
+export { resolveCtx, deepMerge } from './context-resolver.js';
+export { 
+  extractHookMetadata,
+  orderHooksByDependencies,
+  executeHooksAndCreateFacets,
+  validateHookDependencies
+} from './hook-processor.js';
+export { verifySubsystemBuild, buildSubsystem, deepMerge as deepMergeUtils } from './utils.js';
+