@unrdf/kgc-runtime 26.4.2

package/src/api-version.mjs

@@ -0,0 +1,373 @@
+/**
+ * @file API Version - Semantic versioning and deprecation tracking
+ * @module @unrdf/kgc-runtime/api-version
+ * @description Manages API versioning with deprecation policy and compatibility checking
+ */
+
+import { z } from 'zod';
+
+/**
+ * Current KGC Runtime API version
+ */
+export const CURRENT_API_VERSION = '5.0.1';
+
+/**
+ * API version status
+ */
+export const API_STATUS = {
+  STABLE: 'stable',
+  BETA: 'beta',
+  DEPRECATED: 'deprecated',
+  REMOVED: 'removed',
+};
+
+/**
+ * Version metadata schema
+ */
+const VersionMetadataSchema = z.object({
+  version: z.string().regex(/^\d+\.\d+\.\d+$/),
+  status: z.enum(['stable', 'beta', 'deprecated', 'removed']),
+  releaseDate: z.string().optional(),
+  deprecationDate: z.string().optional(),
+  removalDate: z.string().optional(),
+  deprecationReason: z.string().optional(),
+  migrationGuide: z.string().optional(),
+  breakingChanges: z.array(z.string()).optional(),
+});
+
+/**
+ * API versions registry
+ * Each version tracks its status, deprecation, and compatibility
+ */
+const API_VERSIONS = [
+  {
+    version: '5.0.1',
+    status: API_STATUS.BETA,
+    releaseDate: '2024-12-27',
+    breakingChanges: [
+      'Plugin system introduced',
+      'Enhanced isolation and capability management',
+    ],
+  },
+  {
+    version: '5.0.0',
+    status: API_STATUS.BETA,
+    releaseDate: '2024-12-26',
+    breakingChanges: [
+      'Work item system refactored',
+      'Receipt format updated to include parent hash',
+    ],
+  },
+  {
+    version: '4.0.0',
+    status: API_STATUS.DEPRECATED,
+    releaseDate: '2024-11-01',
+    deprecationDate: '2024-12-01',
+    removalDate: '2025-03-01',
+    deprecationReason: 'Replaced by v5 with enhanced governance features',
+    migrationGuide: 'See docs/migration/v4-to-v5.md',
+  },
+  {
+    version: '3.0.0',
+    status: API_STATUS.REMOVED,
+    releaseDate: '2024-06-01',
+    deprecationDate: '2024-09-01',
+    removalDate: '2024-12-01',
+    deprecationReason: 'Legacy API completely removed',
+    migrationGuide: 'See docs/migration/v3-to-v5.md',
+  },
+];
+
+/**
+ * Deprecation policy:
+ * - APIs are marked deprecated 2 releases before removal
+ * - Deprecated APIs remain functional but emit warnings
+ * - Removal happens after minimum 3 months deprecation period
+ */
+export const DEPRECATION_POLICY = {
+  RELEASES_BEFORE_REMOVAL: 2,
+  MIN_DEPRECATION_PERIOD_DAYS: 90,
+  WARNING_ENABLED: true,
+};
+
+/**
+ * API Version Manager - Tracks versions, deprecations, and compatibility
+ *
+ * @example
+ * import { APIVersionManager } from '@unrdf/kgc-runtime/api-version';
+ * const versionManager = new APIVersionManager();
+ * const compatible = versionManager.isCompatible('5.0.0', '5.0.1');
+ * console.log(compatible); // true
+ */
+export class APIVersionManager {
+  constructor() {
+    this.versions = new Map();
+    this.deprecationWarnings = new Set();
+
+    // Load versions
+    for (const versionData of API_VERSIONS) {
+      this.versions.set(versionData.version, versionData);
+    }
+  }
+
+  /**
+   * Get current API version
+   *
+   * @returns {string} Current version
+   */
+  getCurrentVersion() {
+    return CURRENT_API_VERSION;
+  }
+
+  /**
+   * Get version metadata
+   *
+   * @param {string} version - Version to query
+   * @returns {Object|null} Version metadata or null if not found
+   *
+   * @example
+   * const metadata = versionManager.getVersionMetadata('5.0.1');
+   * console.log(metadata.status); // 'beta'
+   */
+  getVersionMetadata(version) {
+    return this.versions.get(version) || null;
+  }
+
+  /**
+   * Check if version is deprecated
+   *
+   * @param {string} version - Version to check
+   * @returns {boolean} True if deprecated
+   *
+   * @example
+   * const deprecated = versionManager.isDeprecated('4.0.0');
+   * console.log(deprecated); // true
+   */
+  isDeprecated(version) {
+    const metadata = this.getVersionMetadata(version);
+    return metadata?.status === API_STATUS.DEPRECATED;
+  }
+
+  /**
+   * Check if version is removed
+   *
+   * @param {string} version - Version to check
+   * @returns {boolean} True if removed
+   */
+  isRemoved(version) {
+    const metadata = this.getVersionMetadata(version);
+    return metadata?.status === API_STATUS.REMOVED;
+  }
+
+  /**
+   * Check if version is stable
+   *
+   * @param {string} version - Version to check
+   * @returns {boolean} True if stable
+   */
+  isStable(version) {
+    const metadata = this.getVersionMetadata(version);
+    return metadata?.status === API_STATUS.STABLE;
+  }
+
+  /**
+   * Check version compatibility (semver)
+   *
+   * @param {string} requiredVersion - Required version
+   * @param {string} actualVersion - Actual version
+   * @returns {boolean} True if compatible
+   *
+   * @example
+   * const compatible = versionManager.isCompatible('5.0.0', '5.0.1');
+   * console.log(compatible); // true (patch compatible)
+   */
+  isCompatible(requiredVersion, actualVersion) {
+    const [reqMajor, reqMinor] = requiredVersion.split('.').map(Number);
+    const [actMajor, actMinor] = actualVersion.split('.').map(Number);
+
+    // Major version must match
+    if (reqMajor !== actMajor) {
+      return false;
+    }
+
+    // Minor version must be >= required
+    if (actMinor < reqMinor) {
+      return false;
+    }
+
+    return true;
+  }
+
+  /**
+   * Emit deprecation warning
+   *
+   * @param {string} feature - Deprecated feature
+   * @param {string} version - Version it was deprecated
+   * @param {string} alternative - Recommended alternative
+   *
+   * @example
+   * versionManager.warnDeprecation('oldFunction', '4.0.0', 'Use newFunction instead');
+   */
+  warnDeprecation(feature, version, alternative) {
+    if (!DEPRECATION_POLICY.WARNING_ENABLED) {
+      return;
+    }
+
+    const warningKey = `${feature}@${version}`;
+
+    // Only warn once per feature
+    if (this.deprecationWarnings.has(warningKey)) {
+      return;
+    }
+
+    console.warn(
+      `[DEPRECATION WARNING] ${feature} is deprecated since v${version}. ${alternative}`
+    );
+
+    this.deprecationWarnings.add(warningKey);
+  }
+
+  /**
+   * Get all deprecated versions
+   *
+   * @returns {Array<Object>} Array of deprecated version metadata
+   */
+  getDeprecatedVersions() {
+    return Array.from(this.versions.values()).filter(
+      v => v.status === API_STATUS.DEPRECATED
+    );
+  }
+
+  /**
+   * Get breaking changes for a version
+   *
+   * @param {string} version - Version to query
+   * @returns {Array<string>} Array of breaking changes
+   */
+  getBreakingChanges(version) {
+    const metadata = this.getVersionMetadata(version);
+    return metadata?.breakingChanges || [];
+  }
+
+  /**
+   * Calculate days until removal
+   *
+   * @param {string} version - Deprecated version
+   * @returns {number|null} Days until removal or null if not deprecated
+   */
+  getDaysUntilRemoval(version) {
+    const metadata = this.getVersionMetadata(version);
+
+    if (!metadata || !metadata.removalDate) {
+      return null;
+    }
+
+    const now = new Date();
+    const removalDate = new Date(metadata.removalDate);
+    const diffTime = removalDate - now;
+    const diffDays = Math.ceil(diffTime / (1000 * 60 * 60 * 24));
+
+    return diffDays;
+  }
+
+  /**
+   * List all versions
+   *
+   * @returns {Array<Object>} All version metadata
+   */
+  listVersions() {
+    return Array.from(this.versions.values());
+  }
+
+  /**
+   * Add new version
+   *
+   * @param {Object} versionData - Version metadata
+   */
+  addVersion(versionData) {
+    const validated = VersionMetadataSchema.parse(versionData);
+    this.versions.set(validated.version, validated);
+  }
+
+  /**
+   * Mark version as deprecated
+   *
+   * @param {string} version - Version to deprecate
+   * @param {Object} options - Deprecation options
+   * @param {string} options.reason - Deprecation reason
+   * @param {string} options.migrationGuide - Migration guide URL
+   * @param {string} options.removalDate - Planned removal date (ISO)
+   */
+  deprecateVersion(version, options = {}) {
+    const metadata = this.getVersionMetadata(version);
+
+    if (!metadata) {
+      throw new Error(`Version not found: ${version}`);
+    }
+
+    metadata.status = API_STATUS.DEPRECATED;
+    metadata.deprecationDate = new Date().toISOString().split('T')[0];
+    metadata.deprecationReason = options.reason;
+    metadata.migrationGuide = options.migrationGuide;
+    metadata.removalDate = options.removalDate;
+
+    this.versions.set(version, metadata);
+  }
+}
+
+/**
+ * Singleton instance
+ */
+const versionManager = new APIVersionManager();
+
+/**
+ * Get the singleton version manager
+ *
+ * @returns {APIVersionManager} Version manager instance
+ */
+export function getVersionManager() {
+  return versionManager;
+}
+
+/**
+ * Check if plugin API version is compatible with runtime
+ *
+ * @param {string} pluginVersion - Plugin's required API version
+ * @returns {boolean} True if compatible
+ *
+ * @example
+ * const compatible = isPluginCompatible('5.0.0');
+ * console.log(compatible); // true
+ */
+export function isPluginCompatible(pluginVersion) {
+  return versionManager.isCompatible(pluginVersion, CURRENT_API_VERSION);
+}
+
+/**
+ * Validate plugin API version
+ *
+ * @param {string} pluginVersion - Plugin's API version
+ * @throws {Error} If version is incompatible or removed
+ */
+export function validatePluginVersion(pluginVersion) {
+  if (versionManager.isRemoved(pluginVersion)) {
+    throw new Error(
+      `Plugin API version ${pluginVersion} has been removed. Please upgrade plugin.`
+    );
+  }
+
+  if (!isPluginCompatible(pluginVersion)) {
+    throw new Error(
+      `Plugin API version ${pluginVersion} is incompatible with runtime ${CURRENT_API_VERSION}`
+    );
+  }
+
+  if (versionManager.isDeprecated(pluginVersion)) {
+    const daysUntilRemoval = versionManager.getDaysUntilRemoval(pluginVersion);
+    versionManager.warnDeprecation(
+      `Plugin API version ${pluginVersion}`,
+      pluginVersion,
+      `Upgrade to ${CURRENT_API_VERSION}. Removal in ${daysUntilRemoval} days.`
+    );
+  }
+}

package/src/atomic-admission.mjs

@@ -0,0 +1,310 @@
+/**
+ * @fileoverview Atomic Capsule Admission using Two-Phase Commit
+ * Ensures all-or-nothing capsule admission across conflicts
+ *
+ * Pattern: Transaction wrapper around merge operations
+ */
+
+import { z } from 'zod';
+import { TransactionManager } from './transaction.mjs';
+import { mergeCapsules } from './merge.mjs';
+import { RollbackLog } from './rollback.mjs';
+
+// ============================================================================
+// Schemas
+// ============================================================================
+
+/**
+ * Atomic admission request schema
+ */
+const AtomicAdmissionRequestSchema = z.object({
+  capsules: z.array(z.any()),
+  totalOrder: z.object({
+    rules: z.array(z.any()),
+    default_rule: z.any(),
+  }),
+  bounds: z.record(z.any()).optional(),
+});
+
+/**
+ * Atomic admission result schema
+ */
+const AtomicAdmissionResultSchema = z.object({
+  success: z.boolean(),
+  transaction_id: z.string().optional(),
+  admitted: z.array(z.string()),
+  denied: z.array(z.string()),
+  conflict_receipts: z.array(z.any()),
+  receipts: z.array(z.any()).optional(),
+  errors: z.array(z.string()).optional(),
+});
+
+/**
+ * @typedef {z.infer<typeof AtomicAdmissionRequestSchema>} AtomicAdmissionRequest
+ */
+
+/**
+ * @typedef {z.infer<typeof AtomicAdmissionResultSchema>} AtomicAdmissionResult
+ */
+
+// ============================================================================
+// AtomicAdmissionGate Class
+// ============================================================================
+
+/**
+ * AtomicAdmissionGate - Atomic capsule admission using transactions
+ *
+ * Features:
+ * - All-or-nothing admission (either all capsules admitted or none)
+ * - Automatic rollback on conflict
+ * - Receipt generation for all operations
+ * - Integration with merge conflict resolution
+ *
+ * @example
+ * const gate = new AtomicAdmissionGate();
+ * const result = await gate.admitCapsules(capsules, totalOrder);
+ * if (result.success) {
+ *   console.log('All capsules admitted:', result.admitted);
+ * } else {
+ *   console.log('Admission failed, rolled back');
+ * }
+ */
+export class AtomicAdmissionGate {
+  /**
+   * @param {Object} options - Configuration options
+   * @param {string} options.logPath - Path to rollback log
+   */
+  constructor(options = {}) {
+    /** @type {TransactionManager} */
+    this.txManager = new TransactionManager({
+      logPath: options.logPath,
+      onRollback: (event) => this._handleRollback(event),
+    });
+
+    /** @type {RollbackLog} */
+    this.rollbackLog = new RollbackLog(options.logPath);
+
+    /** @type {Map<string, any>} */
+    this.admittedCapsules = new Map();
+  }
+
+  /**
+   * Admit capsules atomically
+   *
+   * @param {any[]} capsules - Capsules to admit
+   * @param {any} totalOrder - Conflict resolution rules
+   * @param {any} [bounds] - Optional resource bounds
+   * @returns {Promise<AtomicAdmissionResult>} Admission result
+   */
+  async admitCapsules(capsules, totalOrder, bounds = {}) {
+    try {
+      // Validate input
+      const request = AtomicAdmissionRequestSchema.parse({
+        capsules,
+        totalOrder,
+        bounds,
+      });
+
+      // Phase 1: Merge and detect conflicts
+      const mergeResult = mergeCapsules(request.capsules, request.totalOrder);
+
+      // Check if all capsules were admitted (no conflicts)
+      if (mergeResult.denied.length > 0) {
+        // Some capsules denied - reject entire batch
+        return AtomicAdmissionResultSchema.parse({
+          success: false,
+          admitted: [],
+          denied: mergeResult.denied,
+          conflict_receipts: mergeResult.conflict_receipts,
+          errors: ['Conflict detected - admission denied to maintain atomicity'],
+        });
+      }
+
+      // Phase 2: Create transaction for admission
+      const operations = mergeResult.admitted.map(capsuleId => {
+        const capsule = request.capsules.find(c => c.id === capsuleId);
+        return {
+          id: `admit_${capsuleId}`,
+          type: 'add_capsule',
+          data: capsule,
+        };
+      });
+
+      const tx = this.txManager.begin(operations);
+
+      // Phase 3: Prepare transaction
+      const prepareResult = await this.txManager.prepare(tx.id);
+
+      if (!prepareResult.success) {
+        // Prepare failed - abort
+        return AtomicAdmissionResultSchema.parse({
+          success: false,
+          admitted: [],
+          denied: mergeResult.admitted,
+          conflict_receipts: [],
+          errors: prepareResult.errors,
+        });
+      }
+
+      // Phase 4: Commit transaction
+      const commitResult = await this.txManager.commit(tx.id);
+
+      if (!commitResult.success) {
+        // Commit failed - rollback
+        await this.txManager.rollback(tx.id);
+
+        // Log rollback
+        await this.rollbackLog.append(
+          tx.id,
+          prepareResult.undoOps,
+          tx.hash
+        );
+
+        return AtomicAdmissionResultSchema.parse({
+          success: false,
+          admitted: [],
+          denied: mergeResult.admitted,
+          conflict_receipts: [],
+          errors: commitResult.errors,
+        });
+      }
+
+      // Success - store admitted capsules
+      for (const capsuleId of mergeResult.admitted) {
+        const capsule = request.capsules.find(c => c.id === capsuleId);
+        this.admittedCapsules.set(capsuleId, capsule);
+      }
+
+      return AtomicAdmissionResultSchema.parse({
+        success: true,
+        transaction_id: tx.id,
+        admitted: mergeResult.admitted,
+        denied: [],
+        conflict_receipts: mergeResult.conflict_receipts,
+        receipts: commitResult.receipts,
+      });
+    } catch (error) {
+      return AtomicAdmissionResultSchema.parse({
+        success: false,
+        admitted: [],
+        denied: capsules.map(c => c.id),
+        conflict_receipts: [],
+        errors: [error.message],
+      });
+    }
+  }
+
+  /**
+   * Admit single capsule (convenience method)
+   *
+   * @param {any} capsule - Capsule to admit
+   * @param {any} totalOrder - Conflict resolution rules
+   * @returns {Promise<AtomicAdmissionResult>} Admission result
+   */
+  async admitCapsule(capsule, totalOrder) {
+    return this.admitCapsules([capsule], totalOrder);
+  }
+
+  /**
+   * Rollback a transaction by ID
+   *
+   * @param {string} transactionId - Transaction ID to rollback
+   * @returns {Promise<{success: boolean, operations_undone: number}>} Rollback result
+   */
+  async rollbackTransaction(transactionId) {
+    // Rollback using transaction manager
+    const result = await this.txManager.rollback(transactionId);
+
+    // Remove rolled back capsules from admitted set
+    const tx = this.txManager.getTransaction(transactionId);
+    if (tx) {
+      for (const op of tx.operations) {
+        if (op.type === 'add_capsule' && op.data?.id) {
+          this.admittedCapsules.delete(op.data.id);
+        }
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Get all admitted capsules
+   * @returns {any[]} Admitted capsules
+   */
+  getAdmittedCapsules() {
+    return Array.from(this.admittedCapsules.values());
+  }
+
+  /**
+   * Check if capsule is admitted
+   *
+   * @param {string} capsuleId - Capsule ID
+   * @returns {boolean} True if admitted
+   */
+  isAdmitted(capsuleId) {
+    return this.admittedCapsules.has(capsuleId);
+  }
+
+  /**
+   * Handle rollback event
+   * @private
+   */
+  _handleRollback(event) {
+    console.log(`Transaction ${event.transaction_id} rolled back: ${event.operations_undone} operations undone`);
+  }
+
+  /**
+   * Reset state (for testing)
+   */
+  reset() {
+    this.txManager.reset();
+    this.admittedCapsules.clear();
+  }
+}
+
+// ============================================================================
+// Cascading Rollback Support
+// ============================================================================
+
+/**
+ * Rollback transaction and all dependent transactions
+ *
+ * @param {AtomicAdmissionGate} gate - Admission gate
+ * @param {string} transactionId - Root transaction to rollback
+ * @returns {Promise<{success: boolean, rolled_back: string[]}>} Rollback result
+ */
+export async function cascadingRollback(gate, transactionId) {
+  const rolledBack = [];
+  const toRollback = [transactionId];
+
+  while (toRollback.length > 0) {
+    const txId = toRollback.pop();
+
+    // Rollback this transaction
+    const result = await gate.rollbackTransaction(txId);
+
+    if (result.success) {
+      rolledBack.push(txId);
+
+      // Find dependent transactions (those with this tx as parent)
+      const allTx = gate.txManager.getAllTransactions();
+      const dependents = allTx.filter(tx => tx.parentHash === txId);
+
+      for (const depTx of dependents) {
+        toRollback.push(depTx.id);
+      }
+    }
+  }
+
+  return {
+    success: true,
+    rolled_back: rolledBack,
+  };
+}
+
+// ============================================================================
+// Exports
+// ============================================================================
+
+export default AtomicAdmissionGate;