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.

Module Runtime Boundary

The public module authoring API now belongs to LibModule, not EasyLibrary. Use the LibModule repository for imports such as:

use imperazim\module\BaseModule;
use imperazim\module\ModuleContext;
use imperazim\module\command\BaseModuleCommand;
use imperazim\module\event\BaseModuleListener;

EasyLibrary keeps only an experimental host bridge under imperazim\library\libmodule\*. That bridge is for package detection, provider selection, command registration, doctor/report summaries and smoke validation. It is not a module authoring API.

Important EasyLibrary bridge classes:

• imperazim\library\libmodule\runtime\ModuleRuntimeViewProvider
• imperazim\library\libmodule\runtime\ModuleRuntimeProvider
• imperazim\library\libmodule\runtime\DisabledModuleRuntimeProvider
• imperazim\library\libmodule\summary\ModuleRuntimeSummary
• imperazim\library\libmodule\summary\ModuleSummaryEntry

See Module Boundary and LibModule.

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.