trellis 2.0.8 → 2.0.13

package/src/core/plugins/registry.ts

@@ -0,0 +1,322 @@
+/**
+ * Plugin Registry — Load, register, and manage plugins.
+ *
+ * Handles plugin lifecycle, dependency resolution, event dispatching,
+ * and workspace configuration.
+ *
+ * @module trellis/core/plugins
+ */
+
+import type { TrellisKernel } from '../kernel/trellis-kernel.js';
+import type { OntologyRegistry } from '../ontology/registry.js';
+import type { QueryEngine } from '../query/engine.js';
+import type {
+  PluginDef,
+  PluginContext,
+  PluginManifest,
+  EventCallback,
+  EventHandler,
+  WorkspaceConfig,
+} from './types.js';
+
+// ---------------------------------------------------------------------------
+// Event Bus
+// ---------------------------------------------------------------------------
+
+export class EventBus {
+  private handlers: Map<string, Set<EventCallback>> = new Map();
+
+  on(event: string, handler: EventCallback): void {
+    const set = this.handlers.get(event) ?? new Set();
+    set.add(handler);
+    this.handlers.set(event, set);
+  }
+
+  off(event: string, handler: EventCallback): void {
+    const set = this.handlers.get(event);
+    if (set) {
+      set.delete(handler);
+      if (set.size === 0) this.handlers.delete(event);
+    }
+  }
+
+  async emit(event: string, data?: unknown): Promise<void> {
+    // Exact match
+    const exact = this.handlers.get(event);
+    if (exact) {
+      for (const h of exact) await h(data);
+    }
+
+    // Wildcard match (e.g. "op:*" matches "op:applied")
+    for (const [pattern, handlers] of this.handlers) {
+      if (pattern === event) continue; // Already handled
+      if (pattern.endsWith('*') && event.startsWith(pattern.slice(0, -1))) {
+        for (const h of handlers) await h(data);
+      }
+    }
+  }
+
+  listEvents(): string[] {
+    return [...this.handlers.keys()];
+  }
+
+  clear(): void {
+    this.handlers.clear();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Plugin Registry
+// ---------------------------------------------------------------------------
+
+export class PluginRegistry {
+  private plugins: Map<string, { def: PluginDef; loaded: boolean }> = new Map();
+  private eventBus: EventBus = new EventBus();
+  private workspaceConfig: WorkspaceConfig = {};
+  private logs: Array<{ pluginId: string; message: string; timestamp: string }> = [];
+
+  /**
+   * Register a plugin definition. Does not load it yet.
+   */
+  register(def: PluginDef): void {
+    if (this.plugins.has(def.id)) {
+      throw new Error(`Plugin "${def.id}" is already registered.`);
+    }
+    this.plugins.set(def.id, { def, loaded: false });
+  }
+
+  /**
+   * Unregister a plugin. Unloads it first if loaded.
+   */
+  async unregister(id: string): Promise<void> {
+    const entry = this.plugins.get(id);
+    if (!entry) return;
+    if (entry.loaded) await this.unload(id);
+    this.plugins.delete(id);
+  }
+
+  /**
+   * Load a plugin (call onLoad, register middleware/ontologies/rules/events).
+   * Resolves dependencies first.
+   */
+  async load(
+    id: string,
+    kernel?: TrellisKernel,
+    ontologyRegistry?: OntologyRegistry,
+    queryEngine?: QueryEngine,
+  ): Promise<void> {
+    const entry = this.plugins.get(id);
+    if (!entry) throw new Error(`Plugin "${id}" is not registered.`);
+    if (entry.loaded) return;
+
+    // Check dependencies
+    if (entry.def.dependencies) {
+      for (const dep of entry.def.dependencies) {
+        const depEntry = this.plugins.get(dep);
+        if (!depEntry) {
+          throw new Error(`Plugin "${id}" depends on "${dep}" which is not registered.`);
+        }
+        if (!depEntry.loaded) {
+          await this.load(dep, kernel, ontologyRegistry, queryEngine);
+        }
+      }
+    }
+
+    // Register middleware
+    if (entry.def.middleware && kernel) {
+      for (const mw of entry.def.middleware) {
+        kernel.addMiddleware(mw);
+      }
+    }
+
+    // Register ontologies
+    if (entry.def.ontologies && ontologyRegistry) {
+      for (const schema of entry.def.ontologies) {
+        try { ontologyRegistry.register(schema); } catch {}
+      }
+    }
+
+    // Register rules
+    if (entry.def.rules && queryEngine) {
+      for (const rule of entry.def.rules) {
+        queryEngine.addRule(rule);
+      }
+    }
+
+    // Register event handlers
+    if (entry.def.eventHandlers) {
+      for (const eh of entry.def.eventHandlers) {
+        this.eventBus.on(eh.event, eh.handler);
+      }
+    }
+
+    // Build plugin context
+    const ctx = this._buildContext(id);
+
+    // Call onLoad
+    if (entry.def.onLoad) {
+      await entry.def.onLoad(ctx);
+    }
+
+    entry.loaded = true;
+    await this.eventBus.emit('plugin:loaded', { pluginId: id });
+  }
+
+  /**
+   * Unload a plugin (call onUnload, remove middleware/events).
+   */
+  async unload(id: string): Promise<void> {
+    const entry = this.plugins.get(id);
+    if (!entry || !entry.loaded) return;
+
+    const ctx = this._buildContext(id);
+    if (entry.def.onUnload) {
+      await entry.def.onUnload(ctx);
+    }
+
+    // Remove event handlers
+    if (entry.def.eventHandlers) {
+      for (const eh of entry.def.eventHandlers) {
+        this.eventBus.off(eh.event, eh.handler);
+      }
+    }
+
+    entry.loaded = false;
+    await this.eventBus.emit('plugin:unloaded', { pluginId: id });
+  }
+
+  /**
+   * Load all registered plugins in dependency order.
+   */
+  async loadAll(
+    kernel?: TrellisKernel,
+    ontologyRegistry?: OntologyRegistry,
+    queryEngine?: QueryEngine,
+  ): Promise<void> {
+    const order = this._resolveDependencyOrder();
+    for (const id of order) {
+      await this.load(id, kernel, ontologyRegistry, queryEngine);
+    }
+  }
+
+  /**
+   * Unload all plugins in reverse order.
+   */
+  async unloadAll(): Promise<void> {
+    const order = this._resolveDependencyOrder().reverse();
+    for (const id of order) {
+      await this.unload(id);
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // Queries
+  // -------------------------------------------------------------------------
+
+  get(id: string): PluginDef | undefined {
+    return this.plugins.get(id)?.def;
+  }
+
+  isLoaded(id: string): boolean {
+    return this.plugins.get(id)?.loaded ?? false;
+  }
+
+  list(): Array<{ def: PluginDef; loaded: boolean }> {
+    return [...this.plugins.values()];
+  }
+
+  listLoaded(): PluginDef[] {
+    return [...this.plugins.values()]
+      .filter((e) => e.loaded)
+      .map((e) => e.def);
+  }
+
+  // -------------------------------------------------------------------------
+  // Event bus access
+  // -------------------------------------------------------------------------
+
+  getEventBus(): EventBus {
+    return this.eventBus;
+  }
+
+  async emit(event: string, data?: unknown): Promise<void> {
+    await this.eventBus.emit(event, data);
+  }
+
+  on(event: string, handler: EventCallback): void {
+    this.eventBus.on(event, handler);
+  }
+
+  // -------------------------------------------------------------------------
+  // Workspace config
+  // -------------------------------------------------------------------------
+
+  getWorkspaceConfig(): WorkspaceConfig {
+    return this.workspaceConfig;
+  }
+
+  setWorkspaceConfig(config: WorkspaceConfig): void {
+    this.workspaceConfig = config;
+  }
+
+  getConfigValue(key: string): unknown {
+    return this.workspaceConfig.settings?.[key];
+  }
+
+  setConfigValue(key: string, value: unknown): void {
+    if (!this.workspaceConfig.settings) this.workspaceConfig.settings = {};
+    this.workspaceConfig.settings[key] = value;
+  }
+
+  // -------------------------------------------------------------------------
+  // Logs
+  // -------------------------------------------------------------------------
+
+  getLogs(pluginId?: string): typeof this.logs {
+    if (pluginId) return this.logs.filter((l) => l.pluginId === pluginId);
+    return [...this.logs];
+  }
+
+  // -------------------------------------------------------------------------
+  // Internal
+  // -------------------------------------------------------------------------
+
+  private _buildContext(pluginId: string): PluginContext {
+    return {
+      pluginId,
+      on: (event, handler) => this.eventBus.on(event, handler),
+      emit: (event, data) => { this.eventBus.emit(event, data); },
+      getConfig: (key) => this.getConfigValue(key),
+      log: (message) => {
+        this.logs.push({ pluginId, message, timestamp: new Date().toISOString() });
+      },
+    };
+  }
+
+  private _resolveDependencyOrder(): string[] {
+    const visited = new Set<string>();
+    const order: string[] = [];
+
+    const visit = (id: string, stack: Set<string>) => {
+      if (visited.has(id)) return;
+      if (stack.has(id)) throw new Error(`Circular dependency detected: ${[...stack, id].join(' → ')}`);
+
+      stack.add(id);
+      const entry = this.plugins.get(id);
+      if (entry?.def.dependencies) {
+        for (const dep of entry.def.dependencies) {
+          visit(dep, stack);
+        }
+      }
+      stack.delete(id);
+      visited.add(id);
+      order.push(id);
+    };
+
+    for (const id of this.plugins.keys()) {
+      visit(id, new Set());
+    }
+
+    return order;
+  }
+}

package/src/core/plugins/types.ts

@@ -0,0 +1,126 @@
+/**
+ * Plugin System Types
+ *
+ * Defines the plugin interface, manifest format, lifecycle hooks,
+ * and event system for extensibility.
+ *
+ * @module trellis/core/plugins
+ */
+
+import type { KernelMiddleware } from '../kernel/middleware.js';
+import type { OntologySchema } from '../ontology/types.js';
+import type { DatalogRule } from '../query/types.js';
+import type { KernelOp } from '../persist/backend.js';
+
+// ---------------------------------------------------------------------------
+// Plugin definition
+// ---------------------------------------------------------------------------
+
+export interface PluginDef {
+  /** Unique plugin identifier (e.g. "trellis:security", "my-org:custom"). */
+  id: string;
+  /** Human-readable name. */
+  name: string;
+  /** Semantic version. */
+  version: string;
+  /** Description. */
+  description?: string;
+  /** Plugin dependencies (other plugin IDs). */
+  dependencies?: string[];
+
+  /** Kernel middleware provided by this plugin. */
+  middleware?: KernelMiddleware[];
+  /** Ontology schemas provided by this plugin. */
+  ontologies?: OntologySchema[];
+  /** Datalog rules provided by this plugin. */
+  rules?: DatalogRule[];
+  /** Event listeners provided by this plugin. */
+  eventHandlers?: EventHandler[];
+
+  /** Called when the plugin is loaded. */
+  onLoad?: (ctx: PluginContext) => void | Promise<void>;
+  /** Called when the plugin is unloaded. */
+  onUnload?: (ctx: PluginContext) => void | Promise<void>;
+}
+
+// ---------------------------------------------------------------------------
+// Plugin context — what the plugin receives during lifecycle
+// ---------------------------------------------------------------------------
+
+export interface PluginContext {
+  /** The plugin's own ID. */
+  pluginId: string;
+  /** Subscribe to events. */
+  on: (event: string, handler: EventCallback) => void;
+  /** Emit an event. */
+  emit: (event: string, data?: unknown) => void;
+  /** Get workspace config value. */
+  getConfig: (key: string) => unknown;
+  /** Log a message. */
+  log: (message: string) => void;
+}
+
+// ---------------------------------------------------------------------------
+// Event system
+// ---------------------------------------------------------------------------
+
+export type EventCallback = (data: unknown) => void | Promise<void>;
+
+export interface EventHandler {
+  /** Event name pattern (e.g. "op:*", "entity:created", "milestone:created"). */
+  event: string;
+  /** Handler function. */
+  handler: EventCallback;
+}
+
+/** Well-known event names. */
+export type WellKnownEvent =
+  | 'op:applied'
+  | 'entity:created'
+  | 'entity:updated'
+  | 'entity:deleted'
+  | 'link:added'
+  | 'link:removed'
+  | 'milestone:created'
+  | 'issue:created'
+  | 'issue:closed'
+  | 'plugin:loaded'
+  | 'plugin:unloaded';
+
+// ---------------------------------------------------------------------------
+// Workspace configuration
+// ---------------------------------------------------------------------------
+
+export interface WorkspaceConfig {
+  /** Active ontology IDs. */
+  ontologies?: string[];
+  /** Active plugin IDs. */
+  plugins?: string[];
+  /** Tracked file patterns (globs). */
+  trackedPaths?: string[];
+  /** Ignore patterns. */
+  ignorePaths?: string[];
+  /** Branch policies. */
+  branchPolicies?: Record<string, { linear?: boolean }>;
+  /** Embedding model override. */
+  embeddingModel?: string;
+  /** Snapshot threshold (ops between auto-snapshots). */
+  snapshotThreshold?: number;
+  /** Custom key-value settings. */
+  settings?: Record<string, unknown>;
+}
+
+// ---------------------------------------------------------------------------
+// Plugin manifest (for on-disk .trellis/plugins.json)
+// ---------------------------------------------------------------------------
+
+export interface PluginManifest {
+  /** Plugin ID. */
+  id: string;
+  /** Installed version. */
+  version: string;
+  /** Whether the plugin is enabled. */
+  enabled: boolean;
+  /** Plugin-specific configuration. */
+  config?: Record<string, unknown>;
+}

package/src/core/query/datalog.ts

@@ -0,0 +1,188 @@
+/**
+ * Datalog Evaluator — Rule-based recursive queries.
+ *
+ * Provides transitive closure, reachability, and other recursive
+ * graph queries via Datalog-style rules evaluated over the EAV store.
+ *
+ * Built-in rules:
+ *   - `reachable(?src, ?tgt)` via a named link attribute
+ *   - `ancestor(?x, ?y)` (generic transitive closure over any link)
+ *
+ * Custom rules can be registered via `addRule()`.
+ *
+ * @module trellis/core/query
+ */
+
+import type { EAVStore } from '../store/eav-store.js';
+import type { DatalogRule } from './types.js';
+import { variable, literal } from './types.js';
+import { QueryEngine } from './engine.js';
+
+// ---------------------------------------------------------------------------
+// Built-in rule constructors
+// ---------------------------------------------------------------------------
+
+/**
+ * Creates a transitive closure rule over a specific link attribute.
+ *
+ * `reachable(?x, ?y) :- (x attr y)`
+ * `reachable(?x, ?y) :- (x attr ?z), reachable(?z, ?y)`
+ */
+export function transitiveClosureRules(ruleName: string, linkAttribute: string): DatalogRule[] {
+  return [
+    // Base case: direct link
+    {
+      name: ruleName,
+      params: ['x', 'y'],
+      body: [
+        {
+          kind: 'link',
+          source: variable('x'),
+          attribute: literal(linkAttribute),
+          target: variable('y'),
+        },
+      ],
+      filters: [],
+    },
+    // Recursive case: indirect via intermediate
+    {
+      name: ruleName,
+      params: ['x', 'y'],
+      body: [
+        {
+          kind: 'link',
+          source: variable('x'),
+          attribute: literal(linkAttribute),
+          target: variable('z'),
+        },
+        {
+          kind: 'rule',
+          name: ruleName,
+          args: [variable('z'), variable('y')],
+        },
+      ],
+      filters: [],
+    },
+  ];
+}
+
+/**
+ * Creates a reverse reachability rule (follows links backwards).
+ */
+export function reverseReachabilityRules(ruleName: string, linkAttribute: string): DatalogRule[] {
+  return [
+    {
+      name: ruleName,
+      params: ['x', 'y'],
+      body: [
+        {
+          kind: 'link',
+          source: variable('y'),
+          attribute: literal(linkAttribute),
+          target: variable('x'),
+        },
+      ],
+      filters: [],
+    },
+    {
+      name: ruleName,
+      params: ['x', 'y'],
+      body: [
+        {
+          kind: 'link',
+          source: variable('z'),
+          attribute: literal(linkAttribute),
+          target: variable('x'),
+        },
+        {
+          kind: 'rule',
+          name: ruleName,
+          args: [variable('z'), variable('y')],
+        },
+      ],
+      filters: [],
+    },
+  ];
+}
+
+/**
+ * Creates a "sibling" rule — entities that share a common parent via a link attribute.
+ *
+ * `sibling(?a, ?b) :- (?a attr ?parent), (?b attr ?parent)`
+ * FILTER ?a != ?b
+ */
+export function siblingRules(ruleName: string, linkAttribute: string): DatalogRule[] {
+  return [
+    {
+      name: ruleName,
+      params: ['a', 'b'],
+      body: [
+        {
+          kind: 'link',
+          source: variable('a'),
+          attribute: literal(linkAttribute),
+          target: variable('parent'),
+        },
+        {
+          kind: 'link',
+          source: variable('b'),
+          attribute: literal(linkAttribute),
+          target: variable('parent'),
+        },
+      ],
+      filters: [
+        {
+          kind: 'filter',
+          left: variable('a'),
+          op: '!=',
+          right: variable('b'),
+        },
+      ],
+    },
+  ];
+}
+
+// ---------------------------------------------------------------------------
+// Datalog Runtime — convenience wrapper around QueryEngine + rules
+// ---------------------------------------------------------------------------
+
+export class DatalogRuntime {
+  private engine: QueryEngine;
+
+  constructor(store: EAVStore) {
+    this.engine = new QueryEngine(store);
+  }
+
+  /** Register a Datalog rule (or multiple). */
+  addRule(rule: DatalogRule): void {
+    this.engine.addRule(rule);
+  }
+
+  addRules(rules: DatalogRule[]): void {
+    for (const r of rules) this.engine.addRule(r);
+  }
+
+  removeRule(name: string): void {
+    this.engine.removeRule(name);
+  }
+
+  /** Register built-in transitive closure for a link attribute. */
+  registerTransitiveClosure(ruleName: string, linkAttribute: string): void {
+    this.addRules(transitiveClosureRules(ruleName, linkAttribute));
+  }
+
+  /** Register built-in reverse reachability for a link attribute. */
+  registerReverseReachability(ruleName: string, linkAttribute: string): void {
+    this.addRules(reverseReachabilityRules(ruleName, linkAttribute));
+  }
+
+  /** Register built-in sibling rule for a link attribute. */
+  registerSiblings(ruleName: string, linkAttribute: string): void {
+    this.addRules(siblingRules(ruleName, linkAttribute));
+  }
+
+  /** Get the underlying QueryEngine for direct query execution. */
+  getEngine(): QueryEngine {
+    return this.engine;
+  }
+}