Table of Contents

LuciferCore v6.x Release Notes

Changelog and upgrade guide for the LuciferCore core engine across all v6.x versions.

v6.20.0

Release Date: October 2026 | Target: .NET 9.0 | Status: Latest

Version 6.20.0 enhances FileCache directory indexing by honoring file search filters during initial disk scanning.

Key Features & Architectural Changes

  • Search Pattern Filtering in Directory Indexing:

    • Passed the filter parameter directly into InsertPathInternal to ensure Directory.GetFiles(path, searchFilter) only indexes files matching the specified pattern.

    • Eliminates unnecessary file reads and memory footprint when monitoring specific files or extensions (such as .lucifercore or *.json) within large directory trees.

v6.19.0

Release Date: October 2026 | Target: .NET 9.0

Version 6.19.0 resolves a subtle URL decoding issue in FileCache.InsertPathInternal, ensuring literal filename preservation (e.g. keeping + as + instead of converting to spaces) during static directory scans and aligning cold-path initial indexing with FileSystemWatcher dynamic updates.

Key Features & Architectural Changes

  • Literal Filename Preservation in Directory Scanning:

    • Removed legacy HttpUtility.UrlDecode invocation from FileCache.InsertPathInternal.

    • Preserves literal characters such as + in file and folder names (e.g., c++.cpp is indexed directly as /prefix/c++.cpp instead of corrupted into /prefix/c .cpp).

    • Conforms with RFC 3986 where + is a valid sub-delimiter, reserving space encoding for %20.

    • Completely removes System.Web dependency from FileCache.cs.

  • 100% Indexing Parity with FileSystemWatcher:

    • Eliminates key divergence between startup recursive disk scanning and runtime event tracking (FileSystemWatcher computes virtual keys without URL-decoding).

v6.18.0

Release Date: October 2026 | Target: .NET 9.0

Version 6.18.0 introduces introspection and diagnostics APIs to FileCache, enabling zero-friction inspection of indexed virtual URI keys and monitored directory mappings.

Key Features & Enhancements

  • Cache Key Introspection (Keys & GetAllKeys):

    • Added public IEnumerable Keys => GetAllKeys() and public IEnumerable GetAllKeys().

    • Allows real-time enumeration of all cached virtual URI routes without manual key guessing or individual TryGetValue probes.

    • Prioritizes pre-cached KeyString identifiers with an automatic fallback to UTF-8 decoded bytes, ensuring complete coverage for both directory-scanned assets and programmatically inserted entries.

  • Monitored Directory Inspection:

    • Added public IEnumerable GetAllMonitoredPaths() to list all physical directories under active FileSystemWatcher tracking.

    • Added public IEnumerable<(string Path, string Prefix)> GetMonitoredDirectories() to inspect full directory-to-URL route mappings, streamlining route diagnostics and runtime configuration checks.

v6.17.0

Release Date: October 2026 | Target: .NET 9.0

Version 6.17.0 delivers intelligent path resolution to FileCache, HttpServer, and HttpsServer, eliminating manual path concatenation and Windows drive-root pitfalls.

Key Features & Architectural Changes

  • Intelligent Path Resolution (ResolveDirectory):

    • Modernized path qualification by replacing Path.IsPathRooted with Path.IsPathFullyQualified(path).

    • Overcomes the Windows-specific trap where paths with leading slashes ("/resources/webadmin") were mistakenly treated as drive-rooted (D:\resources\webadmin).

    • Relative paths (whether starting with /, ./, or bare) are automatically stripped of leading separators and cleanly anchored to BaseDirectory.

    • Transparently adapts to development environments (auto-discovering project roots from bin/../../.. via .csproj) and production deployments alike without requiring callers to concatenate Path.Combine or Manager.ResourceDirectory.

  • Unified Physical Key Indexing (Single Source of Truth):

    • Replaced the ambiguity between raw input paths and resolved disk paths by standardizing directory tracking on diskPathNorm for _pathsByKey, _entriesByPath, and InsertPathInternal.

    • FileSystemWatcher events now match registered folder entries with 100% precision, eliminating KeyNotFoundException during runtime file additions or modifications.

    • FindPath(string) and RemovePath(string) reliably resolve queries through ResolveDirectory and fallback lookups while adhering to normalized path conventions.

  • Decoupled Server Static Content Registration:

    • Removed preemptive Directory.Exists(path) checks from HttpServer.AddStaticContent and HttpsServer.AddStaticContent.

    • Delegated directory existence verification and asset resolution entirely to FileCache.InsertPath, enabling direct registration of relative web asset routes (e.g., server.AddStaticContent("/resources/webadmin")) at the server layer.

  • Clean String Primitives for Cold-Path Operations:

    • Refactored directory-level tracking tables (_entriesByPath, _pathsByKey, FileCacheEntry) to use idiomatic C# string keys rather than ByteString.

    • Preserved zero-allocation UTF-8 Span lookups (ReadOnlySpan<byte> / ReadOnlySpan<char>) on the critical cache reading hot-path (TryGetValue, Find).

v6.16.0

Release Date: October 2026 | Target: .NET 9.0

Version 6.16.0 introduces execution telemetry to TimingWheel, enabling hosting dispatchers to precisely detect effective workload vs. deferred spins.

Key Features & Architectural Changes

  • Execution Tracking in TimingWheel.Tick():

    • TimingWheel.Tick() now returns an int representing the exact number of events successfully executed and retired during the tick.

    • Clearly distinguishes between retired events (ev.Tick <= scheduledTick) and deferred events rescheduled into future cycles or buckets (RescheduleNextCycle).

    • Enables hosting managers (such as SimulationManager) to dynamically track idle tick streaks and execute intelligent backoff throttling without heuristic polling.

v6.15.0

Release Date: October 2026 | Target: .NET 9.0

Version 6.15.0 streamlines disk persistence and cache synchronization in FileCache by embracing pure single responsibility and event-driven decoupling.

Key Features

  • Streamlined FileCache.WriteFile:

    • Cleaned up the signature to public bool WriteFile(string key, ReadOnlySpan<byte> content), completely removing the redundant syncToDisk flag.

    • Direct zero-allocation persistence using pooled FileModel and positional RandomAccess.Write.

    • Removed manual ad-hoc cache insertion and fallback handlers from the write path, enforcing strict separation of concerns.

  • Event-Driven & On-Demand Synchronization:

    • Active cache updates are naturally handled by FileSystemWatcher (OnCreated and OnChanged) triggering the folder's registered InsertHandler.

    • Expired or evicted entries seamlessly pull the latest content on next access via LoadLazyEntry using a single disk syscall.

  • Unified Single Source of Truth (BaseDirectory):

    • Eliminated ambiguous split folders and the SourceDirectory property in favor of a single authoritative BaseDirectory.

    • Automatically resolves to the developer project root when both conditions are met: (1) running from a bin build output branch, AND (2) ../../.. contains a *.csproj file.

    • If either condition is not met (production, container, publish), strictly anchors to the runtime directory with zero sandbox escape.

v6.14.0

Release Date: October 2026 | Target: .NET 9.0

Version 6.14.0 introduces architectural enhancements for partitioned event dispatching and self-registering transport infrastructure.

Key Features

  • Instance-Bound Event Routing (Event.Index):

    • Added public int Index { get; set; } to the core Event base class.

    • Tracks target manager instance and partition identity directly within the event payload without requiring external dictionaries or heap allocations.

    • Automatically resets to 0 inside Event.Cleanup() when recycled back to EventPool<T>.

  • Self-Registering Server Transports:

    • Added public static readonly ConcurrentDictionary<int, ServerTransport> Servers to ServerTransport.

    • Servers self-register by port on constructor execution and clean up upon disposal, enabling runtime life-cycle discovery without central facade coupling.

v6.13.0

Release Date: October 2026 | Target: .NET 9.0

Version 6.13.0 delivers a major overhaul of FileCache, transforming it into a high-performance, on-demand asset store with active memory recovery and developer-friendly hot reloading.

Key Features

  • On-Demand Lazy Loading (Default):

    • Directory contents are indexed immediately at startup without reading file payloads into memory.

    • Files are loaded from disk only when requested for the first time via TryGetValue or Find.

    • Startup time for multi-gigabyte static directories drops to sub-millisecond speeds with nearly zero initial RAM usage.

    • Eager loading is still available by setting new FileCache(lazy: false).

  • Sliding Expiration & Lock-Free Sweep():

    • File access timestamps (LastAccessTicks) are updated atomically and lock-free using Volatile.Write.

    • Active reads continuously reset the expiration countdown.

    • Added the public int Sweep() method to reclaim memory by unloading idle file buffers while preserving index metadata for subsequent on-demand reloads.

  • SIMD Content Hashing (XXH64):

    • File data is automatically hashed using hardware-accelerated XXH64 via Buffer.ComputeHash.

    • Redundant reloads are avoided when file touch timestamps change but content remains identical.

    • Added TryGetContentHash(key, out int hash) to support client-server asset synchronization without manual integer version counters.

  • Direct Persistence via FileModel:

    • Added WriteFile(key, content) using pooled FileModel and RandomAccess for zero-allocation disk writes.

    • Seamlessly delegates cache synchronization to filesystem change tracking, triggering the registered InsertHandler naturally.

  • Cascading Fallback Directory Resolution (Twin-Path):

    • Automatically checks candidate source project directories (../../..) before falling back to the application base directory (bin).

    • Enables seamless hot-reloading when modifying code files during development while ensuring production deployments run reliably from bin.

  • Safe Freeze Protection:

    • Calling Freeze() while in lazy mode is safely ignored (no-op), preventing accidental transition into an immutable dictionary.

v6.12.0

Release Date: October 2026 | Target: .NET 9.0

New Features

  • Zero-Allocation SubsetSampler:

    • Introduced high-speed sampling algorithms to select random subsets of elements from collections or spans.

    • Implemented non-allocating reservoir sampling for streaming inputs and in-place Fisher-Yates sampling over Span<T>.

    • Ideal for game loot drops, matchmaking pool selection, and batch item distribution.

v6.11.0

Release Date: October 2026 | Target: .NET 9.0

New Features & Enhancements

  • SpatialGrid 2D Partitioning:

    • Replaced the legacy SpatialHash with SpatialGrid, offering a contiguous 2D grid structure.

    • Supports high-throughput radial queries (Area of Effect / AOE) using caller-provided reusable buffers with zero heap allocations.

    • Dynamic radius shrinking accelerates nearest-neighbor searches in crowded simulation environments.

v6.10.0

Release Date: October 2026 | Target: .NET 9.0

Performance & Core Primitives

  • Monotonic Application Time:

    • Upgraded application time tracking (Time.time) to high-resolution monotonic millisecond precision, eliminating clock drift and leap second jumps.

  • Abstract Event Scheduling Base:

    • Introduced the Event abstract class implementing IComparable<Event> based on simulation Tick.

    • Designed to interface seamlessly with priority min-heaps and hierarchical timing wheels.

v6.9.0

Release Date: October 2026 | Target: .NET 9.0

New Data Structures

  • \(O(1)\) AliasTable (Vose's Method):

    • Added a high-speed alias table implementation for non-uniform discrete probability distributions.

    • After a one-time \(O(N)\) setup, sampling any random item occurs in deterministic \(O(1)\) constant time with two random numbers.

v6.8.0

Release Date: October 2026 | Target: .NET 9.0

New Data Structures

  • FenwickRandom Sampling:

    • Added a Binary Indexed Tree (Fenwick Tree) sampling engine for dynamic probability distributions.

    • Supports dynamic weight updates and random sampling in \(O(\log N)\) time, making it ideal for systems with changing probabilities.

v6.7.0

Release Date: October 2026 | Target: .NET 9.0

Optimizations

  • Vectorized WeightedRandom:

    • Refactored WeightedRandom to use a monotonic prefix-sum array with SIMD-accelerated binary search routines.

    • Significantly reduced branching penalties on modern x86-64 and ARM64 CPUs.

v6.6.0

Release Date: September 2026 | Target: .NET 9.0

Architecture & Core Storage

  • High-Throughput Logging Primitives:

    • Added lock-free ring-buffer primitives in core memory to serve high-frequency logging streams.

    • Provided core interfaces for zero-allocation formatting into raw UTF-8 spans.

v6.5.0

Release Date: September 2026 | Target: .NET 9.0

Simulation Engine

  • Tick Dispatching Optimization:

    • Optimized discrete simulation event queues, reducing context switching overhead during high-frequency dispatch cycles.

    • Enhanced test harnesses for discrete simulation events and heap ordering.

v6.4.0

Release Date: September 2026 | Target: .NET 9.0

New Data Structures

  • Hierarchical TimingWheel:

    • Introduced a high-capacity multi-level timing wheel scheduler capable of managing millions of concurrent timers with \(O(1)\) insert, cancel, and tick operations.

  • HeapQueue<T> Min-Heap:

    • Added a contiguous zero-allocation binary min-heap for priority-ordered event queues.

v6.3.0

Release Date: September 2026 | Target: .NET 9.0

Memory & Buffer Utilities

  • Structural Slicing & Casting:

    • Added Buffer.AsStruct<T>() for zero-copy mapping of raw buffer windows into unmanaged structs.

    • Expanded Utf8Map with longest-prefix hierarchical routing (TryResolvePrefix) for URL routing and endpoint dispatching.

v6.2.0

Release Date: September 2026 | Target: .NET 9.0

SIMD Optimizations & Low-Level I/O

  • SIMD Case-Insensitive Equality:

    • Accelerated Buffer.Equals case-insensitive byte comparisons using SIMD vector instructions.

  • FileModel Positional I/O:

    • Implemented FileModel backed by OS file handles (SafeFileHandle) and .NET RandomAccess APIs to eliminate stream abstraction overhead.

v6.1.0

Release Date: September 2026 | Target: .NET 9.0

Breaking Changes

  • Facade Decoupling:

    • Decoupled the Lucifer runtime facade, bootstrap, and configuration helpers to the LuciferCore.Platforms package.

    • LuciferCore now functions strictly as a lightweight, zero-allocation microkernel engine.

  • ObjectPool Standardization:

    • Replaced direct Lucifer.Rent/Return calls with unified ObjectPool.Rent<T>() and ObjectPool.Return<T>().

  • Static DI Overhaul:

    • Migrated model resolution and dependency mapping to DIExtensions.

v6.0.0

Release Date: September 2026 | Target: .NET 9.0

Major Architecture Shift

  • Modulith Core on .NET 9:

    • Complete re-architecture of the Lucifer ecosystem designed for high-throughput, low-latency microservices and game server backends.

  • Span-First & Zero-Allocation Pipeline:

    • Core transport protocols (TCP, UDP, SSL, UDS, HTTP, WebSocket) re-engineered around raw memory spans and lock-free pooled buffers.
Edit this page