@unrdf/kgc-runtime 26.4.2

package/src/work-item.mjs

@@ -0,0 +1,449 @@
+/**
+ * KGC Runtime - Async Work Item System
+ * Provides work item management with deterministic scheduling and receipt logging
+ */
+
+import { createStore, dataFactory } from '@unrdf/oxigraph';
+import { z } from 'zod';
+
+/**
+ * Work item state enumeration
+ */
+export const WORK_ITEM_STATES = {
+  QUEUED: 'queued',
+  RUNNING: 'running',
+  SUCCEEDED: 'succeeded',
+  FAILED: 'failed',
+  DENIED: 'denied',
+};
+
+/**
+ * Terminal states (cannot transition from these)
+ */
+const TERMINAL_STATES = new Set([
+  WORK_ITEM_STATES.SUCCEEDED,
+  WORK_ITEM_STATES.FAILED,
+  WORK_ITEM_STATES.DENIED,
+]);
+
+/**
+ * Valid state transitions
+ */
+const VALID_TRANSITIONS = {
+  [WORK_ITEM_STATES.QUEUED]: [
+    WORK_ITEM_STATES.RUNNING,
+    WORK_ITEM_STATES.DENIED,
+  ],
+  [WORK_ITEM_STATES.RUNNING]: [
+    WORK_ITEM_STATES.SUCCEEDED,
+    WORK_ITEM_STATES.FAILED,
+  ],
+  [WORK_ITEM_STATES.SUCCEEDED]: [],
+  [WORK_ITEM_STATES.FAILED]: [],
+  [WORK_ITEM_STATES.DENIED]: [],
+};
+
+/**
+ * Zod schema for work item bounds
+ */
+const BoundsSchema = z.object({
+  timeout: z.number().optional(),
+  maxRetries: z.number().optional(),
+  priority: z.number().optional(),
+  metadata: z.any().optional(),
+}).optional();
+
+/**
+ * Generate nanosecond timestamp
+ * @returns {bigint} Current time in nanoseconds
+ */
+function nowNs() {
+  const hrTime = process.hrtime.bigint();
+  return hrTime;
+}
+
+/**
+ * Generate unique work item ID
+ * @returns {string} Unique ID
+ */
+function generateWorkItemId() {
+  if (typeof crypto !== 'undefined' && crypto.randomUUID) {
+    return `work-item-${crypto.randomUUID()}`;
+  }
+  try {
+    const crypto = require('crypto');
+    return `work-item-${crypto.randomUUID()}`;
+  } catch {
+    return `work-item-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+  }
+}
+
+/**
+ * WorkItem Executor - Manages async work items with deterministic scheduling
+ *
+ * @example
+ * import { WorkItemExecutor } from './work-item.mjs';
+ * const executor = new WorkItemExecutor();
+ * const id = await executor.enqueueWorkItem('Process data');
+ * const item = await executor.pollWorkItem(id);
+ * console.assert(item.status === 'queued');
+ */
+export class WorkItemExecutor {
+  /**
+   * Create new work item executor
+   * @param {Object} options - Configuration options
+   */
+  constructor(options = {}) {
+    this.store = createStore();
+    this.workItems = new Map(); // In-memory cache for fast access
+    this.stateTransitionCount = 0;
+
+    // RDF predicates for work items
+    this.predicates = {
+      GOAL: 'http://kgc.io/goal',
+      STATUS: 'http://kgc.io/status',
+      CREATED_NS: 'http://kgc.io/created_ns',
+      STARTED_NS: 'http://kgc.io/started_ns',
+      FINISHED_NS: 'http://kgc.io/finished_ns',
+      RECEIPT_LOG: 'http://kgc.io/receipt_log',
+      BOUNDS: 'http://kgc.io/bounds',
+      PRIORITY: 'http://kgc.io/priority',
+    };
+
+    // Named graph for work items
+    this.workItemsGraph = 'http://kgc.io/var/kgc/work-items';
+  }
+
+  /**
+   * Enqueue new work item
+   *
+   * @param {string} goal - Work item goal/description
+   * @param {Object} [bounds] - Execution bounds (timeout, retries, priority, etc.)
+   * @returns {Promise<string>} Work item ID
+   *
+   * @example
+   * const id = await executor.enqueueWorkItem('Calculate sum', { priority: 5 });
+   */
+  async enqueueWorkItem(goal, bounds = {}) {
+    // Validate bounds
+    BoundsSchema.parse(bounds);
+
+    const workItemId = generateWorkItemId();
+    const created_ns = nowNs();
+
+    const workItem = {
+      id: workItemId,
+      goal,
+      status: WORK_ITEM_STATES.QUEUED,
+      receipt_log: [],
+      created_ns: created_ns.toString(),
+      started_ns: null,
+      finished_ns: null,
+      bounds,
+      priority: bounds.priority || 0,
+    };
+
+    // Store in memory
+    this.workItems.set(workItemId, workItem);
+
+    // Store in RDF triple store
+    await this._persistWorkItem(workItem);
+
+    // Count initial state
+    this.stateTransitionCount++;
+
+    return workItemId;
+  }
+
+  /**
+   * Poll work item status
+   *
+   * @param {string} workItemId - Work item ID
+   * @returns {Promise<Object|null>} Work item or null if not found
+   *
+   * @example
+   * const item = await executor.pollWorkItem(id);
+   * console.log(item.status); // 'queued'
+   */
+  async pollWorkItem(workItemId) {
+    const workItem = this.workItems.get(workItemId);
+
+    if (!workItem) {
+      return null;
+    }
+
+    // Return deep copy to prevent external modifications
+    return JSON.parse(JSON.stringify(workItem));
+  }
+
+  /**
+   * Transition work item to new state
+   *
+   * @param {string} workItemId - Work item ID
+   * @param {string} newState - Target state
+   * @throws {Error} If transition is invalid
+   *
+   * @example
+   * await executor.transitionWorkItem(id, WORK_ITEM_STATES.RUNNING);
+   */
+  async transitionWorkItem(workItemId, newState) {
+    const workItem = this.workItems.get(workItemId);
+
+    if (!workItem) {
+      throw new Error(`Work item not found: ${workItemId}`);
+    }
+
+    const currentState = workItem.status;
+
+    // Check if current state is terminal
+    if (TERMINAL_STATES.has(currentState)) {
+      throw new Error(
+        `Cannot transition from terminal state: ${currentState}`
+      );
+    }
+
+    // Validate state transition
+    if (!VALID_TRANSITIONS[currentState]?.includes(newState)) {
+      throw new Error(
+        `Invalid state transition: ${currentState} -> ${newState}`
+      );
+    }
+
+    // Update state
+    workItem.status = newState;
+
+    // Update timestamps
+    if (newState === WORK_ITEM_STATES.RUNNING && !workItem.started_ns) {
+      workItem.started_ns = nowNs().toString();
+    }
+
+    if (TERMINAL_STATES.has(newState) && !workItem.finished_ns) {
+      workItem.finished_ns = nowNs().toString();
+    }
+
+    // Persist changes
+    await this._persistWorkItem(workItem);
+
+    // Increment transition counter
+    this.stateTransitionCount++;
+  }
+
+  /**
+   * Finalize work item with result and final receipt
+   *
+   * @param {string} workItemId - Work item ID
+   * @param {Object} result - Execution result
+   * @param {Object} receipt - Final receipt
+   * @returns {Promise<Object>} Updated work item
+   *
+   * @example
+   * const item = await executor.finalizeWorkItem(id, { value: 42 }, { done: true });
+   */
+  async finalizeWorkItem(workItemId, result, receipt) {
+    const workItem = this.workItems.get(workItemId);
+
+    if (!workItem) {
+      throw new Error(`Work item not found: ${workItemId}`);
+    }
+
+    // Add final receipt
+    await this.addReceipt(workItemId, receipt);
+
+    // Transition to succeeded (if currently running)
+    if (workItem.status === WORK_ITEM_STATES.RUNNING) {
+      await this.transitionWorkItem(workItemId, WORK_ITEM_STATES.SUCCEEDED);
+    }
+
+    // Store result
+    workItem.result = result;
+    await this._persistWorkItem(workItem);
+
+    return this.pollWorkItem(workItemId);
+  }
+
+  /**
+   * Add receipt to work item's append-only log
+   *
+   * @param {string} workItemId - Work item ID
+   * @param {Object} receipt - Receipt data
+   *
+   * @example
+   * await executor.addReceipt(id, { step: 'validation', status: 'ok' });
+   */
+  async addReceipt(workItemId, receipt) {
+    const workItem = this.workItems.get(workItemId);
+
+    if (!workItem) {
+      throw new Error(`Work item not found: ${workItemId}`);
+    }
+
+    // Deep copy receipt to ensure immutability
+    const receiptCopy = JSON.parse(JSON.stringify(receipt));
+
+    // Append to log
+    workItem.receipt_log.push(receiptCopy);
+
+    // Persist changes
+    await this._persistWorkItem(workItem);
+  }
+
+  /**
+   * Get deterministic execution order
+   * Returns pending/queued items ordered by priority (desc) then creation time (asc)
+   *
+   * @returns {string[]} Ordered array of work item IDs
+   *
+   * @example
+   * const order = executor.getExecutionOrder();
+   * console.log(order); // ['work-item-1', 'work-item-2', ...]
+   */
+  getExecutionOrder() {
+    const eligibleItems = Array.from(this.workItems.values())
+      .filter(item => item.status === WORK_ITEM_STATES.QUEUED);
+
+    // Sort by priority (descending) then by creation time (ascending)
+    eligibleItems.sort((a, b) => {
+      // Higher priority first
+      if (a.priority !== b.priority) {
+        return b.priority - a.priority;
+      }
+      // Earlier creation time first (FIFO for same priority)
+      return BigInt(a.created_ns) < BigInt(b.created_ns) ? -1 : 1;
+    });
+
+    return eligibleItems.map(item => item.id);
+  }
+
+  /**
+   * Get total state transition count
+   *
+   * @returns {number} Number of state transitions
+   */
+  getStateTransitionCount() {
+    return this.stateTransitionCount;
+  }
+
+  /**
+   * Query work items using SPARQL
+   *
+   * @param {string} sparql - SPARQL query
+   * @returns {Promise<Array>} Query results
+   */
+  async queryWorkItems(sparql) {
+    return this.store.query(sparql);
+  }
+
+  // ===== Private Methods =====
+
+  /**
+   * Persist work item to RDF triple store
+   * @private
+   */
+  async _persistWorkItem(workItem) {
+    const subject = dataFactory.namedNode(
+      `http://kgc.io/var/kgc/work-items/${workItem.id}`
+    );
+    const graph = dataFactory.namedNode(this.workItemsGraph);
+
+    // Remove existing quads for this work item
+    const existingQuads = [];
+    for (const quad of this.store.match(subject, null, null, graph)) {
+      existingQuads.push(quad);
+    }
+    for (const quad of existingQuads) {
+      this.store.delete(quad);
+    }
+
+    // Add updated quads
+    const quads = [
+      dataFactory.quad(
+        subject,
+        dataFactory.namedNode(this.predicates.GOAL),
+        dataFactory.literal(workItem.goal),
+        graph
+      ),
+      dataFactory.quad(
+        subject,
+        dataFactory.namedNode(this.predicates.STATUS),
+        dataFactory.literal(workItem.status),
+        graph
+      ),
+      dataFactory.quad(
+        subject,
+        dataFactory.namedNode(this.predicates.CREATED_NS),
+        dataFactory.literal(
+          workItem.created_ns,
+          dataFactory.namedNode('http://www.w3.org/2001/XMLSchema#integer')
+        ),
+        graph
+      ),
+    ];
+
+    if (workItem.started_ns) {
+      quads.push(
+        dataFactory.quad(
+          subject,
+          dataFactory.namedNode(this.predicates.STARTED_NS),
+          dataFactory.literal(
+            workItem.started_ns,
+            dataFactory.namedNode('http://www.w3.org/2001/XMLSchema#integer')
+          ),
+          graph
+        )
+      );
+    }
+
+    if (workItem.finished_ns) {
+      quads.push(
+        dataFactory.quad(
+          subject,
+          dataFactory.namedNode(this.predicates.FINISHED_NS),
+          dataFactory.literal(
+            workItem.finished_ns,
+            dataFactory.namedNode('http://www.w3.org/2001/XMLSchema#integer')
+          ),
+          graph
+        )
+      );
+    }
+
+    if (workItem.receipt_log.length > 0) {
+      quads.push(
+        dataFactory.quad(
+          subject,
+          dataFactory.namedNode(this.predicates.RECEIPT_LOG),
+          dataFactory.literal(JSON.stringify(workItem.receipt_log)),
+          graph
+        )
+      );
+    }
+
+    if (workItem.bounds) {
+      quads.push(
+        dataFactory.quad(
+          subject,
+          dataFactory.namedNode(this.predicates.BOUNDS),
+          dataFactory.literal(JSON.stringify(workItem.bounds)),
+          graph
+        )
+      );
+    }
+
+    quads.push(
+      dataFactory.quad(
+        subject,
+        dataFactory.namedNode(this.predicates.PRIORITY),
+        dataFactory.literal(
+          workItem.priority.toString(),
+          dataFactory.namedNode('http://www.w3.org/2001/XMLSchema#integer')
+        ),
+        graph
+      )
+    );
+
+    // Add all quads to store
+    for (const quad of quads) {
+      this.store.add(quad);
+    }
+  }
+}

package/templates/plugin-template/README.md

@@ -0,0 +1,58 @@
+# Example KGC Plugin Template
+
+This is a complete template for creating KGC Runtime plugins.
+
+## Structure
+
+```
+plugin-template/
+├── plugin.json       # Plugin manifest
+├── index.mjs         # Plugin implementation
+├── README.md         # This file
+└── test.mjs          # Plugin tests
+```
+
+## Quick Start
+
+1. **Copy Template**
+   ```bash
+   cp -r templates/plugin-template my-plugin
+   cd my-plugin
+   ```
+
+2. **Update Manifest** (`plugin.json`)
+   - Change `name` to your plugin name
+   - Update `version`, `author`, `description`
+   - Declare required `capabilities`
+
+3. **Implement Plugin** (`index.mjs`)
+   - Modify `initialize()` for setup
+   - Add your custom methods
+   - Update `cleanup()` for teardown
+
+4. **Test Plugin** (`test.mjs`)
+   - Write comprehensive tests
+   - Test all capabilities
+   - Verify error handling
+
+5. **Register and Use**
+   ```javascript
+   import { PluginManager } from '@unrdf/kgc-runtime/plugin-manager';
+
+   const manager = new PluginManager();
+   await manager.registerPlugin(manifest);
+   await manager.loadPlugin('my-plugin@1.0.0');
+   ```
+
+## Best Practices
+
+1. **Validate All Inputs** - Use Zod schemas
+2. **Handle Errors** - Return error receipts
+3. **Declare Minimum Capabilities** - Only what you need
+4. **Document Your API** - JSDoc comments
+5. **Write Tests** - Aim for 100% coverage
+
+## See Also
+
+- [Plugin Development Guide](../../docs/extensions/plugin-development.md)
+- [API Stability Policy](../../docs/api-stability.md)

package/templates/plugin-template/index.mjs

@@ -0,0 +1,162 @@
+/**
+ * Example KGC Runtime Plugin
+ *
+ * This is a template for creating custom KGC plugins.
+ * Copy this template and modify to create your own plugin.
+ */
+
+import { z } from 'zod';
+import { PluginReceiptSchema } from '@unrdf/kgc-runtime/schemas';
+
+/**
+ * Input validation schema
+ */
+const InputSchema = z.object({
+  operation: z.string().min(1).max(100),
+  data: z.record(z.any()).optional(),
+});
+
+/**
+ * Plugin entry point
+ *
+ * @param {Object} runtime - KGC Runtime API (whitelisted methods only)
+ * @returns {Object} Plugin interface
+ */
+export default function examplePlugin(runtime) {
+  // Private state (encapsulated)
+  let initialized = false;
+  let callCount = 0;
+
+  return {
+    name: 'example-plugin',
+    version: '1.0.0',
+
+    /**
+     * Initialize plugin
+     * Called when plugin transitions to LOADED state
+     */
+    async initialize() {
+      console.log('[example-plugin] Initializing...');
+
+      // Perform any setup here
+      // - Validate runtime API
+      // - Initialize state
+      // - Connect to resources (within capability limits)
+
+      initialized = true;
+      console.log('[example-plugin] Initialized successfully');
+    },
+
+    /**
+     * Generate custom receipt
+     *
+     * @param {string} operation - Operation name
+     * @param {Object} inputs - Operation inputs
+     * @param {Object} outputs - Operation outputs
+     * @returns {Promise<Object>} Custom receipt
+     */
+    async generateCustomReceipt(operation, inputs = {}, outputs = {}) {
+      if (!initialized) {
+        throw new Error('Plugin not initialized');
+      }
+
+      // Validate inputs
+      InputSchema.parse({ operation, data: inputs });
+
+      // Use runtime API to generate base receipt
+      const baseReceipt = await runtime.generateReceipt(
+        operation,
+        inputs,
+        outputs
+      );
+
+      callCount++;
+
+      // Extend with custom metadata
+      const customReceipt = {
+        ...baseReceipt,
+        pluginMetadata: {
+          pluginName: 'example-plugin',
+          pluginVersion: '1.0.0',
+          receiptType: 'custom-example',
+          customFields: {
+            callCount,
+            timestamp: Date.now(),
+            processingNotes: 'Processed by example plugin',
+          },
+        },
+      };
+
+      // Validate against plugin receipt schema
+      return PluginReceiptSchema.parse(customReceipt);
+    },
+
+    /**
+     * Validate custom receipt
+     *
+     * @param {Object} receipt - Receipt to validate
+     * @returns {Promise<Object>} Validation result
+     */
+    async validateCustomReceipt(receipt) {
+      if (!initialized) {
+        throw new Error('Plugin not initialized');
+      }
+
+      try {
+        // Validate schema
+        const validated = PluginReceiptSchema.parse(receipt);
+
+        // Custom validation logic
+        if (validated.pluginMetadata?.pluginName !== 'example-plugin') {
+          return {
+            valid: false,
+            errors: ['Receipt not from example-plugin'],
+          };
+        }
+
+        // Use runtime validation
+        const baseValidation = await runtime.validateReceipt(receipt);
+
+        return {
+          valid: baseValidation.success,
+          errors: baseValidation.errors || [],
+          metadata: validated.pluginMetadata,
+        };
+      } catch (error) {
+        return {
+          valid: false,
+          errors: [error.message],
+        };
+      }
+    },
+
+    /**
+     * Get plugin statistics
+     *
+     * @returns {Object} Plugin stats
+     */
+    getStats() {
+      return {
+        initialized,
+        callCount,
+        version: '1.0.0',
+      };
+    },
+
+    /**
+     * Cleanup on unload
+     * Called when plugin transitions to UNLOADED state
+     */
+    async cleanup() {
+      console.log('[example-plugin] Cleaning up...');
+
+      // Perform cleanup:
+      // - Close connections
+      // - Release resources
+      // - Save state if needed
+
+      initialized = false;
+      console.log('[example-plugin] Cleanup complete');
+    },
+  };
+}

package/templates/plugin-template/plugin.json

@@ -0,0 +1,19 @@
+{
+  "name": "example-plugin",
+  "version": "1.0.0",
+  "description": "Example KGC Runtime plugin template",
+  "entryPoint": "./index.mjs",
+  "capabilities": [
+    "receipt:generate",
+    "receipt:validate",
+    "custom:example"
+  ],
+  "api_version": "5.0.1",
+  "author": "Your Name",
+  "license": "MIT",
+  "repository": "https://github.com/your-org/example-plugin",
+  "metadata": {
+    "tags": ["example", "template"],
+    "category": "receipt"
+  }
+}