feat(reflect): add libreflect incubator

Author: ImperaZim

CHANGELOG.md

@@ -141,6 +141,11 @@ elprobe run <package>
   main-thread callback registry, generic `AsyncTask` wrapper and dispatcher.
   This validates async rules for DB, HTTP, Agent, scheduler and package/update
   jobs before creating a standalone `LibAsync` repository.
+- Added the OP-31 `LibReflect` incubator inside the EasyLibrary core. The new
+  experimental `imperazim\library\reflect\*` classes provide explicit
+  class/interface/trait inspection, class contract validation, attribute access
+  and safe instantiation helpers without global scanning or hidden runtime
+  auto-discovery.
 
 ### Package manager
 

README.md

@@ -867,6 +867,22 @@ and package/update work:
 See [`docs/libasync-incubator.md`](docs/libasync-incubator.md) for examples,
 rules and graduation criteria.
 
+## LibReflect incubator
+
+EasyLibrary 3.0-dev also includes an experimental reflection incubator under
+`imperazim\library\reflect`. It is not an official `LibReflect` package yet.
+
+The incubator validates a small, explicit reflection shape:
+
+- `ClassInspector` inspects one class/interface/trait name at a time.
+- `ClassInspection` exposes metadata, attributes and controlled instantiation.
+- `ClassContract` validates inheritance, interfaces and instantiability.
+- `ClassContractResult` carries validation errors.
+- `ClassFactory` instantiates only classes that pass the contract.
+
+It intentionally avoids global class scans, hidden auto-discovery and runtime
+magic. See [`docs/libreflect-incubator.md`](docs/libreflect-incubator.md).
+
 ## EasyLibrary Agent Bridge
 
 The **EasyLibrary Agent Bridge** is an optional network bridge between PocketMine-MP plugins and the external [`EasyLibraryAgent`](https://github.com/ImperaZim/EasyLibraryAgent) Go service.
@@ -985,6 +1001,7 @@ Use compute for expensive/global tasks. Keep small local or same-tick logic insi
 - [`docs/module-boundary.md`](docs/module-boundary.md)
 - [`docs/module-smoke-matrix.md`](docs/module-smoke-matrix.md)
 - [`docs/libasync-incubator.md`](docs/libasync-incubator.md)
+- [`docs/libreflect-incubator.md`](docs/libreflect-incubator.md)
 - [`docs/api.md`](docs/api.md)
 - [`docs/public-api.md`](docs/public-api.md)
 - [`docs/package-contract.md`](docs/package-contract.md)

changelogs/3.0.md

@@ -527,6 +527,65 @@ Compatibility impact:
 - Future `LibAsync` extraction must still prove at least two real libs can use
   the shared contract safely.
 
+### LibReflect incubator
+
+EasyLibrary now includes a small `LibReflect` incubator under
+`imperazim\library\reflect`.
+
+What changed:
+
+- Added `ClassInspector` for inspecting one explicit class/interface/trait name.
+- Added `ClassInspection` as a read-only snapshot of class metadata, attributes
+  and controlled instantiation.
+- Added `ClassContract` for fluent inheritance/interface/instantiability
+  validation.
+- Added `ClassContractResult` for structured validation errors and assertion.
+- Added `ClassFactory` for instantiating only classes that pass the contract.
+- Added `docs/libreflect-incubator.md` with examples, rules, candidate uses and
+  graduation criteria.
+- Added lightweight tests for class metadata, attributes, valid/invalid
+  contracts and rejection of abstract class instantiation.
+
+Why it changed:
+
+EasyLibrary already has legitimate reflection needs in module class loading,
+package entry loading, provider diagnostics and plugin migration/debug
+contexts. The risk is turning reflection into hidden runtime magic. This
+incubator defines a deliberately small, explicit shape before any standalone
+`LibReflect` package exists.
+
+How to use the incubator shape:
+
+```php
+use imperazim\library\reflect\ClassContract;
+use imperazim\library\reflect\ClassFactory;
+use imperazim\module\BaseModule;
+
+$contract = ClassContract::for($className)
+    ->mustExtend(BaseModule::class)
+    ->mustBeInstantiable()
+    ->validate();
+
+if (!$contract->isOk()) {
+    foreach ($contract->getErrors() as $error) {
+        $logger->warning($error);
+    }
+    return;
+}
+
+$module = ClassFactory::newInstance($className, [$plugin, $config]);
+```
+
+Compatibility impact:
+
+- This is additive and marked `@experimental`.
+- No official standalone lib API changed.
+- No `LibReflect` repo or package has been created yet.
+- The incubator intentionally does not scan all declared classes or arbitrary
+  source trees.
+- A future extraction must prove at least two real call sites become smaller or
+  safer without making runtime behavior invisible.
+
 ### Compatibility policy
 
 EasyLibrary now has a dedicated compatibility policy at

docs/compatibility.md

@@ -227,3 +227,21 @@ standalone package, or be rejected before stable `3.0.0` if real DB/HTTP/Agent
 or scheduler migrations do not justify it.
 
 See [`libasync-incubator.md`](libasync-incubator.md).
+
+## LibReflect Incubator
+
+The `imperazim\library\reflect\*` namespace is experimental during 3.0-dev.
+
+It exists to test whether a future official `LibReflect` package should share:
+
+- explicit class inspection;
+- class contract validation;
+- attribute access;
+- controlled instantiation helpers.
+
+This is not a stable public promise yet. The incubator must not be treated as a
+global class scanner, dependency injection container or automatic command/module
+loader. It may change, move to a standalone package, or be rejected before
+stable `3.0.0` if real call sites do not justify it.
+
+See [`libreflect-incubator.md`](libreflect-incubator.md).

docs/getting-started.md

@@ -77,6 +77,7 @@ composer run quality
 - [`module-boundary.md`](module-boundary.md) for the current module runtime and future `LibModule` boundary plan.
 - [`module-smoke-matrix.md`](module-smoke-matrix.md) for module runtime validation.
 - [`libasync-incubator.md`](libasync-incubator.md) for the experimental async worker/result shape.
+- [`libreflect-incubator.md`](libreflect-incubator.md) for the experimental reflection/class-contract shape.
 
 ## LibPlaceholder package features
 

docs/libreflect-incubator.md

@@ -0,0 +1,126 @@
+# LibReflect Incubator
+
+`LibReflect` is not an official standalone package yet.
+
+EasyLibrary 3.0-dev now has a small internal incubator under:
+
+```text
+imperazim\library\reflect
+```
+
+The goal is to validate whether a future `LibReflect` should exist without
+turning reflection into hidden framework magic.
+
+## Why This Exists
+
+Several parts of the ecosystem already need cautious reflection:
+
+- package entry classes need existence and constructor checks;
+- module loaders need to validate module classes;
+- provider diagnostics need to identify class file ownership;
+- plugin migration tools may need controlled class metadata;
+- optional attributes can reduce boilerplate when used explicitly.
+
+Those are legitimate cases. The risky part is uncontrolled auto-discovery,
+global class scans and silent instantiation. The incubator intentionally avoids
+those patterns.
+
+## Current Experimental Pieces
+
+| Class | Role |
+|---|---|
+| `ClassInspector` | Entry point for inspecting one class/interface/trait name. |
+| `ClassInspection` | Read-only snapshot of class metadata, attributes and safe instantiation. |
+| `ClassContract` | Fluent validation for inheritance, interfaces and instantiability. |
+| `ClassContractResult` | Validation result with errors and structured output. |
+| `ClassFactory` | Small helper for instantiating only validated, instantiable classes. |
+
+All of these are `@experimental`.
+
+## Example
+
+```php
+use imperazim\library\reflect\ClassContract;
+use imperazim\library\reflect\ClassFactory;
+use imperazim\module\BaseModule;
+
+$contract = ClassContract::for($className)
+    ->mustExtend(BaseModule::class)
+    ->mustBeInstantiable()
+    ->validate();
+
+if (!$contract->isOk()) {
+    foreach ($contract->getErrors() as $error) {
+        $logger->warning($error);
+    }
+    return;
+}
+
+$module = ClassFactory::newInstance($className, [$plugin, $config]);
+```
+
+## Attribute Example
+
+```php
+use Attribute;
+use imperazim\library\reflect\ClassInspector;
+
+#[Attribute(Attribute::TARGET_CLASS)]
+final class FeatureInfo {
+    public function __construct(public string $id) {}
+}
+
+#[FeatureInfo('economy')]
+final class EconomyFeature {}
+
+$inspection = ClassInspector::inspect(EconomyFeature::class);
+$info = $inspection->newAttributeInstances(FeatureInfo::class)[0] ?? null;
+```
+
+## Rules
+
+- Inspect explicit class names only.
+- Do not scan all declared classes by default.
+- Do not recursively scan arbitrary source directories in runtime code.
+- Do not instantiate classes unless a contract has passed.
+- Do not hide runtime behavior behind attributes without a visible registration
+  path.
+- Prefer normal `use` imports and explicit PHP code when reflection does not
+  remove real duplication.
+
+## Candidate Uses
+
+| Area | Candidate use |
+|---|---|
+| Module loader | Replace ad-hoc `ReflectionClass` checks for module class validation. |
+| Package entry loader | Standardize zero-argument or host-argument entry instantiation checks. |
+| Provider diagnostics | Standardize file/class metadata reporting. |
+| Command tooling | Optional explicit attributes for command metadata if it reduces boilerplate. |
+| Migration/debug docs | Safer class metadata output for diagnostics and reports. |
+
+## What This Does Not Promise
+
+This incubator is not:
+
+- a dependency injection container;
+- a global class scanner;
+- an annotation framework;
+- an automatic command/module loader;
+- a replacement for explicit package/module manifests;
+- a stable public API yet.
+
+## Graduation Criteria
+
+Only create `LibReflect` as an official repository if the incubator proves all
+of these:
+
+- at least two real EasyLibrary/libs call sites become smaller or safer;
+- no runtime path depends on scanning all classes;
+- docs define which metadata can be used in production;
+- tests cover missing classes, abstract classes, inheritance, interfaces,
+  attributes and instantiation;
+- migration docs explain when not to use reflection;
+- release/package assets follow the same official lib standard as
+  `LibCommons`, `LibHttp` and `LibAssets`.
+
+Until then, this stays inside EasyLibrary as a 3.0-dev experiment.

docs/public-api.md

@@ -120,6 +120,26 @@ Current experimental classes:
 See [`libasync-incubator.md`](libasync-incubator.md) for the rules and
 graduation criteria.
 
+### LibReflect Incubator
+
+The `imperazim\library\reflect\*` namespace is an `@experimental` incubator for
+a possible future `LibReflect` package. It exists to test explicit class
+inspection, class-contract validation, attribute access and safe instantiation
+without introducing global scanners or hidden runtime magic.
+
+Current experimental classes:
+
+| Class | Status | Notes |
+|---|---|---|
+| `imperazim\library\reflect\ClassInspector` | `@experimental` | Entry point for inspecting one explicit class/interface/trait name. |
+| `imperazim\library\reflect\ClassInspection` | `@experimental` | Read-only metadata, attributes and instantiation wrapper. |
+| `imperazim\library\reflect\ClassContract` | `@experimental` | Fluent validation for inheritance, interfaces and instantiability. |
+| `imperazim\library\reflect\ClassContractResult` | `@experimental` | Structured validation result and assertion helper. |
+| `imperazim\library\reflect\ClassFactory` | `@experimental` | Instantiates only validated, instantiable classes. |
+
+See [`libreflect-incubator.md`](libreflect-incubator.md) for the rules and
+graduation criteria.
+
 ## Internal Implementation Surfaces
 
 The following namespaces are implementation details of EasyLibrary. They are

src/imperazim/library/reflect/ClassContract.php

@@ -0,0 +1,80 @@
+<?php
+
+declare(strict_types = 1);
+
+namespace imperazim\library\reflect;
+
+/**
+* Fluent class validation contract for the LibReflect incubator.
+*
+* @experimental 3.0-dev LibReflect incubator helper.
+*/
+final class ClassContract {
+
+  /** @var string[] */
+  private array $parents = [];
+
+  /** @var string[] */
+  private array $interfaces = [];
+
+  private bool $mustBeInstantiable = false;
+
+  private bool $autoload = true;
+
+  private function __construct(private string $className) {}
+
+  public static function for(string $className): self {
+    return new self($className);
+  }
+
+  public function autoload(bool $autoload): self {
+    $clone = clone $this;
+    $clone->autoload = $autoload;
+    return $clone;
+  }
+
+  public function mustExtend(string $parent): self {
+    $clone = clone $this;
+    $clone->parents[] = $parent;
+    return $clone;
+  }
+
+  public function mustImplement(string $interface): self {
+    $clone = clone $this;
+    $clone->interfaces[] = $interface;
+    return $clone;
+  }
+
+  public function mustBeInstantiable(bool $required = true): self {
+    $clone = clone $this;
+    $clone->mustBeInstantiable = $required;
+    return $clone;
+  }
+
+  public function validate(): ClassContractResult {
+    $inspection = ClassInspector::inspect($this->className, $this->autoload);
+    $errors = $inspection->getErrors();
+
+    if (!$inspection->exists()) {
+      return new ClassContractResult($inspection, $errors);
+    }
+
+    foreach ($this->parents as $parent) {
+      if (!$inspection->isSubclassOf($parent)) {
+        $errors[] = "{$inspection->getName()} must extend $parent.";
+      }
+    }
+
+    foreach ($this->interfaces as $interface) {
+      if (!$inspection->implementsInterface($interface)) {
+        $errors[] = "{$inspection->getName()} must implement $interface.";
+      }
+    }
+
+    if ($this->mustBeInstantiable && !$inspection->isInstantiable()) {
+      $errors[] = "{$inspection->getName()} must be instantiable.";
+    }
+
+    return new ClassContractResult($inspection, $errors);
+  }
+}