[GR-73222] Specify exact reflection behavior

Author: vjovanov

README.md

@@ -16,6 +16,11 @@ The documentation for the Truffle framework, for example, is in [_truffle/docs/_
 This also applies to languages, tools, and other components maintained in [related repositories](#related-repositories).
 Instructions for building GraalVM from source are in [`vm/README.md`](vm/README.md).
 
+- [§FS-003-reflection](substratevm/docs/functional-spec/reflection.md): Java reflection
+  registration and run-time access.
+- [§AR-002-reflection](substratevm/src/com.oracle.svm.hosted/src/com/oracle/svm/hosted/reflect/ReflectionDataBuilder.java):
+  reflection metadata architecture.
+
 ## Get Support
 
 * Open a [GitHub issue][issues] for reproducible bugs and concrete feature requests.

substratevm/docs/README.md

@@ -43,3 +43,16 @@ Consulting the CI configurations in ci/ci.jsonnet may help understand how `mx ga
 ## Project Terminus
 
 - [Project Terminus](project-terminus.md): overview and design direction for self-hosting Native Image.
+
+## Reflection
+
+- [Java Reflection Registration](functional-spec/reflection.md): class acquisition, metadata queries,
+  invocation, serialization, and unsafe access.
+- [§AR-002-reflection](../src/com.oracle.svm.hosted/src/com/oracle/svm/hosted/reflect/ReflectionDataBuilder.java):
+  reflection registration, metadata encoding, and run-time enforcement.
+
+## Security Providers
+
+- [JCA Security Provider Inclusion](functional-spec/security-providers.md): required provider inclusion and run-time behavior.
+- [§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

@@ -0,0 +1,8 @@
+# Architecture
+
+This directory contains developer-facing architecture records for Native Image.
+
+- [§AR-001-security-providers](../../src/com.oracle.svm.hosted/src/com/oracle/svm/hosted/jca/SecurityServicesFeature.java):
+  provider inclusion, verification, and metadata tracing.
+- [§AR-002-reflection](../../src/com.oracle.svm.hosted/src/com/oracle/svm/hosted/reflect/ReflectionDataBuilder.java):
+  reflection registration, metadata encoding, and run-time enforcement.

substratevm/docs/functional-spec/README.md

@@ -0,0 +1,43 @@
+# Functional Specifications
+
+This directory contains functional specifications for Native Image.
+
+- [JCA Security Provider Inclusion](security-providers.md): provider lookup and factory-call behavior
+  based on metadata.
+- [Java Reflection Registration](reflection.md): class acquisition, metadata queries, invocation,
+  serialization, and unsafe access.
+- [Functional Decisions](decisions/): product behavior decisions and tradeoffs for the
+  specifications.
+
+## Notation
+
+The specifications in this directory share the following notation.
+
+Non-normative text appears as an indented note.
+It explains or motivates a rule and states no requirement of its own.
+
+> This is non-normative text.
+> It gives rationale, intuition, or examples.
+
+A definition that introduces a **bold term** states the exact condition under which that term
+applies, with the phrase *if and only if*.
+
+Each specification names its default package.
+Whenever it refers to a class or interface using a single identifier N, the intended reference is to
+the class or interface named N in that package.
+Classes and interfaces from other packages are named by their canonical name, for example
+`java.util.ServiceLoader`.
+
+A cross-reference within a specification is shown as §x.y and links to that section.
+A reference to The Java Language Specification is written as JLS §12.4, and a reference to the Java
+SE API documentation names the specified class, interface, or member.
+
+The specifications use the following terms of the Java Platform specifications with their standard
+meaning:
+
+- *Loading* (JLS §12.2) is finding the binary form of a class and constructing a `java.lang.Class`
+  object for it.
+  *Creation of a new class instance* (JLS §12.5) is the separate act of instantiating that class.
+- *Class initialization* (JLS §12.4) is the execution of a class's static initializers.
+- The *binary name* (JLS §13.1) of a class is the name by which reflection metadata,
+  `java.lang.Class.forName`, and diagnostics identify it.