refactor(knowledge): extract graph module

.tegami/knowledge-graph-module.md

@@ -0,0 +1,11 @@
+---
+packages:
+  orgmemory: patch
+subject: Isolate Knowledge Graph lifecycle and processing boundaries
+---
+
+## Improvements
+
+Knowledge Graph indexing, processing profiles, lifecycle operations, curation,
+exploration, and export now share an explicit module boundary, reducing coupling
+and making future graph changes safer to verify and release.

apps/api/src/main/java/com/orgmemory/api/OrgMemoryApiApplication.java

@@ -2,8 +2,8 @@
 
 import com.orgmemory.core.knowledge.sourceledger.SourceIngestionProperties;
 
-import com.orgmemory.core.knowledge.GraphExplorerProperties;
-import com.orgmemory.core.knowledge.GraphProcessingProperties;
+import com.orgmemory.core.knowledge.graph.GraphExplorerProperties;
+import com.orgmemory.core.knowledge.graph.GraphProcessingProperties;
 import com.orgmemory.core.knowledge.KnowledgeEmbeddingProperties;
 import com.orgmemory.core.knowledge.KnowledgeRetrievalProperties;
 import com.orgmemory.core.shared.secret.SecretCipherProperties;

apps/api/src/main/java/com/orgmemory/api/knowledge/KnowledgeAssetLifecycleController.java

@@ -1,8 +1,8 @@
 package com.orgmemory.api.knowledge;
 
 import com.orgmemory.api.security.CurrentActorProvider;
-import com.orgmemory.core.knowledge.GraphIndexJobView;
-import com.orgmemory.core.knowledge.GraphIndexLifecycleService;
+import com.orgmemory.core.knowledge.graph.GraphIndexJobView;
+import com.orgmemory.core.knowledge.graph.GraphIndexLifecycleService;
 import com.orgmemory.core.knowledge.asset.KnowledgeAssetLifecycleService;
 import com.orgmemory.core.knowledge.asset.KnowledgeAssetRef;
 import io.swagger.v3.oas.annotations.Operation;

apps/api/src/main/java/com/orgmemory/api/knowledge/KnowledgeGraphExplorerController.java

@@ -1,8 +1,8 @@
 package com.orgmemory.api.knowledge;
 
 import com.orgmemory.api.security.CurrentActorProvider;
-import com.orgmemory.core.knowledge.KnowledgeGraphExplorerService;
-import com.orgmemory.core.knowledge.KnowledgeGraphView;
+import com.orgmemory.core.knowledge.graph.KnowledgeGraphExplorerService;
+import com.orgmemory.core.knowledge.graph.KnowledgeGraphView;
 import io.swagger.v3.oas.annotations.Operation;
 import jakarta.servlet.http.HttpServletResponse;
 import java.util.UUID;

apps/api/src/main/java/com/orgmemory/api/knowledge/KnowledgeGraphManagementController.java

@@ -2,9 +2,9 @@
 
 import com.orgmemory.api.ApiRequestException;
 import com.orgmemory.api.security.CurrentActorProvider;
-import com.orgmemory.core.knowledge.KnowledgeGraphCurationCommand;
-import com.orgmemory.core.knowledge.KnowledgeGraphCurationService;
-import com.orgmemory.core.knowledge.KnowledgeGraphExportService;
+import com.orgmemory.core.knowledge.graph.KnowledgeGraphCurationCommand;
+import com.orgmemory.core.knowledge.graph.KnowledgeGraphCurationService;
+import com.orgmemory.core.knowledge.graph.KnowledgeGraphExportService;
 import com.orgmemory.core.organization.CurrentActor;
 import com.orgmemory.graphrag.curation.GraphCurationRecord;
 import com.orgmemory.graphrag.curation.GraphIdentityKind;

apps/api/src/test/java/com/orgmemory/api/knowledge/KnowledgeGraphManagementControllerTests.java

@@ -7,9 +7,9 @@
 import static org.mockito.Mockito.when;
 
 import com.orgmemory.api.security.CurrentActorProvider;
-import com.orgmemory.core.knowledge.KnowledgeGraphCurationCommand;
-import com.orgmemory.core.knowledge.KnowledgeGraphCurationService;
-import com.orgmemory.core.knowledge.KnowledgeGraphExportService;
+import com.orgmemory.core.knowledge.graph.KnowledgeGraphCurationCommand;
+import com.orgmemory.core.knowledge.graph.KnowledgeGraphCurationService;
+import com.orgmemory.core.knowledge.graph.KnowledgeGraphExportService;
 import com.orgmemory.core.organization.CurrentActor;
 import java.util.UUID;
 import org.junit.jupiter.api.Test;

apps/worker/src/main/java/com/orgmemory/worker/OrgMemoryWorkerApplication.java

@@ -3,8 +3,8 @@
 import com.orgmemory.core.knowledge.sourceledger.SourceIngestionProperties;
 
 import com.orgmemory.core.knowledge.CanonicalHybridKnowledgeSearch;
-import com.orgmemory.core.knowledge.GraphProcessingProperties;
-import com.orgmemory.core.knowledge.KnowledgeGraphExplorerConfiguration;
+import com.orgmemory.core.knowledge.graph.GraphProcessingProperties;
+import com.orgmemory.core.knowledge.graph.KnowledgeGraphExplorerConfiguration;
 import com.orgmemory.core.knowledge.KnowledgeRetrievalProperties;
 import com.orgmemory.core.shared.secret.SecretCipherProperties;
 import com.orgmemory.worker.authorization.AssetAuthorizationConvergenceProperties;

apps/worker/src/main/java/com/orgmemory/worker/graph/GraphIndexingProcessor.java

@@ -3,10 +3,10 @@
 import com.orgmemory.core.ai.AiRoute;
 import com.orgmemory.core.ai.AiRouteResolver;
 import com.orgmemory.core.ai.AiWorkload;
-import com.orgmemory.core.knowledge.ClaimedGraphIndex;
-import com.orgmemory.core.knowledge.GraphIndexChunk;
-import com.orgmemory.core.knowledge.GraphIndexingCoordinator;
-import com.orgmemory.core.knowledge.GraphIndexingStoppedException;
+import com.orgmemory.core.knowledge.graph.ClaimedGraphIndex;
+import com.orgmemory.core.knowledge.graph.GraphIndexChunk;
+import com.orgmemory.core.knowledge.graph.GraphIndexingCoordinator;
+import com.orgmemory.core.knowledge.graph.GraphIndexingStoppedException;
 import com.orgmemory.graphrag.indexing.ExtractedChunk;
 import com.orgmemory.graphrag.indexing.GraphContributionAssembler;
 import com.orgmemory.graphrag.indexing.LightRagEmbeddingPayloads;

apps/worker/src/main/java/com/orgmemory/worker/graph/GraphPublicationCommitter.java

@@ -1,8 +1,8 @@
 package com.orgmemory.worker.graph;
 
-import com.orgmemory.core.knowledge.ClaimedGraphIndex;
-import com.orgmemory.core.knowledge.GraphIndexChunk;
-import com.orgmemory.core.knowledge.GraphIndexingCoordinator;
+import com.orgmemory.core.knowledge.graph.ClaimedGraphIndex;
+import com.orgmemory.core.knowledge.graph.GraphIndexChunk;
+import com.orgmemory.core.knowledge.graph.GraphIndexingCoordinator;
 import com.orgmemory.graphrag.cache.CanonicalCacheKeyHasher;
 import com.orgmemory.graphrag.cache.ModelInvocationCache;
 import com.orgmemory.graphrag.cache.RetrievalResultCache;

apps/worker/src/test/java/com/orgmemory/worker/graph/GraphIndexingProcessorTests.java

@@ -19,12 +19,12 @@
 import com.orgmemory.core.ai.AiRoute;
 import com.orgmemory.core.ai.AiRouteResolver;
 import com.orgmemory.core.ai.AiWorkload;
-import com.orgmemory.core.knowledge.ClaimedGraphIndex;
+import com.orgmemory.core.knowledge.graph.ClaimedGraphIndex;
 import com.orgmemory.core.knowledge.EmbeddingDistanceMetric;
 import com.orgmemory.core.knowledge.EmbeddingProfileRef;
-import com.orgmemory.core.knowledge.GraphIndexChunk;
-import com.orgmemory.core.knowledge.GraphIndexingCoordinator;
-import com.orgmemory.core.knowledge.GraphProcessingProfileRef;
+import com.orgmemory.core.knowledge.graph.GraphIndexChunk;
+import com.orgmemory.core.knowledge.graph.GraphIndexingCoordinator;
+import com.orgmemory.core.knowledge.graph.GraphProcessingProfileRef;
 import com.orgmemory.graphrag.extraction.LightRagExtractionPrompt;
 import com.orgmemory.graphrag.model.ExtractedEntity;
 import com.orgmemory.graphrag.model.ExtractedRelation;

apps/worker/src/test/java/com/orgmemory/worker/graph/GraphPublicationCommitterTests.java

@@ -9,12 +9,12 @@
 import static org.mockito.Mockito.verify;
 import static org.mockito.Mockito.when;
 
-import com.orgmemory.core.knowledge.ClaimedGraphIndex;
+import com.orgmemory.core.knowledge.graph.ClaimedGraphIndex;
 import com.orgmemory.core.knowledge.EmbeddingDistanceMetric;
 import com.orgmemory.core.knowledge.EmbeddingProfileRef;
-import com.orgmemory.core.knowledge.GraphIndexChunk;
-import com.orgmemory.core.knowledge.GraphIndexingCoordinator;
-import com.orgmemory.core.knowledge.GraphProcessingProfileRef;
+import com.orgmemory.core.knowledge.graph.GraphIndexChunk;
+import com.orgmemory.core.knowledge.graph.GraphIndexingCoordinator;
+import com.orgmemory.core.knowledge.graph.GraphProcessingProfileRef;
 import com.orgmemory.graphrag.cache.ModelInvocationCache;
 import com.orgmemory.graphrag.cache.RetrievalResultCache;
 import com.orgmemory.graphrag.model.FloatVector;

core/src/main/java/com/orgmemory/core/knowledge/EmbeddingProfile.java

@@ -41,7 +41,7 @@ public class EmbeddingProfile {
     protected EmbeddingProfile() {
     }
 
-    EmbeddingProfileRef toRef() {
+    public EmbeddingProfileRef toRef() {
         return new EmbeddingProfileRef(
                 id,
                 organizationId,

core/src/main/java/com/orgmemory/core/knowledge/EmbeddingProfileRepository.java

@@ -4,7 +4,7 @@
 import java.util.UUID;
 import org.springframework.data.jpa.repository.JpaRepository;
 
-interface EmbeddingProfileRepository extends JpaRepository<EmbeddingProfile, UUID> {
+public interface EmbeddingProfileRepository extends JpaRepository<EmbeddingProfile, UUID> {
 
     Optional<EmbeddingProfile> findByOrganizationIdAndProfileKey(UUID organizationId, String profileKey);
 

core/src/main/java/com/orgmemory/core/knowledge/KnowledgeEvidenceScopeResolver.java

@@ -34,7 +34,7 @@
  * permission-aware retrieval, graph and citation use cases.
  */
 @Service
-class KnowledgeEvidenceScopeResolver {
+public class KnowledgeEvidenceScopeResolver {
 
     private static final PermissionKey CAN_VIEW = PermissionKey.of("can_view");
     private static final String RESOURCE_TYPE = "knowledge_asset";
@@ -65,7 +65,7 @@ class KnowledgeEvidenceScopeResolver {
     }
 
     @Transactional(readOnly = true)
-    ResolvedKnowledgeEvidenceScope resolve(
+    public ResolvedKnowledgeEvidenceScope resolve(
             CurrentActor actor,
             String expectedAuthorizationModelId) {
         Objects.requireNonNull(actor, "actor");

core/src/main/java/com/orgmemory/core/knowledge/KnowledgeEvidenceScopeUnavailableException.java

@@ -1,11 +1,11 @@
 package com.orgmemory.core.knowledge;
 
-final class KnowledgeEvidenceScopeUnavailableException extends RuntimeException {
+public final class KnowledgeEvidenceScopeUnavailableException extends RuntimeException {
 
     private final String reasonCode;
     private final String policyVersion;
 
-    KnowledgeEvidenceScopeUnavailableException(
+    public KnowledgeEvidenceScopeUnavailableException(
             String reasonCode,
             String policyVersion) {
         super("Knowledge evidence authorization scope is unavailable");

core/src/main/java/com/orgmemory/core/knowledge/ResolvedKnowledgeEvidenceScope.java

@@ -9,7 +9,7 @@
 import java.util.Set;
 import java.util.UUID;
 
-record ResolvedKnowledgeEvidenceScope(
+public record ResolvedKnowledgeEvidenceScope(
         UUID organizationId,
         UUID actorUserId,
         UUID actorDepartmentId,
@@ -19,7 +19,7 @@ record ResolvedKnowledgeEvidenceScope(
         Map<UUID, Set<UUID>> assetIdsByKnowledgeSpace,
         Map<UUID, Long> aclGenerationByKnowledgeSpace) {
 
-    ResolvedKnowledgeEvidenceScope {
+    public ResolvedKnowledgeEvidenceScope {
         Objects.requireNonNull(organizationId, "organizationId");
         Objects.requireNonNull(actorUserId, "actorUserId");
         authorizationModelId = required(
@@ -42,17 +42,17 @@ record ResolvedKnowledgeEvidenceScope(
         }
     }
 
-    Set<UUID> allAssetIds() {
+    public Set<UUID> allAssetIds() {
         LinkedHashSet<UUID> all = new LinkedHashSet<>();
         assetIdsByKnowledgeSpace.values().forEach(all::addAll);
         return Set.copyOf(all);
     }
 
-    Set<UUID> knowledgeSpaceIds() {
+    public Set<UUID> knowledgeSpaceIds() {
         return assetIdsByKnowledgeSpace.keySet();
     }
 
-    SecureKnowledgeRetrievalStore.RetrievalScope toRetrievalScope() {
+    public SecureKnowledgeRetrievalStore.RetrievalScope toRetrievalScope() {
         return new SecureKnowledgeRetrievalStore.RetrievalScope(
                 organizationId,
                 actorUserId,
@@ -63,7 +63,7 @@ SecureKnowledgeRetrievalStore.RetrievalScope toRetrievalScope() {
                 evaluatedAt);
     }
 
-    AuthorizedEvidenceScope forKnowledgeSpace(UUID knowledgeSpaceId) {
+    public AuthorizedEvidenceScope forKnowledgeSpace(UUID knowledgeSpaceId) {
         Objects.requireNonNull(knowledgeSpaceId, "knowledgeSpaceId");
         return new AuthorizedEvidenceScope(
                 organizationId,

core/src/main/java/com/orgmemory/core/knowledge/SecureKnowledgeRetrievalStore.java

@@ -272,7 +272,7 @@ List<SecureRetrievalCandidate> semantic(
         return jdbc.query(sql, parameters, SecureKnowledgeRetrievalStore::mapCandidate);
     }
 
-    List<SecureRetrievalCandidate> recheck(
+    public List<SecureRetrievalCandidate> recheck(
             RetrievalScope scope,
             Collection<UUID> chunkIds) {
         if (chunkIds.isEmpty()) {

core/src/main/java/com/orgmemory/core/knowledge/SecureRetrievalCandidate.java

@@ -2,7 +2,7 @@
 
 import java.util.UUID;
 
-record SecureRetrievalCandidate(
+public record SecureRetrievalCandidate(
         UUID organizationId,
         UUID chunkId,
         UUID knowledgeAssetId,

core/src/main/java/com/orgmemory/core/knowledge/asset/KnowledgeChunkProjection.java

@@ -0,0 +1,30 @@
+package com.orgmemory.core.knowledge.asset;
+
+import com.orgmemory.graphrag.model.FloatVector;
+import java.util.Objects;
+import java.util.UUID;
+
+public record KnowledgeChunkProjection(
+        UUID id,
+        int index,
+        String content,
+        String heading,
+        int tokenCount,
+        FloatVector embedding) {
+
+    public KnowledgeChunkProjection {
+        Objects.requireNonNull(id, "id");
+        if (index < 0) {
+            throw new IllegalArgumentException("index must be non-negative");
+        }
+        content = Objects.requireNonNull(content, "content").strip();
+        if (content.isEmpty()) {
+            throw new IllegalArgumentException("content must not be blank");
+        }
+        heading = heading == null || heading.isBlank() ? null : heading.strip();
+        if (tokenCount < 0) {
+            throw new IllegalArgumentException("tokenCount must be non-negative");
+        }
+        Objects.requireNonNull(embedding, "embedding");
+    }
+}

core/src/main/java/com/orgmemory/core/knowledge/asset/KnowledgeChunkProjectionStore.java

@@ -1,7 +1,6 @@
 package com.orgmemory.core.knowledge.asset;
 
 import com.orgmemory.core.knowledge.EmbeddingProfileRef;
-import com.orgmemory.core.knowledge.GraphIndexChunk;
 import com.orgmemory.core.knowledge.PgVectorLiteral;
 
 import java.sql.Types;
@@ -149,7 +148,7 @@ public int activate(
     }
 
     @Transactional(readOnly = true)
-    public List<GraphIndexChunk> loadActive(
+    public List<KnowledgeChunkProjection> loadActive(
             UUID organizationId,
             UUID sourceRevisionId,
             UUID knowledgeAssetId,
@@ -173,7 +172,7 @@ public List<GraphIndexChunk> loadActive(
                         .addValue("knowledgeAssetId", knowledgeAssetId)
                         .addValue("knowledgeAssetVersionId", knowledgeAssetVersionId)
                         .addValue("projectionGeneration", projectionGeneration),
-                (resultSet, rowNumber) -> new GraphIndexChunk(
+                (resultSet, rowNumber) -> new KnowledgeChunkProjection(
                         resultSet.getObject("id", UUID.class),
                         resultSet.getInt("chunk_index"),
                         resultSet.getString("content"),

core/src/main/java/com/orgmemory/core/knowledge/connector/ConnectorSourceRevisionCoordinator.java

@@ -1,7 +1,7 @@
 package com.orgmemory.core.knowledge.connector;
 
 import com.orgmemory.core.knowledge.EmbeddingProfileRef;
-import com.orgmemory.core.knowledge.GraphIndexJobQueue;
+import com.orgmemory.core.knowledge.graph.GraphIndexJobQueue;
 import com.orgmemory.core.knowledge.asset.KnowledgeAssetRef;
 
 

core/src/main/java/com/orgmemory/core/knowledge/ClaimedGraphIndex.java → core/src/main/java/com/orgmemory/core/knowledge/graph/ClaimedGraphIndex.java

@@ -1,5 +1,6 @@
-package com.orgmemory.core.knowledge;
+package com.orgmemory.core.knowledge.graph;
 
+import com.orgmemory.core.knowledge.EmbeddingProfileRef;
 import java.util.List;
 import java.util.Objects;
 import java.util.UUID;

core/src/main/java/com/orgmemory/core/knowledge/GraphExplorerProperties.java → core/src/main/java/com/orgmemory/core/knowledge/graph/GraphExplorerProperties.java

@@ -1,4 +1,4 @@
-package com.orgmemory.core.knowledge;
+package com.orgmemory.core.knowledge.graph;
 
 import org.springframework.boot.context.properties.ConfigurationProperties;
 

core/src/main/java/com/orgmemory/core/knowledge/GraphIndexChunk.java → core/src/main/java/com/orgmemory/core/knowledge/graph/GraphIndexChunk.java

@@ -1,4 +1,4 @@
-package com.orgmemory.core.knowledge;
+package com.orgmemory.core.knowledge.graph;
 
 import com.orgmemory.graphrag.model.FloatVector;
 import java.util.Objects;

core/src/main/java/com/orgmemory/core/knowledge/GraphIndexJob.java → core/src/main/java/com/orgmemory/core/knowledge/graph/GraphIndexJob.java

@@ -1,5 +1,6 @@
-package com.orgmemory.core.knowledge;
+package com.orgmemory.core.knowledge.graph;
 
+import com.orgmemory.core.knowledge.SourceFailureMessage;
 import com.orgmemory.core.shared.BaseEntity;
 import jakarta.persistence.Column;
 import jakarta.persistence.Entity;

core/src/main/java/com/orgmemory/core/knowledge/GraphIndexJobQueue.java → core/src/main/java/com/orgmemory/core/knowledge/graph/GraphIndexJobQueue.java

@@ -1,4 +1,4 @@
-package com.orgmemory.core.knowledge;
+package com.orgmemory.core.knowledge.graph;
 
 import com.orgmemory.core.knowledge.asset.KnowledgeAssetRef;
 import com.orgmemory.core.knowledge.asset.KnowledgeAssetVersion;

core/src/main/java/com/orgmemory/core/knowledge/GraphIndexJobRepository.java → core/src/main/java/com/orgmemory/core/knowledge/graph/GraphIndexJobRepository.java

@@ -1,4 +1,4 @@
-package com.orgmemory.core.knowledge;
+package com.orgmemory.core.knowledge.graph;
 
 import java.time.Instant;
 import java.util.Optional;

core/src/main/java/com/orgmemory/core/knowledge/GraphIndexJobStatus.java → core/src/main/java/com/orgmemory/core/knowledge/graph/GraphIndexJobStatus.java

@@ -1,4 +1,4 @@
-package com.orgmemory.core.knowledge;
+package com.orgmemory.core.knowledge.graph;
 
 enum GraphIndexJobStatus {
     PENDING,

core/src/main/java/com/orgmemory/core/knowledge/GraphIndexJobView.java → core/src/main/java/com/orgmemory/core/knowledge/graph/GraphIndexJobView.java

@@ -1,4 +1,4 @@
-package com.orgmemory.core.knowledge;
+package com.orgmemory.core.knowledge.graph;
 
 import java.time.Instant;
 import java.util.UUID;

core/src/main/java/com/orgmemory/core/knowledge/GraphIndexLifecycleService.java → core/src/main/java/com/orgmemory/core/knowledge/graph/GraphIndexLifecycleService.java

@@ -1,4 +1,4 @@
-package com.orgmemory.core.knowledge;
+package com.orgmemory.core.knowledge.graph;
 
 import com.orgmemory.core.knowledge.asset.KnowledgeAsset;
 import com.orgmemory.core.knowledge.asset.KnowledgeAssetRef;