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
• runtime state, path, diagnostics, restart, maintenance, and policy contracts
• 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
• 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.

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.

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.

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.