Public API Contract

Public API Contract

This page summarizes the EasyLibrary 3.0-dev public API classification.

The versioned source document is docs/public-api.md.

Stability Markers

Marker	Meaning
@api	Supported public contract for plugin developers in the current major line.
@experimental	Usable during 3.0-dev, but still allowed to change before stable 3.0.0.
@internal	EasyLibrary implementation detail. Do not depend on it from another plugin.
@deprecated	Kept temporarily for migration with a documented replacement.

Current Public Core API

Use ProviderResolver when plugin code needs to know which official provider owns a library at runtime:

use imperazim\library\provider\ProviderResolver;
use imperazim\library\provider\ProviderStatus;

$resolver = ProviderResolver::fromServer($this->getServer());
$provider = $resolver?->one("libplaceholder");

if ($provider?->getProviderSource() === ProviderStatus::SOURCE_PACKAGE_BACKED
    || $provider?->getProviderSource() === ProviderStatus::SOURCE_STANDALONE) {
    $plugin = $provider->getPlugin();
}

Supported public classes:

Class	Status
imperazim\library\provider\ProviderResolver	@api
imperazim\library\provider\ProviderStatus	@api
imperazim\library\cache\RuntimeCache	@api

The explicit Library module and Agent accessors are also public entry points, but lifecycle, package, command and boot internals are not public API.

RuntimeCache is process-local memory only. It supports TTL, remember(), many helpers and stats, but it is not persistent storage or distributed state. The old imperazim\components\cache\Cache component class was removed in the 3.0-dev line; callers should migrate directly to RuntimeCache.

Experimental Module Runtime

The module runtime is available for testing in the 3.0-dev line, but remains @experimental until the stable 3.0.0 freeze.

The current runtime stays in the EasyLibrary core. See Module Boundary for the future LibModule plan and the OP-29 checklist. Component cleanup now goes through an internal adapter, Module Smoke Matrix records the current validation baseline, but the module authoring surface remains experimental.

Important experimental classes:

• imperazim\module\ModuleInterface
• imperazim\module\BaseModule
• imperazim\module\ModuleApiProvider
• imperazim\module\ModuleContext
• imperazim\module\ModuleManager
• imperazim\module\service\ModuleServiceRegistry
• imperazim\module\health\ModuleHealthReport
• imperazim\module\summary\ModuleRuntimeSummary
• imperazim\module\summary\ModuleSummaryEntry

LibAsync Incubator

imperazim\library\async\* is also experimental. It currently exists only as a 3.0-dev incubator for a possible future LibAsync package.

Important experimental classes:

• imperazim\library\async\AsyncWorker
• imperazim\library\async\AsyncResult
• imperazim\library\async\AsyncPayloadGuard
• imperazim\library\async\AsyncCallbackRegistry
• imperazim\library\async\AsyncJobTask
• imperazim\library\async\AsyncDispatcher

See LibAsync Incubator.

LibReflect Incubator

imperazim\library\reflect\* is experimental. It currently exists only as a 3.0-dev incubator for a possible future LibReflect package.

Important experimental classes:

• imperazim\library\reflect\ClassInspector
• imperazim\library\reflect\ClassInspection
• imperazim\library\reflect\ClassContract
• imperazim\library\reflect\ClassContractResult
• imperazim\library\reflect\ClassFactory

See LibReflect Incubator.

Internal Surfaces

Do not depend on these namespaces from another plugin:

• imperazim\library\package\*
• imperazim\library\config\*
• imperazim\library\command\*
• imperazim\components\plugin\*
• module loader, registry, resolver and lifecycle internals.

Use documented commands, config files, package contracts and provider APIs instead.

See Compatibility Policy for BC, deprecation and channel rules.