refactor(knowledge): publish retrieval adapter contracts

ARCHITECTURE.md

@@ -169,9 +169,12 @@ evidence snapshot and exact current governing-evidence decision through the
 Retrieval-owned `GraphEvidenceVerifier`; Graph does not import Retrieval scope
 resolution, candidate, or store implementation types. Verified snapshots reject
 unknown Knowledge Spaces, and canonical evidence rechecks carry only the assets
-authorized for the requested Space. Retrieval remains
-explicitly open while its remaining sibling adapters are replaced by
-intentional APIs. The
+authorized for the requested Space. API and Worker inject interfaces for the
+canonical/GraphRAG engines, citation/source opening, authorization inspection,
+and embedding-profile resolution; full evidence-scope resolution plus the
+default and JDBC implementations are package-private. Retrieval remains explicitly open while
+its remaining concrete/persistence root types are internalized and its final
+dependency allowlist is proven. The
 provider-neutral object-storage port is exposed as the
 `knowledge::storage` named interface. Leased database jobs carry ingestion work
 across processes. A specific Knowledge Asset

apps/api/build.gradle.kts

@@ -33,6 +33,7 @@ dependencies {
     testImplementation("org.springframework.boot:spring-boot-starter-webmvc-test")
     testImplementation("org.springframework.security:spring-security-test")
     testImplementation("org.springframework.boot:spring-boot-testcontainers")
+    testImplementation("org.springframework.modulith:spring-modulith-starter-test")
     testImplementation("io.projectreactor:reactor-test")
     testImplementation("org.testcontainers:testcontainers-junit-jupiter")
     testImplementation("org.testcontainers:testcontainers-postgresql")

apps/api/src/main/java/com/orgmemory/api/admin/AdminPermissionController.java

@@ -14,7 +14,7 @@
 import com.orgmemory.core.organization.AppUser;
 import com.orgmemory.core.organization.CurrentActor;
 import com.orgmemory.core.knowledge.retrieval.AuthorizationResourceDirectory;
-import com.orgmemory.core.knowledge.retrieval.KnowledgeEvidenceScopeResolver;
+import com.orgmemory.core.knowledge.retrieval.KnowledgeAssetAccessInspector;
 import io.swagger.v3.oas.annotations.Operation;
 import java.time.Instant;
 import java.util.LinkedHashMap;
@@ -64,7 +64,7 @@ class AdminPermissionController {
     private final AdminAccessGuard guard;
     private final AccessExplanationService explanations;
     private final AuthorizationResourceDirectory resources;
-    private final KnowledgeEvidenceScopeResolver evidenceScopes;
+    private final KnowledgeAssetAccessInspector evidenceScopes;
     private final KnowledgeAssetRepository assets;
     private final KnowledgeAssetVersionRepository versions;
     private final KnowledgeSpaceQuery spaces;
@@ -73,7 +73,7 @@ class AdminPermissionController {
             AdminAccessGuard guard,
             AccessExplanationService explanations,
             AuthorizationResourceDirectory resources,
-            KnowledgeEvidenceScopeResolver evidenceScopes,
+            KnowledgeAssetAccessInspector evidenceScopes,
             KnowledgeAssetRepository assets,
             KnowledgeAssetVersionRepository versions,
             KnowledgeSpaceQuery spaces) {
@@ -211,7 +211,7 @@ private ExplainAccessResponse canonicalContentResponse(
             contentState = AccessState.UNKNOWN;
             contentReason = "NOT_EVALUATED_RELATIONSHIP_NOT_ALLOWED";
         } else {
-            KnowledgeEvidenceScopeResolver.AssetInspection content = evidenceScopes.inspectAsset(
+            KnowledgeAssetAccessInspector.AssetInspection content = evidenceScopes.inspectAsset(
                     subject,
                     assetId,
                     relationship.policyVersion(),

apps/api/src/test/java/com/orgmemory/api/RetrievalAdapterBoundaryTests.java

@@ -0,0 +1,47 @@
+package com.orgmemory.api;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+import com.tngtech.archunit.core.importer.ClassFileImporter;
+import com.tngtech.archunit.core.importer.ImportOption;
+import java.util.Set;
+import java.util.TreeSet;
+import org.junit.jupiter.api.Test;
+
+class RetrievalAdapterBoundaryTests {
+
+    @Test
+    void apiDependsOnlyOnIntentionalRetrievalContracts() {
+        var dependencies = new ClassFileImporter()
+                .withImportOption(ImportOption.Predefined.DO_NOT_INCLUDE_TESTS)
+                .importPackages("com.orgmemory.api")
+                .stream()
+                .flatMap(type -> type.getDirectDependenciesFromSelf().stream())
+                .map(dependency -> dependency.getTargetClass().getName())
+                .filter(name -> name.startsWith("com.orgmemory.core.knowledge.retrieval."))
+                .collect(TreeSet::new, Set::add, Set::addAll);
+
+        assertEquals(
+                Set.of(
+                        "com.orgmemory.core.knowledge.retrieval.AuthorizationResourceDirectory",
+                        "com.orgmemory.core.knowledge.retrieval.CanonicalHybridKnowledgeSearch",
+                        "com.orgmemory.core.knowledge.retrieval.CitationContent",
+                        "com.orgmemory.core.knowledge.retrieval.CitationContentService",
+                        "com.orgmemory.core.knowledge.retrieval.EmbeddingDistanceMetric",
+                        "com.orgmemory.core.knowledge.retrieval.EmbeddingProfileRef",
+                        "com.orgmemory.core.knowledge.retrieval.EmbeddingProfileRegistry",
+                        "com.orgmemory.core.knowledge.retrieval.EmbeddingProfileSpec",
+                        "com.orgmemory.core.knowledge.retrieval.GraphRagKnowledgeRetrievalService",
+                        "com.orgmemory.core.knowledge.retrieval.GraphRagRetrievalPolicy",
+                        "com.orgmemory.core.knowledge.retrieval.GraphRagRetrievalPolicy$RerankPolicy",
+                        "com.orgmemory.core.knowledge.retrieval.KnowledgeAssetAccessInspector",
+                        "com.orgmemory.core.knowledge.retrieval.KnowledgeAssetAccessInspector$AssetInspection",
+                        "com.orgmemory.core.knowledge.retrieval.KnowledgeEmbeddingProperties",
+                        "com.orgmemory.core.knowledge.retrieval.KnowledgeRetrievalProperties",
+                        "com.orgmemory.core.knowledge.retrieval.QueryEmbedding",
+                        "com.orgmemory.core.knowledge.retrieval.QueryEmbeddingPort",
+                        "com.orgmemory.core.knowledge.retrieval.SourceContent",
+                        "com.orgmemory.core.knowledge.retrieval.SourceContentService"),
+                dependencies);
+    }
+}

apps/worker/build.gradle.kts

@@ -20,6 +20,7 @@ dependencies {
     runtimeOnly("org.postgresql:postgresql")
 
     testImplementation("org.junit.jupiter:junit-jupiter")
+    testImplementation("org.springframework.modulith:spring-modulith-starter-test")
     testImplementation(libs.apache.poi.ooxml)
     testImplementation("org.springframework.boot:spring-boot-starter-webmvc-test")
     testImplementation("org.springframework.boot:spring-boot-testcontainers")

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

@@ -2,7 +2,7 @@
 
 import com.orgmemory.core.knowledge.sourceledger.SourceIngestionProperties;
 
-import com.orgmemory.core.knowledge.retrieval.CanonicalHybridKnowledgeSearch;
+import com.orgmemory.core.knowledge.retrieval.CanonicalHybridKnowledgeSearchConfiguration;
 import com.orgmemory.core.knowledge.graph.GraphProcessingProperties;
 import com.orgmemory.core.knowledge.graph.KnowledgeGraphExplorerConfiguration;
 import com.orgmemory.core.knowledge.retrieval.KnowledgeRetrievalProperties;
@@ -51,7 +51,7 @@
         excludeFilters = @ComponentScan.Filter(
                 type = FilterType.ASSIGNABLE_TYPE,
                 classes = {
-                        CanonicalHybridKnowledgeSearch.class,
+                        CanonicalHybridKnowledgeSearchConfiguration.class,
                         KnowledgeGraphExplorerConfiguration.class
                 }))
 public class OrgMemoryWorkerApplication {

apps/worker/src/test/java/com/orgmemory/worker/RetrievalAdapterBoundaryTests.java

@@ -0,0 +1,34 @@
+package com.orgmemory.worker;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+import com.tngtech.archunit.core.importer.ClassFileImporter;
+import com.tngtech.archunit.core.importer.ImportOption;
+import java.util.Set;
+import java.util.TreeSet;
+import org.junit.jupiter.api.Test;
+
+class RetrievalAdapterBoundaryTests {
+
+    @Test
+    void workerDependsOnlyOnIntentionalRetrievalContracts() {
+        var dependencies = new ClassFileImporter()
+                .withImportOption(ImportOption.Predefined.DO_NOT_INCLUDE_TESTS)
+                .importPackages("com.orgmemory.worker")
+                .stream()
+                .flatMap(type -> type.getDirectDependenciesFromSelf().stream())
+                .map(dependency -> dependency.getTargetClass().getName())
+                .filter(name -> name.startsWith("com.orgmemory.core.knowledge.retrieval."))
+                .collect(TreeSet::new, Set::add, Set::addAll);
+
+        assertEquals(
+                Set.of(
+                        "com.orgmemory.core.knowledge.retrieval.CanonicalHybridKnowledgeSearchConfiguration",
+                        "com.orgmemory.core.knowledge.retrieval.EmbeddingDistanceMetric",
+                        "com.orgmemory.core.knowledge.retrieval.EmbeddingProfileRef",
+                        "com.orgmemory.core.knowledge.retrieval.EmbeddingProfileRegistry",
+                        "com.orgmemory.core.knowledge.retrieval.EmbeddingProfileSpec",
+                        "com.orgmemory.core.knowledge.retrieval.KnowledgeRetrievalProperties"),
+                dependencies);
+    }
+}

apps/worker/src/test/java/com/orgmemory/worker/connector/ConnectorContentEditIntegrationTests.java

@@ -34,6 +34,7 @@
 import com.orgmemory.core.knowledge.connector.ConnectorMembershipMember;
 import com.orgmemory.core.knowledge.connector.ConnectorPermissionItem;
 import com.orgmemory.core.knowledge.retrieval.CanonicalHybridKnowledgeSearch;
+import com.orgmemory.core.knowledge.retrieval.CanonicalHybridKnowledgeSearchConfiguration;
 import com.orgmemory.core.knowledge.retrieval.KnowledgeRetrievalProperties;
 import com.orgmemory.core.knowledge.connector.ConnectorCaptureStatus;
 import com.orgmemory.core.knowledge.retrieval.QueryEmbeddingPort;
@@ -88,7 +89,7 @@
         "orgmemory.graph-rag.postgres.apache-age-mode=disabled",
         "orgmemory.connector.scheduling-enabled=false"
 })
-@Import(CanonicalHybridKnowledgeSearch.class)
+@Import(CanonicalHybridKnowledgeSearchConfiguration.class)
 @EnableConfigurationProperties(KnowledgeRetrievalProperties.class)
 @Testcontainers
 @DirtiesContext(classMode = DirtiesContext.ClassMode.AFTER_CLASS)

apps/worker/src/test/java/com/orgmemory/worker/connector/ConnectorIdentityTrustIntegrationTests.java

@@ -31,6 +31,7 @@
 import com.orgmemory.core.knowledge.connector.ConnectorMembershipMember;
 import com.orgmemory.core.knowledge.connector.ConnectorPermissionItem;
 import com.orgmemory.core.knowledge.retrieval.CanonicalHybridKnowledgeSearch;
+import com.orgmemory.core.knowledge.retrieval.CanonicalHybridKnowledgeSearchConfiguration;
 import com.orgmemory.core.knowledge.retrieval.KnowledgeRetrievalProperties;
 import com.orgmemory.core.knowledge.connector.ConnectorCaptureStatus;
 import com.orgmemory.core.knowledge.retrieval.QueryEmbeddingPort;
@@ -84,7 +85,7 @@
         "orgmemory.graph-rag.postgres.apache-age-mode=disabled",
         "orgmemory.connector.scheduling-enabled=false"
 })
-@Import(CanonicalHybridKnowledgeSearch.class)
+@Import(CanonicalHybridKnowledgeSearchConfiguration.class)
 @EnableConfigurationProperties(KnowledgeRetrievalProperties.class)
 @Testcontainers
 @DirtiesContext(classMode = DirtiesContext.ClassMode.AFTER_CLASS)

apps/worker/src/test/java/com/orgmemory/worker/connector/ConnectorPruningIntegrationTests.java

@@ -31,6 +31,7 @@
 import com.orgmemory.core.knowledge.connector.ConnectorMembershipMember;
 import com.orgmemory.core.knowledge.connector.ConnectorPermissionItem;
 import com.orgmemory.core.knowledge.retrieval.CanonicalHybridKnowledgeSearch;
+import com.orgmemory.core.knowledge.retrieval.CanonicalHybridKnowledgeSearchConfiguration;
 import com.orgmemory.core.knowledge.retrieval.KnowledgeRetrievalProperties;
 import com.orgmemory.core.knowledge.connector.ConnectorCaptureStatus;
 import com.orgmemory.core.knowledge.retrieval.QueryEmbeddingPort;
@@ -81,7 +82,7 @@
         "orgmemory.graph-rag.postgres.apache-age-mode=disabled",
         "orgmemory.connector.scheduling-enabled=false"
 })
-@Import(CanonicalHybridKnowledgeSearch.class)
+@Import(CanonicalHybridKnowledgeSearchConfiguration.class)
 @EnableConfigurationProperties(KnowledgeRetrievalProperties.class)
 @Testcontainers
 @DirtiesContext(classMode = DirtiesContext.ClassMode.AFTER_CLASS)

apps/worker/src/test/java/com/orgmemory/worker/connector/ConnectorStagingIngestionIntegrationTests.java

@@ -22,6 +22,7 @@
 import com.orgmemory.core.authorization.RelationshipTupleWriteResult;
 import com.orgmemory.core.authorization.ResourceRef;
 import com.orgmemory.core.knowledge.retrieval.CanonicalHybridKnowledgeSearch;
+import com.orgmemory.core.knowledge.retrieval.CanonicalHybridKnowledgeSearchConfiguration;
 import com.orgmemory.core.knowledge.connector.ConnectorCrawlBatch;
 import com.orgmemory.core.knowledge.connector.ConnectorIngestionResult;
 import com.orgmemory.core.knowledge.connector.ConnectorIngestionService;
@@ -76,7 +77,7 @@
         "orgmemory.graph-rag.postgres.apache-age-mode=disabled",
         "orgmemory.connector.scheduling-enabled=false"
 })
-@Import(CanonicalHybridKnowledgeSearch.class)
+@Import(CanonicalHybridKnowledgeSearchConfiguration.class)
 @EnableConfigurationProperties(KnowledgeRetrievalProperties.class)
 @Testcontainers
 @DirtiesContext(classMode = DirtiesContext.ClassMode.AFTER_CLASS)

apps/worker/src/test/java/com/orgmemory/worker/ingestion/SourceIngestionPipelineIntegrationTests.java

@@ -33,6 +33,7 @@
 import com.orgmemory.core.knowledge.retrieval.QueryEmbedding;
 import com.orgmemory.core.knowledge.retrieval.KnowledgeRetrievalProperties;
 import com.orgmemory.core.knowledge.retrieval.CanonicalHybridKnowledgeSearch;
+import com.orgmemory.core.knowledge.retrieval.CanonicalHybridKnowledgeSearchConfiguration;
 import com.orgmemory.core.knowledge.storage.ObjectContent;
 import com.orgmemory.core.knowledge.storage.ObjectStoragePort;
 import com.orgmemory.core.knowledge.storage.ObjectWriteRequest;
@@ -86,7 +87,7 @@
 })
 @Import({
         SourceIngestionPipelineIntegrationTests.UploadTestConfiguration.class,
-        CanonicalHybridKnowledgeSearch.class
+        CanonicalHybridKnowledgeSearchConfiguration.class
 })
 @EnableConfigurationProperties(KnowledgeRetrievalProperties.class)
 @Testcontainers

core/src/main/java/com/orgmemory/core/knowledge/retrieval/AuthorizationResourceDirectory.java

@@ -1,60 +1,13 @@
 package com.orgmemory.core.knowledge.retrieval;
 
-import com.orgmemory.core.shared.error.KnowledgeResourceNotFoundException;
-
-import com.orgmemory.core.knowledge.asset.KnowledgeAssetRetrievalQuery;
-
 import com.orgmemory.core.authorization.ResourceRef;
-import com.orgmemory.core.knowledge.space.KnowledgeSpaceQuery;
-import com.orgmemory.core.organization.OrganizationResourceQuery;
-import java.util.Objects;
 import java.util.UUID;
-import org.springframework.stereotype.Service;
-import org.springframework.transaction.annotation.Transactional;
 
 /**
- * Resolves an administrator-supplied authorization resource against the
- * canonical tenant directory before OpenFGA is queried.
+ * Adapter-facing query that validates an authorization resource against its
+ * canonical tenant-owned directory before policy evaluation.
  */
-@Service
-public class AuthorizationResourceDirectory {
-
-    private final OrganizationResourceQuery organizationResources;
-    private final KnowledgeSpaceQuery spaces;
-    private final KnowledgeAssetRetrievalQuery assets;
-
-    AuthorizationResourceDirectory(
-            OrganizationResourceQuery organizationResources,
-            KnowledgeSpaceQuery spaces,
-            KnowledgeAssetRetrievalQuery assets) {
-        this.organizationResources = organizationResources;
-        this.spaces = spaces;
-        this.assets = assets;
-    }
+public interface AuthorizationResourceDirectory {
 
-    @Transactional(readOnly = true)
-    public ResourceRef require(
-            UUID organizationId,
-            String resourceType,
-            UUID resourceId) {
-        Objects.requireNonNull(organizationId, "organizationId");
-        Objects.requireNonNull(resourceId, "resourceId");
-        String type = Objects.requireNonNull(resourceType, "resourceType").strip();
-        boolean exists = switch (type) {
-            case "organization" ->
-                    organizationId.equals(resourceId)
-                            && organizationResources.organizationExists(organizationId);
-            case "organizational_unit" ->
-                    organizationResources.departmentExists(organizationId, resourceId);
-            case "knowledge_space" ->
-                    spaces.exists(organizationId, resourceId);
-            case "knowledge_asset" ->
-                    assets.exists(organizationId, resourceId);
-            default -> false;
-        };
-        if (!exists) {
-            throw new KnowledgeResourceNotFoundException();
-        }
-        return ResourceRef.of(organizationId, type, resourceId);
-    }
+    ResourceRef require(UUID organizationId, String resourceType, UUID resourceId);
 }