Redeon.SuperSiteEngineCore.Web.Eltheon.Core.Abstractions

Stable, dependency-light contract package for Eltheon core infrastructure, feature packages, Razor UI packages, templates, hosts, and future PluginSDK alignment.

This package contains shared framework language only. It intentionally has no dependencies on concrete feature packages, WebUi, templates, hosts, PluginSDK projects, EF Core, Razor, MVC, or concrete runtime services.

Purpose

Use Core.Abstractions when multiple Eltheon packages need the same stable concept but must remain independently upgradeable NuGet packages.

Typical examples:

• navigation contributions
• permission declarations
• event bus contracts and event metadata
• metrics and tracing facades
• rendering contracts
• notification and realtime publishing ports
• storage contracts, including project-owned upload space defaults
• runtime state, path, diagnostics, restart, maintenance, and policy contracts
• workload job, worker, descriptor, trigger-context, and execution-policy contracts
• Adviser check, observation, subject, evidence, coverage, recommendation, and action descriptors
• permission cache invalidation ports

Core.Abstractions is not an implementation package. Implementations remain in the owning feature package, host, or WebUi package.

Included Contract Areas

Navigation

• EltheonNavigationEntry
• EltheonNavigationEntryType
• IEltheonNavigationProvider
• IEltheonNavigationRegistry

Feature packages use these types to contribute Admin/User/Docs navigation without referencing Core.WebUi or the template shell.

Permissions

• EltheonPermissionDefinition
• EltheonPermissionDefinitionFactory
• IEltheonPermissionProvider
• IEltheonPermission
• EltheonPermissionSet
• EltheonPermissionGrant
• EltheonPermissionRiskLevel
• IEltheonPermissionCacheInvalidator

Feature packages declare permissions here. Concrete storage, synchronization, admin UI, and role integration remain owned by the Permissions and Identity features.

Events

• IEvent
• IChangeSetEvent
• IEventBus
• IEventProvider
• IEventEnvelopeProvider
• IEventTriggerContext
• IEventEnvelopeFactory
• IEventRegistry
• IEventTransport
• IEventContextAccessor
• EltheonEventEnvelope
• EventMetadata
• event classification enums such as EventScope, EventDurability, EventVisibility, EventSeverity, EventPriority, EventResult, and EventActorType

The Events feature provides the concrete EventBus implementation. Other features can publish or consume event contracts through Core.Abstractions without referencing the Events package only for interfaces.

IEventTriggerContext is an explicit payload-side allowlist for workload triggers. It exposes only an optional routing subject and bounded secret-safe string metadata; event payloads remain inaccessible to workload trigger context.

Metrics

• IMetrics
• ITracer
• IMetricsExporterState
• IHttpMetricsDiagnosticsProvider
• HttpMetricsSnapshot
• HttpEndpointMetricsSnapshot
• HttpStatusCodeBucket
• MetricDefinition
• IMetricDefinitionRegistry

The Metrik feature provides OpenTelemetry, exporter wiring, HTTP instrumentation, and diagnostics implementations. Features that only record counters, gauges, histograms, spans, or read neutral diagnostics contracts should depend on Core.Abstractions.

Rendering

• IRenderService
• IRenderEngine
• IRenderTemplateProvider
• IRenderDefinitionProvider
• IRenderComponent
• IRenderOutputProvider
• RenderRequest
• RenderDefinition
• RenderContext
• RenderTemplate
• RenderModel
• RenderResult
• render diagnostics, descriptors, output kinds, cache policy, and component invocation/result contracts
• RenderComponentDescriptor catalog metadata for component discovery/editor surfaces
• RenderComponentParameterDescriptor for neutral component parameter forms

The Renderer feature provides concrete engines, registries, providers, components, diagnostics, events, and metrics. Core.Abstractions only defines the neutral rendering language so future features, hosts, and plugins can exchange render requests without referencing a concrete renderer implementation.

Notifications and Realtime

• IEltheonNotificationPublisher
• EltheonNotificationMessage
• EltheonNotificationTarget
• EltheonNotificationScope
• EltheonNotificationSeverity
• EltheonNotificationCategoryKeys
• EltheonNotificationChannel
• EltheonNotificationChannelDescriptor
• EltheonNotificationPublishOptions
• EltheonNotificationDeliveryMode
• EltheonNotificationPersistenceMode
• EltheonNotificationDeliveryContext
• EltheonNotificationDeliveryResult
• EltheonNotificationDeliveryStatus
• EltheonNotificationProviderHealth
• IEltheonNotificationChannelProvider
• IEltheonNotificationProviderHealthCheck
• IEltheonAdminRealtimePublisher
• IEltheonRealtimeNotificationPublisher
• EltheonRealtimeNotification

These ports let features emit admin updates or structured notification requests without referencing Notifications, SignalR, or any concrete UI transport package. Notification channels use stable string keys so optional packages and future plugins can provide channels without expanding a central enum.

Runtime

• RuntimeState, RuntimeStateKind, RuntimeHealthStatus, and IRuntimeStateAccessor
• host and startup contracts such as HostMode, HostState, StartupPhase, and StartupState
• maintenance contracts such as MaintenanceState, MaintenanceLevel, MaintenanceAccessMode, IMaintenanceStateReader, and IMaintenanceStateStore
• restart requirement contracts such as RuntimeRestartRequirement, RuntimeRestartReason, RuntimeRestartSeverity, IRuntimeRestartRequirementReader, and IRuntimeRestartRequirementStore
• runtime path contracts such as RuntimePathKind, RuntimePathDescriptor, and IRuntimePathProvider
• runtime policy and diagnostics contracts such as RuntimeConfigChangeImpact, RuntimePolicyResult, RuntimeDiagnosticSnapshot, IRuntimeDiagnosticsProvider, and IRuntimeDiagnosticContributor
• RuntimeEventNames for stable runtime event names

Core.Runtime provides implementations for these contracts. Template hosts, Watchdog, RuntimeManagement, and feature packages should consume the neutral contracts without moving host composition or UI behavior into Core.Abstractions.

Workloads

• IEltheonJob for bounded executions
• IEltheonWorker for continuously supervised worker generations
• EltheonJobDescriptor and EltheonWorkerDescriptor for structurally distinct registrations
• IEltheonWorkloadCatalog for immutable validated descriptor discovery
• EltheonExecutionPolicy, EltheonRetryPolicy, and EltheonWorkerRestartPolicy
• EltheonTriggerBindingDefinition and EltheonTriggerOccurrence
• EltheonJobContext, EltheonWorkerContext, and EltheonJobResult
• EltheonJobResultFact for bounded, secret-safe scalar result information
• IEltheonJobDispatcher plus secret-safe execution requests, handles, snapshots, statuses, and attempt history
• IEltheonWorkerSupervisor plus worker snapshots, generation identity, lifecycle status, and start/stop reasons

The Service feature implements the complete workload catalog, execution coordinator, worker supervisor, trigger engine, persistence, administration, and observability runtime. These contracts deliberately do not derive from IHostedService. The former managed-service contracts were removed and are not a compatibility surface.

Trusted dispatch boundaries may attach an ExecutionPolicyOverride to EltheonJobExecutionRequest. The Service runtime validates this bounded policy and gives trigger-binding overrides precedence over persistent workload overrides and descriptor defaults.

IEltheonWorkloadOwnerAvailabilityProvider lets feature and plugin owners make workload availability explicit without introducing a dependency from Core.Abstractions to their concrete runtime. Owner unavailability blocks new job admissions and worker starts.

EltheonJobResult.ResultFacts and EltheonJobExecutionSnapshot.ResultFacts are additive compatibility surfaces. A result may contain at most 16 facts. Each fact has a stable key, an optional resource key, a fallback display name, and a scalar string value; fixed field lengths prevent arbitrary payload transport. Existing callers can continue to use the unchanged three-parameter EltheonJobResult constructor, and older serialized snapshots deserialize with an empty fact list.

Adviser

• IEltheonAdviserCheck
• EltheonAdviserCheckDescriptor
• EltheonAdviserCheckContext
• EltheonAdviserCheckExecutionResult
• EltheonAdviserObservation
• EltheonAdviserSubject and EltheonAdviserSubjectReference
• EltheonAdviserEvidence
• EltheonAdviserCoverage
• EltheonAdviserRecommendation
• EltheonAdviserActionDescriptor
• EltheonAdviserIdentifierRules
• AddEltheonAdviserCheck<TCheck>()

Contributor features own their check logic and register it through Core.Abstractions. They do not reference the concrete Adviser feature. Checks are scoped, receive bounded selectors and correlation data, and return structured scalar evidence. The context deliberately excludes raw Service-v3 trigger and event payloads, persistence services, finding stores, and an arbitrary service provider.

The existing bounded plugin types under v1/Extensions, including IEltheonAdviserCheckProvider, remain a separate compatibility surface and are not aliases for these contributor contracts.

Storage

• IStorageService
• IStorageObjectCatalog
• IStorageSpaceRegistry
• IStorageVersionService
• IStorageBackupService
• IStorageRandomAccessFileResolver
• IStorageUrlResolver
• storage DTOs for objects, versions, backups, findings, remediations, events, and policies
• StorageProjectSpaces.CreatePrivateUploadSpace for project-owned private upload spaces with safe writes, metadata, optional trash, optional versioning, and no random-access files

Core.Storage implements these contracts. Feature and project packages should register spaces through these neutral definitions instead of referencing Core.Storage implementation types.

Usage

public sealed class MyFeatureNavigationProvider : IEltheonNavigationProvider
{
    public IEnumerable<EltheonNavigationEntry> GetEntries()
    {
        yield return new EltheonNavigationEntry
        {
            Key = "my-feature.admin",
            Area = "Admin",
            LabelKey = "Navigation.MyFeature",
            FallbackLabel = "My feature",
            Page = "/MyFeature/Index",
            Icon = "box"
        };
    }
}

public sealed class MyService
{
    private readonly IEventBus? _eventBus;
    private readonly IEltheonNotificationPublisher? _notifications;

    public MyService(IEventBus? eventBus = null, IEltheonNotificationPublisher? notifications = null)
    {
        _eventBus = eventBus;
        _notifications = notifications;
    }
}

await _notifications.PublishAsync(
    new EltheonNotificationMessage
    {
        CategoryKey = EltheonNotificationCategoryKeys.Security,
        Title = "Security warning",
        Message = "A suspicious sign-in attempt was detected.",
        Scope = EltheonNotificationScope.Admin,
        Targets = [EltheonNotificationTarget.Role("Administrators")]
    },
    new EltheonNotificationPublishOptions
    {
        PreferredChannels = [EltheonNotificationChannel.InApp, EltheonNotificationChannel.Mail],
        PersistenceMode = EltheonNotificationPersistenceMode.Inbox
    });

PreferredChannels, delivery modes, persistence modes, and targets express publisher intent. The Notifications feature owns effective policy evaluation and can enrich EltheonNotificationDeliveryContext with the selected persistence mode, deduplication/coalescing keys, audit intent, and required-delivery behavior before providers run. Concrete inbox storage, preference data, migrations, APIs, and mail adapters remain host/feature composition concerns and are not implemented by Core.Abstractions. Existing publisher implementations remain source-compatible through a default structured-overload adapter.

public sealed class MyFeatureCheck : IEltheonAdviserCheck
{
    public EltheonAdviserCheckDescriptor Descriptor { get; } = new(
        "eltheon.my-feature.configuration",
        "my-feature",
        "Adviser.MyFeature.Configuration.Title",
        "Adviser.MyFeature.Configuration.Description",
        EltheonAdviserCategory.Configuration,
        EltheonAdviserSeverity.Medium,
        [EltheonAdviserIdentifierRules.OperationalProfile],
        EltheonAdviserCostClass.Light,
        TimeSpan.FromSeconds(20),
        "1.0.0");

    public Task<EltheonAdviserCheckExecutionResult> ExecuteAsync(
        EltheonAdviserCheckContext context,
        CancellationToken cancellationToken)
    {
        cancellationToken.ThrowIfCancellationRequested();
        return Task.FromResult(
            new EltheonAdviserCheckExecutionResult(
                EltheonAdviserCheckExecutionStatus.Succeeded,
                new EltheonAdviserCoverage(EltheonAdviserCoverageMode.Complete)));
    }
}

services.AddEltheonAdviserCheck<MyFeatureCheck>();

Boundary Rules

• Do not place EF models, Razor Pages, TagHelpers, database contexts, host configuration, plugin implementation types, or feature services in this package.
• Do not add references from Core.Abstractions to feature packages, WebUi, templates, hosts, or PluginSDK.
• Add only the smallest stable contract needed to remove concrete package coupling.
• If a type is only useful inside one feature implementation, it belongs in that feature package.

For governance rules, see docs/Eltheon_Core_Abstractions_Rulebook.md.

Destructive Storage and Recovery Boundaries

IStorageSpaceLifecycleService provides a neutral owner-scoped contract for explicit Storage-space destruction. IEltheonDatabaseRecoveryService supports creation, verification, restore, and lifecycle-controlled deletion of secret-safe provider recovery artifacts. Concrete filesystem and database behavior remains outside Core.Abstractions.