Eltheon Core.Storage

Core.Storage is the Eltheon storage foundation package. It owns space-based file management under the runtime StorageRoot and keeps managed file operations behind storage contracts instead of direct feature file access.

The built-in private logs space permits local random-access files without Storage metadata or HotIndex tracking. Active log lifecycle and retention remain owned by the Logging feature. Existing DataAssets/Logs content can be copied through the dedicated pre-composition boot migration.

Built-in system spaces expose Storage-first compatibility access. Missing objects may fall back to their mapped legacy DataAssets location, while writes are mirrored during the transition. Boot-critical Runtime control files remain below RuntimeRoot and deliberately do not depend on Storage.

Plugin materialization is stricter than general object compatibility: any object in the plugins space makes Storage authoritative for the complete snapshot. Legacy plugins are materialized only while the Storage space is entirely empty.

Implemented Foundation Surface

• Storage space registration with per-space policies and telemetry options.
• Root-safe local path policy that rejects traversal and never exposes physical paths through public DTOs.
• Local provider initialization with lazy directory creation.
• Storage operation pipeline for read/write/delete.
• Safe write with temp files, atomic replacement, backup/version-light support, cleanup on failure, and per-space serialization.
• Runtime-tunable worker pool with bounded worker count.
• Per-space SQLite metadata store and in-memory HotIndex.
• System space definitions, including the configs and local random-access databases spaces.
• Public URL resolution through IStorageUrlResolver and IStoragePublicDeliveryProvider.
• Private admin delivery through StorageManagement uses IStorageService.OpenReadAsync; Core.Storage does not expose physical paths.
• Diagnostics for root, space structure, metadata/file drift, reparse points, and worker configuration.
• Secret-safe storage events published through the optional Eltheon IEventBus, including EventBus metadata defaults and ambient correlation.
• Sparse action-oriented notifications through optional IEltheonNotificationPublisher for error/critical findings, incomplete remediation audit, and failed storage boot migrations.
• Provider-capable storage metrics emitted through the neutral IMetrics contract, plus a bounded 24-hour diagnostics projection for the StorageManagement cockpit.
• A passive file watcher marks metadata-capable local spaces as dirty after external file-system changes; it never mutates files or metadata and excludes random-access spaces such as logs and databases.
• EltheonServices-ready maintenance jobs for retention, integrity scan, metadata maintenance, public manifest work, and diagnostics. Jobs are exposed as neutral IEltheonManagedService instances and as IHostedService so the Service feature can discover and trigger them without a package dependency back from Storage to Services.
• Legacy DataAssets diagnostics plus explicitly authorized migration assistants that inventory, copy, and hash-verify data without deleting sources.
• SQLite database migration uses an offline pre-composition boot task, SQLite backup and integrity checks, atomic data-directory activation, and source preservation.
• Runtime diagnostics contribution for RuntimeManagement, Adviser, dashboard, or future admin surfaces.
• Retention maintenance for expired temp/trash files and lightweight backup pruning by configured maximum versions per object.
• Diagnostic findings publish sanitized Eltheon.Storage.DiagnosticsFindingRaised events when an event bus is available.
• Current findings carry opaque process-local IDs and declarative remediation actions; internal object keys and paths remain inside Core.Storage.
• State-changing remediations require an accepted audit-relevant EventBus request event and publish a persistent completion outcome.
• Metadata maintenance runs bounded SQLite integrity checks, WAL checkpoints, and optimizer passes for existing per-space metadata databases.
• Public manifest maintenance rebuilds internal public-manifest.json files for public metadata-backed spaces without exposing physical paths.

Dependency Boundaries

Core.Storage references only Core.Abstractions plus infrastructure packages needed for DI/options and SQLite. It must not reference concrete feature packages such as Events, Metrik, Notifications, Service, InMemory, WebUi, or template hosts.

Platform integrations should bridge through these neutral contracts:

• IEventBus
• IMetrics
• IStorageDiagnostics
• IStorageMaintenanceJob
• IRuntimeDiagnosticContributor
• IEltheonNotificationPublisher

Safety Rules

• StorageRoot is not public.
• Public URLs are resolved only for explicitly public spaces and public descriptors.
• Metrics must not use object keys, file names, physical paths, user IDs, or URLs as labels.
• Read events are disabled by default.
• Diagnostics remain read-only. Repairs run through short-lived, single-use remediation plans with immediate precondition checks. Legacy and localization migrations are validated at runtime and execute only as persistent tasks during the next boot.
• Maintenance jobs must use storage APIs and must not write directly to per-space SQLite databases.
• Random-access files require an explicit space policy and the local provider. Their physical paths are infrastructure-only and never enter public diagnostics, events, audit payloads, or metrics.
• Legacy migration copies through IStorageService, verifies content hashes, and preserves source data. Source changes, reparse points, policy conflicts, access errors, and hash mismatches block startup with a sanitized recovery record.
• No startup path may move legacy DataAssets or config files automatically.
• Retention only touches managed temp, trash, and backup/version directories below StorageRoot; it never deletes active data objects directly.
• Public manifests are internal metadata artifacts; public delivery still goes through IStorageUrlResolver and configured delivery providers.
• File watchers are dirty signals only. Diagnostics and remediation remain responsible for surfacing and resolving drift.

Configs Pilot

Core.ConfigFiles mirrors eligible JSON config writes into the configs storage space while preserving the legacy path. This is a compatibility bridge, not a full migration. Reads still support the legacy line, and no files are moved during startup.

Migration Backlog

Later feature migrations should be handled one feature at a time and should keep package independence intact:

• Email attachments/templates and generated mail artifacts.
• Webhook payload archives.
• Renderer demo/generated artifacts.
• Localization override files.
• Plugin packages and plugin-owned assets.
• Queue payloads and dead-letter files.
• Project uploads and public media.
• Export/import bundles.

Each migration should register an explicit space, use IStorageService, and keep any required legacy read path until the feature has its own migration plan.