@nahisaho/yata-global 1.6.6

package/dist/kgpr/merge-engine.d.ts

@@ -0,0 +1,269 @@
+/**
+ * Knowledge Graph Pull Request (KGPR) - Merge Engine
+ *
+ * Handles conflict detection, diff application, and merge audit logging
+ *
+ * @packageDocumentation
+ * @module @nahisaho/yata-global/kgpr
+ *
+ * @see REQ-KGPR-004
+ * @see TSK-KGPR-006
+ */
+import { EventEmitter } from 'events';
+import type { KGPR, KGPRDiff, EntityChange, RelationshipChange } from './types.js';
+/**
+ * Conflict type
+ */
+export type ConflictType = 'entity_exists' | 'entity_modified' | 'entity_deleted' | 'relationship_exists' | 'relationship_broken' | 'circular_dependency' | 'schema_violation';
+/**
+ * Conflict severity
+ */
+export type ConflictSeverity = 'error' | 'warning' | 'info';
+/**
+ * Merge conflict
+ */
+export interface MergeConflict {
+    /** Conflict ID */
+    id: string;
+    /** Conflict type */
+    type: ConflictType;
+    /** Severity */
+    severity: ConflictSeverity;
+    /** Human-readable message */
+    message: string;
+    /** Local entity/relationship ID */
+    localId: string;
+    /** Global entity/relationship ID (if exists) */
+    globalId?: string;
+    /** Entity/relationship name */
+    name: string;
+    /** Namespace */
+    namespace: string;
+    /** Whether this is an entity or relationship */
+    itemType: 'entity' | 'relationship';
+    /** Local value */
+    localValue?: Record<string, unknown>;
+    /** Global value */
+    globalValue?: Record<string, unknown>;
+    /** Suggested resolution */
+    suggestedResolution?: ConflictResolution;
+}
+/**
+ * Conflict resolution strategy
+ */
+export type ConflictResolution = 'use_local' | 'use_global' | 'merge' | 'skip' | 'rename';
+/**
+ * Merge options
+ */
+export interface MergeOptions {
+    /** How to handle conflicts */
+    conflictStrategy?: 'fail' | 'skip_conflicts' | 'force';
+    /** Custom conflict resolutions by ID */
+    resolutions?: Map<string, ConflictResolution>;
+    /** Dry run (don't actually apply) */
+    dryRun?: boolean;
+    /** Merger user ID */
+    mergerId?: string;
+    /** Merger user name */
+    mergerName?: string;
+}
+/**
+ * Merge result
+ */
+export interface MergeResult {
+    /** Whether merge was successful */
+    success: boolean;
+    /** KGPR ID */
+    kgprId: string;
+    /** Conflicts found */
+    conflicts: MergeConflict[];
+    /** Applied changes */
+    applied: {
+        entitiesAdded: number;
+        entitiesUpdated: number;
+        entitiesDeleted: number;
+        relationshipsAdded: number;
+        relationshipsUpdated: number;
+        relationshipsDeleted: number;
+    };
+    /** Skipped changes */
+    skipped: {
+        entities: string[];
+        relationships: string[];
+    };
+    /** Audit log entry */
+    auditLog: MergeAuditLog;
+    /** Error message (if failed) */
+    error?: string;
+}
+/**
+ * Merge audit log entry
+ */
+export interface MergeAuditLog {
+    /** Log ID */
+    id: string;
+    /** KGPR ID */
+    kgprId: string;
+    /** KGPR title */
+    kgprTitle: string;
+    /** KGPR author */
+    kgprAuthor: string;
+    /** Merger ID */
+    mergerId: string;
+    /** Merger name */
+    mergerName: string;
+    /** Operation type */
+    operation: 'merge' | 'dry_run' | 'conflict_check';
+    /** Result */
+    result: 'success' | 'failed' | 'partial';
+    /** Timestamp */
+    timestamp: Date;
+    /** Changes applied */
+    changes: {
+        entitiesAdded: EntityChange[];
+        entitiesUpdated: EntityChange[];
+        entitiesDeleted: EntityChange[];
+        relationshipsAdded: RelationshipChange[];
+        relationshipsUpdated: RelationshipChange[];
+        relationshipsDeleted: RelationshipChange[];
+    };
+    /** Conflicts */
+    conflicts: MergeConflict[];
+    /** Resolutions applied */
+    resolutions: Array<{
+        conflictId: string;
+        resolution: ConflictResolution;
+    }>;
+    /** Duration (ms) */
+    durationMs: number;
+}
+/**
+ * Global Knowledge Graph interface (for reading/writing to global KG)
+ */
+export interface GlobalKnowledgeGraph {
+    /** Check if entity exists */
+    entityExists(name: string, namespace: string): Promise<boolean>;
+    /** Get entity by name and namespace */
+    getEntity(name: string, namespace: string): Promise<{
+        id: string;
+        name: string;
+        type: string;
+        namespace: string;
+        version?: number;
+        metadata?: Record<string, unknown>;
+        updatedAt: Date;
+    } | null>;
+    /** Check if relationship exists */
+    relationshipExists(sourceName: string, sourceNamespace: string, targetName: string, targetNamespace: string, type: string): Promise<boolean>;
+    /** Add entity */
+    addEntity(entity: {
+        name: string;
+        type: string;
+        namespace: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<string>;
+    /** Update entity */
+    updateEntity(name: string, namespace: string, updates: Record<string, unknown>): Promise<void>;
+    /** Delete entity */
+    deleteEntity(name: string, namespace: string): Promise<void>;
+    /** Add relationship */
+    addRelationship(rel: {
+        sourceName: string;
+        sourceNamespace: string;
+        targetName: string;
+        targetNamespace: string;
+        type: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<string>;
+    /** Delete relationship */
+    deleteRelationship(sourceName: string, sourceNamespace: string, targetName: string, targetNamespace: string, type: string): Promise<void>;
+    /** Check for circular dependencies */
+    wouldCreateCycle?(sourceName: string, sourceNamespace: string, targetName: string, targetNamespace: string, relationshipType: string): Promise<boolean>;
+}
+/**
+ * MergeEngine events
+ */
+export interface MergeEngineEvents {
+    'merge:started': {
+        kgprId: string;
+    };
+    'merge:conflict': {
+        conflict: MergeConflict;
+    };
+    'merge:progress': {
+        phase: string;
+        progress: number;
+        total: number;
+    };
+    'merge:completed': {
+        result: MergeResult;
+    };
+    'merge:failed': {
+        kgprId: string;
+        error: string;
+    };
+    'error': Error;
+}
+/**
+ * Merge Engine
+ *
+ * Handles conflict detection, diff application, and merge audit logging
+ *
+ * @example
+ * ```typescript
+ * const engine = new MergeEngine({ globalKG });
+ * const conflicts = await engine.checkConflicts(kgpr.diff);
+ * if (conflicts.length === 0) {
+ *   const result = await engine.merge(kgpr);
+ * }
+ * ```
+ */
+export declare class MergeEngine extends EventEmitter {
+    private globalKG;
+    private auditLogs;
+    private conflictIdCounter;
+    constructor(options?: {
+        globalKG?: GlobalKnowledgeGraph;
+    });
+    /**
+     * Connect to global knowledge graph
+     */
+    connectGlobalKG(globalKG: GlobalKnowledgeGraph): void;
+    /**
+     * Generate unique conflict ID
+     */
+    private generateConflictId;
+    /**
+     * Generate unique audit log ID
+     */
+    private generateAuditLogId;
+    /**
+     * Check for conflicts in a diff
+     */
+    checkConflicts(diff: KGPRDiff): Promise<MergeConflict[]>;
+    /**
+     * Merge a KGPR into the global knowledge graph
+     */
+    merge(kgpr: KGPR, options?: MergeOptions): Promise<MergeResult>;
+    /**
+     * Apply diff to global KG
+     */
+    private applyDiff;
+    /**
+     * Create an audit log entry
+     */
+    private createAuditLog;
+    /**
+     * Get all audit logs
+     */
+    getAuditLogs(): MergeAuditLog[];
+    /**
+     * Get audit logs for a specific KGPR
+     */
+    getAuditLogsForKGPR(kgprId: string): MergeAuditLog[];
+    /**
+     * Clear audit logs
+     */
+    clearAuditLogs(): void;
+}
+//# sourceMappingURL=merge-engine.d.ts.map

package/dist/kgpr/merge-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge-engine.d.ts","sourceRoot":"","sources":["../../src/kgpr/merge-engine.ts"],"names":[],"mappings":"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"}