GR-69858: Architectural, functional spec, and test cleanup

Author: vjovanov

substratevm/docs/README.md

@@ -47,5 +47,5 @@ Consulting the CI configurations in ci/ci.jsonnet may help understand how `mx ga
 ## Security Providers
 
 - [JCA Security Provider Inclusion](functional-spec/security-providers.md): required provider inclusion and run-time behavior.
-- [§AR-002-security-providers](../src/com.oracle.svm.hosted/src/com/oracle/svm/hosted/jca/SecurityServicesFeature.java):
+- [§AR-001-security-providers](../src/com.oracle.svm.hosted/src/com/oracle/svm/hosted/jca/SecurityServicesFeature.java):
   provider inclusion, verification, and metadata tracing.

substratevm/docs/architecture/README.md

@@ -2,5 +2,5 @@
 
 This directory contains developer-facing architecture records for Native Image.
 
-- [§AR-002-security-providers](../../src/com.oracle.svm.hosted/src/com/oracle/svm/hosted/jca/SecurityServicesFeature.java):
+- [§AR-001-security-providers](../../src/com.oracle.svm.hosted/src/com/oracle/svm/hosted/jca/SecurityServicesFeature.java):
   provider inclusion, verification, and metadata tracing.

substratevm/docs/functional-spec/security-providers.md

@@ -59,7 +59,7 @@ initialization, and an application can instead install an existing instance with
 [§7](#7-transition-to-the-future-defaults) defines the future-default options that select this
 behavior during the transition from service-driven provider inclusion and build-time provider-list
 initialization.
-The implementation is described by [§AR-002-security-providers](../../src/com.oracle.svm.hosted/src/com/oracle/svm/hosted/jca/SecurityServicesFeature.java).
+The implementation is described by [§AR-001-security-providers](../../src/com.oracle.svm.hosted/src/com/oracle/svm/hosted/jca/SecurityServicesFeature.java).
 
 ## 1. Notation
 
@@ -334,7 +334,7 @@ Instantiation reachability records successful verification for an application-su
 provider class independently of any configured-list instance of the same class. In particular, a
 verification failure for an omitted configured instance does not prevent provider-object use of an
 application-created instance.
-The implementation-specific recognition rule is §AR-002-security-providers.3.
+The implementation-specific recognition rule is §AR-001-security-providers.3.
 
 ## 6. Tracing Metadata
 
@@ -564,7 +564,7 @@ condition.
 ### 8.9 Architecture Obligations
 
 The following requirements apply universally to the implementation.
-[§AR-002-security-providers](../../src/com.oracle.svm.hosted/src/com/oracle/svm/hosted/jca/SecurityServicesFeature.java) names the structures that enforce
+[§AR-001-security-providers](../../src/com.oracle.svm.hosted/src/com/oracle/svm/hosted/jca/SecurityServicesFeature.java) names the structures that enforce
 them.
 
 #### 8.9.1 Closure of Registration Signals

substratevm/src/com.oracle.svm.core/src/com/oracle/svm/core/jdk/SecurityProviderRuntimeAccess.java

@@ -43,7 +43,7 @@ public final class SecurityProviderRuntimeAccess {
     private SecurityProviderRuntimeAccess() {
     }
 
-    // §AR-002-security-providers.2
+    // §AR-001-security-providers.2
     /** Apply the single JDK-acquisition filter to hosted or run-time eligibility state. */
     public static boolean passesJdkAcquisitionFilter(boolean eligible) {
         return eligible;

substratevm/src/com.oracle.svm.graal/src/com/oracle/svm/graal/hosted/runtimecompilation/RuntimeCompilationFeature.java

@@ -418,11 +418,9 @@ public void duringSetup(DuringSetupAccess c) {
         if (SubstrateOptions.useLLVMBackend()) {
             throw UserError.abort("Runtime compilation is currently unimplemented on the LLVM backend (GR-43073).");
         }
-        /*
-         * Runtime randomness seeds constant blinding and code-offset randomization. Register it
-         * only with its runtime-compilation consumer so ordinary executables do not retain JCA
-         * security providers. §FS-002-security-providers.2.4
-         */
+        /* Runtime randomness seeds constant blinding and code-offset randomization. Register it
+         * only with runtime compilation so ordinary executables do not retain JCA providers.
+         * §FS-002-security-providers.2.4 */
         if (ImageLayerBuildingSupport.firstImageBuild() && !ImageSingletons.contains(RuntimeRandomness.class)) {
             ImageSingletons.add(RuntimeRandomness.class, new RuntimeRandomnessSupport());
         }

substratevm/src/com.oracle.svm.hosted/src/com/oracle/svm/hosted/jca/SecurityServicesFeature.java

@@ -138,7 +138,7 @@
 import sun.security.provider.NativePRNG;
 import sun.security.x509.OIDMap;
 
-/// AR-002-security-providers: Security Provider Architecture
+/// AR-001-security-providers: Security Provider Architecture
 ///
 /// The feature records at image build time which security providers the JDK may construct, which
 /// provider services reflection may instantiate, and which application-created providers JCE may
@@ -152,14 +152,18 @@
 /// instantiated Provider subtype -----> application-provider verification only
 /// ```
 ///
-/// The registration planner interprets reflection and instantiation signals. The catalog registrar
-/// then records provider construction, retained services, and verification results in the layered
-/// run-time manifest. Legacy service-driven inclusion bypasses the planner and retains only the
-/// reached service type and its provider.
+/// At image build time, {@link SecurityServicesFeature#providerRegistrationPlan} interprets
+/// reflection metadata, and {@link SecurityProviderRegistrationPlanner#processNewProviders}
+/// combines it with instantiation signals. Complete plans go to
+/// {@link SecurityProviderCatalogRegistrar#includeProviderClass}; verification-only plans go to
+/// {@link SecurityProviderCatalogRegistrar#registerApplicationSuppliedProviderClass}. Legacy
+/// {@link SecurityServicesFeature#registerService} inclusion bypasses the planner and goes directly
+/// to {@link SecurityProviderCatalogRegistrar#includeProviderForLegacyService}.
 ///
-/// At run time, JDK-managed provider construction consults the manifest through the acquisition
-/// filter. An application-supplied provider object consults the same manifest only for JCE
-/// verification; supplying an existing instance does not require reflective provider construction.
+/// At run time, {@link SecurityProviderRuntimeAccess#isJdkAcquirable} gates JDK-managed provider
+/// construction. Application-supplied provider objects instead use
+/// {@link com.oracle.svm.core.jdk.JceProviderVerificationSupport#getVerificationResult
+/// getVerificationResult} for JCE verification; they do not require reflective construction.
 /// This architecture implements §FS-002-security-providers.
 ///
 /// ## 1. Supported Transition Modes

substratevm/src/com.oracle.svm.test/src/com/oracle/svm/test/services/SecurityProviderAnalysisArchitectureTest.java

@@ -36,7 +36,7 @@
 import com.oracle.svm.core.jdk.SecurityProviderRuntimeState;
 
 public class SecurityProviderAnalysisArchitectureTest {
-    /** Tests §AR-002-security-providers.3 and §AR-002-security-providers.4. */
+    /** Tests §AR-001-security-providers.3 and §AR-001-security-providers.4. */
     @Test
     public void typeMetadataCreatesApplicationSuppliedVerificationState() throws Exception {
         Assume.assumeTrue("native image runtime only", ImageInfo.inImageRuntimeCode());
@@ -49,7 +49,7 @@ public void typeMetadataCreatesApplicationSuppliedVerificationState() throws Exc
         Assert.assertNotNull(Mac.getInstance("type-metadata-mac", provider));
     }
 
-    /** Tests §AR-002-security-providers.4 manifest merge semantics. */
+    /** Tests §AR-001-security-providers.4 manifest merge semantics. */
     @Test
     public void failedBuildTimeVerificationIsNotOverwritten() {
         Assume.assumeTrue("native image runtime only", ImageInfo.inImageRuntimeCode());
@@ -62,14 +62,14 @@ public void failedBuildTimeVerificationIsNotOverwritten() {
         Assert.assertThrows(SecurityException.class, () -> Mac.getInstance("failed-verification-mac", provider));
     }
 
-    /** Tests §AR-002-security-providers.3 without granting JDK construction eligibility. */
+    /** Tests §AR-001-security-providers.3 without granting JDK construction eligibility. */
     @Test
     public void instantiatedProviderWithoutMetadataIsValidationOnly() {
         Assume.assumeTrue("native image runtime only", ImageInfo.inImageRuntimeCode());
         assertApplicationSuppliedProviderWasValidated(new SecurityServiceTest.ReachableProviderWithoutMetadata());
     }
 
-    /** §AR-002-security-providers.3: An image-heap provider instance is validated. */
+    /** §AR-001-security-providers.3: An image-heap provider instance is validated. */
     @Test
     public void imageHeapProviderWithoutMetadataIsValidated() {
         Assume.assumeTrue("native image runtime only", ImageInfo.inImageRuntimeCode());

substratevm/src/com.oracle.svm.test/src/com/oracle/svm/test/services/SecurityProviderExplicitRegistrationArchitectureTest.java

@@ -41,7 +41,7 @@
 public class SecurityProviderExplicitRegistrationArchitectureTest {
     private static final String REGISTERED_PROVIDER_NAME = "reflection-metadata-provider";
 
-    /** Tests §AR-002-security-providers.3 and §AR-002-security-providers.4. */
+    /** Tests §AR-001-security-providers.3 and §AR-001-security-providers.4. */
     @Test
     public void instantiatedProvidersHaveClassKeyedAcquisitionKinds() {
         Assume.assumeTrue("native image runtime only", ImageInfo.inImageRuntimeCode());