ProphetsWay.Logger 4.0.0

Prefix Reserved
dotnet add package ProphetsWay.Logger --version 4.0.0
                    
NuGet\Install-Package ProphetsWay.Logger -Version 4.0.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="ProphetsWay.Logger" Version="4.0.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="ProphetsWay.Logger" Version="4.0.0" />
                    
Directory.Packages.props
<PackageReference Include="ProphetsWay.Logger" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add ProphetsWay.Logger --version 4.0.0
                    
#r "nuget: ProphetsWay.Logger, 4.0.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package ProphetsWay.Logger@4.0.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=ProphetsWay.Logger&version=4.0.0
                    
Install as a Cake Addin
#tool nuget:?package=ProphetsWay.Logger&version=4.0.0
                    
Install as a Cake Tool

ProphetsWay.Logger

Route log messages to console, file, event, or custom destinations with per-destination severity and label selection.

Current tree: unreleased v4 work. The app variables select 4.0.0; v4 remains unreleased. Logger's optional Linux/macOS jobs are configured and enabled for CI. Initial hosted Linux/macOS attempts failed; no passing native Linux/macOS verification is recorded. Hosted reruns remain required; Windows success and ABI declaration proxies do not certify them. Explicit-registration route isolation and ordered membership snapshots (M2-B) are implemented. Native M3 scopes, entry annotations, full captured context, registration settings and whole-entry label selection are now implemented alongside the six native severities. M4-A adds shared UTC event time, invariant value rendering and quoted single-line text with native scope boundaries. M4-B1 implements explicit-file append/reset, fixed-path output and physical encoding/termination. M4-B2 now integrates ordinary and exact-T automatic output into one shared UTF-8 session file, with initial-only recovery and remembered initialization failure. M5 carrier data and both explicit Microsoft bridge directions are implemented in current source: Microsoft-to-Logger inbound and opt-in Logger-to-Microsoft outbound. Configuring one direction does not enable the reverse. Supplied destinations use guarded entrypoints and protected LogCore hooks; subclasses must migrate their old Log overrides. This describes current source, not the published NuGet package, a completed final acceptance gate, or release certification.

Build Status:
Build Status

Why Logger

When you need both a detailed log and a warning/error view, repeating each logging call for each output adds unnecessary work. Configure destinations once at application startup; plain Logger calls reach enabled registered destinations whose severity and label restrictions accept the entry.

  • Send the same message to console, files, or callbacks with different reporting levels.
  • Pass application metadata to typed destinations without putting it into message text.
  • Carry application-defined labels and scope properties, withholding the whole entry from destinations whose configured policies reject it.
  • Evaluate the same label policy independently when you need a membership-only decision.

Configure your intended destinations explicitly. The automatic file is quick-start behavior, not a substitute for choosing output paths, access controls, and retention.

Install

For a published package, use the .NET CLI:

dotnet add package ProphetsWay.Logger

Or use Visual Studio's NuGet Package Manager Console:

Install-Package ProphetsWay.Logger

These commands do not install the unreleased API merely because it is documented here. To use the native severity, scope/context, label-policy, text/formatter examples, or either Microsoft logging bridge direction now, reference the current library project from your application. app-variables.yml selects 4.0.0 for this unreleased v4 work; no v4 package or release is claimed.

Current Source Targets

Project Targets Meaning
Library netstandard2.0;net10.0 .NET Standard 2.0 compatibility floor plus a dedicated .NET 10 asset.
Tests net48;net10.0 Windows Framework verification uses the Standard 2.0 library; .NET 10 tests use its dedicated asset.
Example net10.0 Console example, built but not run in the focused validation below.

There is no separate net48 library asset. Older modern runtimes compatible with .NET Standard 2.0 can still use that floor; removing their dedicated assets does not automatically strand them. Consumers requiring pre-Standard-2.0 reach cannot use this new target set. Verification is currently Windows-focused, not equivalent Mac/Linux proof.

The library's sole direct package reference is Microsoft.Extensions.Logging.Abstractions 10.0.12, unconditional for both targets. It flows to consumers together with its normal transitive dependencies through NuGet resolution. Both Microsoft bridge directions described below are implemented in current source. This does not mean the currently published package contains either bridge.

Package Contents And Source Metadata

The unreleased M6 packaging update retains both library assets above. The local package inspection on 2026-09-29 EDT verified the outputs below before the Microsoft.Extensions.Logging.Abstractions dependency was added. These are historical observations, not a package built or validated from the current dependency-bearing candidate:

Package detail Verified output or setting
Library and XML documentation The .nupkg contains DLL/XML pairs for netstandard2.0 and net10.0, with 177 documented member entries per XML file. GenerateDocumentationFile is true; missing public XML comments still produce compiler warnings, so this is not complete API documentation.
Symbols IncludeSymbols=true and SymbolPackageFormat=snupkg produce a separate .snupkg with one portable PDB per library asset.
Source metadata PublishRepositoryUrl=true and EmbedUntrackedSources=true are enabled. Each inspected PDB has 38 document records, two embedded sources and a Source Link map targeting commit e7cbc016ffe47a66559ed67750d87641c6e7ca6b. This does not mean every source file is embedded.
Package metadata The package retains its README, changelog and icon, and now carries the repository homepage, tags logging, logger, diagnostics, and repository kind git.

These settings are in the library project. Its reproducibility-related ContinuousIntegrationBuild setting is true only when TF_BUILD is True; local evaluation left it unset, while CI-mode evaluation returned true. Property evaluation is not proof of reproducible binaries. The measured Source Link metadata also does not prove remote-source availability or an end-to-end debugger experience.

As of 2026-10-01, recorded restore reuse is accepted under the narrow SDK-01 exception for the SDK-owned library-packs source; restore was not rerun. The fresh R3 Windows baseline passed three builds and 672 selected tests on each of net48 and net10.0, with zero failures, skips or test identity changes. Baseline results alone do not establish independent assertion equivalence, final verification, current-candidate package qualification or bridge completion. The earlier package observations above remain historical.

This is historical, partial M6 evidence, not full qualification or release approval. At the time of this 2026-10-01 record, inbound was present and outbound had not yet been implemented; later M5 source adds outbound destinations, described below. Remaining assertion migration, the owner-handled test-project rename, broader consumer/security qualification and deferred non-Windows proof remain separate. At that historical checkpoint the version file selected the pre-v4 release; this update changed neither that selection nor publication status.

2026-10-24 annotation: D025 records explicit owner approval of the test-project rename and accompanying infrastructure/docs. The deferral above describes the historical M6 checkpoint, not a pending approval request. Approval and updated guidance do not establish completed rename verification.

Quick Start

Each C# block below is independent, with its own imports, enclosing types and static entry method, written for C# 7.3 library compilation. Call its Main or Run method only when you intend its output. Examples use current declarations and test call patterns. Expected output describes the source contract, not a recorded execution of these programs.

Log To The Console

Register before logging to avoid implicit file creation. Retain the destination reference so you can remove it. This follows the calls in ConsoleDestinationTests.cs.

Illustrative — not currently present in the repo.

using ProphetsWay.Utilities;
using ProphetsWay.Utilities.LoggerDestinations;

public static class Program
{
    public static void Main()
    {
        var destination = new ConsoleDestination(LogLevels.Trace);
        Logger.AddDestination(destination);
        try
        {
            Logger.Trace("Detailed startup trace.");
            Logger.Debug("Hello World!");
        }
        finally
        {
            Logger.RemoveDestination(destination);
        }
    }
}

The messages use invariant UTC timestamps, quoted single-line text and exact emitted levels, TraceOnly and DebugOnly; see Record Layout. The explicit Trace destination mask accepts all six severities; the constructor's unchanged default Debug mask does not accept Trace. Logger.ClearDestinations() clears plain registrations; Logger.ClearDestinations<T>() clears registrations for that metadata type. Removing or clearing does not dispose your destinations. Do not log after removing the last destination unless you intend fallback. For no-setup output and optional startup configuration, see Automatic File Output.

Evaluate A Label Policy

This example does not call Logger or write a log file. The identifiers are synthetic, not predefined classifications. The rules and copied-membership behavior are exercised in DestinationLabelPolicyTests.cs.

Illustrative — not currently present in the repo.

using System;
using System.Collections.Generic;
using ProphetsWay.Utilities;

public static class Program
{
    public static void Main()
    {
        var personal = new SensitivityLabel("PII");
        var internalUse = new SensitivityLabel("Internal");
        var configured = new List<SensitivityLabel>
        {
            personal, internalUse, new SensitivityLabel("PII")
        };
        var allow = new DestinationLabelPolicy(LabelFilterMode.AllowOnly, configured);
        configured.Clear();

        Console.WriteLine(personal.Equals(new SensitivityLabel("PII")));
        Console.WriteLine(allow.Mode);
        Console.WriteLine(allow.Labels.Count);
        Console.WriteLine(allow.Allows(new[] { personal, internalUse }));
        Console.WriteLine(allow.Allows(new[] { new SensitivityLabel("pii") }));
        Console.WriteLine(allow.Allows(new SensitivityLabel[0]));

        var exclude = new DestinationLabelPolicy(LabelFilterMode.Exclude, new[] { personal });
        Console.WriteLine(exclude.Allows(new[] { internalUse }));
        Console.WriteLine(exclude.Allows(new[] { personal, internalUse }));

        var noFilter = new DestinationLabelPolicy(LabelFilterMode.NoFilter, new SensitivityLabel[0]);
        Console.WriteLine(noFilter.Allows(new[] { personal }));
    }
}

Expected output from the source/test contract, not a recorded execution of this snippet:

True
AllowOnly
2
True
False
False
True
False
True

Allows returns only label eligibility. It neither registers a destination nor intercepts a later Logger.Debug call by itself. Attach the policy through registration settings or a supplied destination's LabelPolicy to enforce it during delivery.

Attach Scopes And Read Delivered Context

Use scopes for labels and properties shared by an operation, and LogAnnotated for labels specific to one entry. This event recipient accepts only entries whose complete effective label set is nonempty and contained in its configured membership. All data here is synthetic; the example creates no file. The scope and context assertions live in LoggerTests.cs.

Illustrative — not currently present in the repo.

using System;
using System.Collections.Generic;
using ProphetsWay.Utilities;
using ProphetsWay.Utilities.LoggerDestinations;

public static class ScopeExample
{
    public static void Run()
    {
        var internalUse = new SensitivityLabel("Internal");
        var personal = new SensitivityLabel("PersonalData");
        var policy = new DestinationLabelPolicy(
            LabelFilterMode.AllowOnly, new[] { internalUse, personal });
        var destination = new EventDestination(LogLevels.Trace);
        destination.LoggingEvent += ReadEntry;
        Logger.AddDestination(destination,
            new DestinationRegistrationSettings(true, LogLevels.Trace, policy));

        var properties = new List<KeyValuePair<string, object>>
        {
            new KeyValuePair<string, object>("Step", "Receive"),
            new KeyValuePair<string, object>("Step", "Validate")
        };
        try
        {
            using (Logger.BeginScope(null, properties))
            {
                properties.Clear();
                using (Logger.BeginScope(new LogAnnotations(new[] { internalUse, internalUse })))
                {
                    Logger.LogAnnotated(new LogAnnotations(new[] { personal }),
                        LogLevels.InformationOnly, message: "Synthetic request.");
                }
            }

            Logger.SetDestinationSettings(destination, new DestinationRegistrationSettings(
                true, LogLevels.Trace,
                new DestinationLabelPolicy(LabelFilterMode.AllowOnly, new SensitivityLabel[0])));
            Logger.Info("Deliberately rejected without activating fallback.");
        }
        finally
        {
            Logger.RemoveDestination(destination);
        }
    }

    private static void ReadEntry(object sender, EventDestination.LoggerEventArgs entry)
    {
        var context = entry.Context;
        Console.WriteLine(entry.RawMessage);
        foreach (var label in context.Labels.EffectiveLabels)
            Console.WriteLine("Effective label: {0}", label.Identifier);
        foreach (var origin in context.Labels.Origins)
            Console.WriteLine("{0}: scope {1}, occurrence {2}", origin.Label.Identifier,
                origin.ScopeIndex.HasValue ? origin.ScopeIndex.Value.ToString() : "entry",
                origin.OccurrenceIndex);
        foreach (var frame in context.Scopes)
            foreach (var property in frame.Properties)
                Console.WriteLine("{0}: {1}", property.Key, property.Value);
    }
}

The unlabeled outer frame keeps both Step pairs despite properties.Clear(). The repeated Internal label contributes separate origins but one effective identity. Origin scope indices address context.Labels.ScopeAnnotations, so they do not count that unlabeled outer frame. The final settings replacement keeps an enabled reject-all registration; it does not remove the recipient or cause automatic output. The callback explicitly formats its synthetic property values; Logger itself does not implicitly format arbitrary scope objects.

Core Concepts

Namespaces

The package and assembly are ProphetsWay.Logger; the utility namespace deliberately differs.

Import Use
ProphetsWay.Utilities Logger, LogLevels, ordinary destination contracts/bases, label/policy types, LogAnnotations, scope/context types and DestinationRegistrationSettings.
ProphetsWay.Utilities.LoggerDestinations ConsoleDestination, FileDestination, EventDestination, GenericEventDestination<T>, TextBasedDestination, GenericTextBasedDestination<T>.
ProphetsWay.Utilities.Generics ILoggingDestination<T>, IContextLoggingDestination<T>, BaseLoggingDestination<T>, ILoggerMetadata, and metadata extension methods.

Severity Selection

These are the current source values in LogLevels.cs. Each helper emits one exact bit; an inclusive destination setting accepts that severity and every more severe one.

Helper Exact message bit Inclusive destination mask Accepted severities
Trace TraceOnly = 32 Trace = 63 Trace, Debug, Information, Warning, Error, Critical.
Debug DebugOnly = 16 Debug = 31 Debug, Information, Warning, Error, Critical.
Info InformationOnly = 8 Information = 15 Information, Warning, Error, Critical.
Warn WarningOnly = 4 Warning = 7 Warning, Error, Critical.
Error ErrorOnly = 2 Error = 3 Error, Critical.
Critical Critical = 1 Critical = 1 Critical only.

LogLevels is an Int32 flags enum with these eleven names. There is no CriticalOnly, None, or All alias. Use an exact bit as the destination mask for just that severity, or combine bits with |. Security and SecurityOnly have been removed.

Destination masks accept every integer from 0 through 63, including unnamed combinations. Zero is an active reject-all destination, not an absent registration or a reason to use fallback. Raw/direct message masks accept 1 through 63, never zero. Eligibility requires (messageLevel & destinationMask) == messageLevel: message mask 9 passes destination 15 but fails destination 8. A valid mismatch returns normally without delivery.

The core's enum, integer and string constructors preserve equivalent accepted bits. Strings use case-sensitive Enum.TryParse<LogLevels> grammar: decimal Int32 text or comma-separated recognized names, with its surrounding/token whitespace handling. Signs and leading zeroes follow that parser too: " +009 " is 9 and "-0" is zero. "0", "9", " +9 ", and "Critical, InformationOnly" are valid; duplicate names combine by OR. Empty/whitespace-only text, wrong-case names, removed/unknown names, empty comma tokens, "Critical|InformationOnly", "Critical, 8", "1, 8", "0x9", overflow, negative values and unknown bits are rejected. Invalid text no longer silently selects Information. Prefer named masks; configure LogLevels.Trace explicitly when you need all six severities.

Label Identity

SensitivityLabel.cs defines a sealed immutable reference value. Identifier retains exactly what you supplied: 1 through 256 UTF-16 code units, with no unit accepted by Char.IsWhiteSpace or Char.IsControl on the executing runtime. There is no other syntax restriction, trimming, case folding, Unicode normalization, or registry.

Use Equals or collection value comparisons: separate labels with the same ordinal identifier are equal; PII and pii are distinct. No value-equality == operator is supplied. Equal labels have equal hashes, but hashes are neither unique nor a persistent or cryptographic identity. See SensitivityLabelTests.cs.

Annotation Occurrences

LogAnnotations.cs provides a sealed immutable value for one explicit label attachment. Construct it with LogAnnotations(IEnumerable<SensitivityLabel> labels) and read its getter-only ReadOnlyCollection<SensitivityLabel> LabelOccurrences. Construction copies the complete finite sequence before returning: empty is valid, order and every repeated occurrence survive, and later source additions, removals or replacements cannot change the captured value.

These are occurrences, not the deduplicated membership used by DestinationLabelPolicy. Labels retain SensitivityLabel's ordinal value equality; LogAnnotations does not define annotation-value equality. Reusing a value does not combine attachments or merge their origins. Construction alone attaches nothing. Pass it to Logger.BeginScope or Logger.LogAnnotated; ordinary and typed convenience helpers inherit scopes without adding an entry annotation. See LogAnnotationsTests.cs.

Scopes And Captured Context

Logger.BeginScope(annotations) opens a label-only frame; the two-argument form also captures an ordered sequence of KeyValuePair<string, object>. A null annotation means no attachment; a non-null empty annotation is retained as an explicit empty attachment. Neither subtracts outer labels. Opening a scope does not log anything or change registrations.

Read the completed LogContext from a permitted event or contextual recipient:

Readback Meaning
context.EventTimestampUtc Getter-only DateTimeOffset with offset zero, captured once for this call before recipient callbacks.
context.Scopes Every frame, outermost first, including inherited, empty and unlabeled frames. Each exposes Annotations and Properties.
context.Labels.EntryAnnotations This entry's explicit attachment, or null.
context.Labels.ScopeAnnotations The ordered non-null annotation projection of Scopes; empty attachments and repeated uses remain separate.
context.Labels.Origins One record per occurrence, scope attachments first then entry; each has Label, ScopeIndex and OccurrenceIndex.
context.Labels.EffectiveLabels The complete ordinal-identity union of all origins, with duplicates removed; ordering is unspecified.

All selected contexts and supplied text records from one originating call share that UTC value, including same-call internal forwarding. Retained contexts keep it after scope exit. Recursive Logger calls and supplied-base public direct calls sample anew; distinct or increasing values and cross-thread ordering are not promised. This is event time, not filename or output time.

ScopeIndex is zero-based into ScopeAnnotations, not Scopes; null identifies the entry. OccurrenceIndex is zero-based within that attachment's LabelOccurrences. Empty attachments occupy projection positions but contribute no origins. Inherited-only labels count as labeled. Context/frame/origin values are library-created, with no public constructors or ambient-capture factory; readback is data, not reusable delivery permission.

Properties are copied membership, not a dictionary or a deep clone. Pair order, duplicate keys, null/empty/whitespace keys, default pairs and original values/references survive. Later source-list changes and scope exit cannot alter captured membership; nested objects can still change. Logger does not inspect getters, enumerate nested values, call their ToString, classify them or strip capabilities already reachable through them. Retaining recipients own safe retention and later cleanup. See LogScopeFrame.cs and LogContext.cs.

Use using blocks and dispose each handle only in the opening operation or its normal continuation, including across await. Normally captured child work inherits active frames; its own scope additions/cleanup do not change parent or sibling frames. A child can outlive parent scope exit and retain the captured labels. Deliberately suppressing execution-context flow prevents inheritance by newly queued work, without clearing the caller or earlier captures. Explicitly passed objects still require your classification.

Cleanup removes the handle's frame when current, throws InvalidOperationException without mutation when it is below another active frame, and is a no-op when locally absent, including repeat cleanup after unrelated scopes open. Handles are non-transferable: do not delegate their disposal to independent work. There is no creator-ID/fork workflow or promise to detect every inherited-handle misuse. Supported inner scopes cannot remove inherited labels; deliberate or accidental handle misuse is not sandboxed. Ending a scope disposes neither destinations nor property values and does not revoke or erase captures. This is the accepted D024 discipline in docs/decision-log.md.

Policy Membership

LabelFilterMode is not a flags enum. Construct a policy with exactly one mode and a non-null sequence of non-null labels. Mode is getter-only; Labels is an owned ReadOnlyCollection<SensitivityLabel> containing one representative per configured identity, even for NoFilter. Later changes to the source collection cannot change the policy.

Mode Result for valid effective labels
NoFilter = 0 Always true, including unlabeled input; still validates input.
Exclude = 1 True only when no effective identity is configured. Any intersection denies.
AllowOnly = 2 True only for nonempty effective membership wholly contained in configured membership.

Empty Exclude permits every valid input; empty AllowOnly denies every valid input. Duplicates and ordering do not change matching. Unknown valid identities participate normally. When calling Allows yourself, supply all effective labels, including inherited ones: the predicate alone does not collect scopes or origins. Logger supplies the full captured union when enforcing registration and supplied-destination policies.

Registration Settings

DestinationRegistrationSettings(bool enabled, LogLevels reportingLevel, DestinationLabelPolicy labelPolicy) requires all three arguments and exposes getter-only Enabled, ReportingLevel and LabelPolicy. Pass it to Logger.AddDestination(destination, settings) or its exact-T overload. The original one-argument add means enabled, registration mask Trace (63), and empty NoFilter: no added restriction, not an override of the recipient's own severity mask.

Logger.SetDestinationSettings(destination, settings) and its generic form replace all settings atomically on an existing registration, preserving its insertion position. They are not upserts. Existing captures keep their old settings; later captures, including recursive logging, see published replacements. Sharing a settings value across routes does not couple future replacements.

An enabled registration suppresses fallback even when its mask is zero or its policy rejects everything. A disabled registration retains its position and duplicate identity but is neither attempted nor counted for fallback suppression. Disabling the last enabled recipient can therefore reactivate existing fallback behavior; disabling and rejecting are not interchangeable.

Supplied destinations also expose LabelPolicy, initially empty NoFilter, through LoggingDestinationCore. Replacing it atomically changes that destination's own restriction, including direct calls, not its registration settings. Delivery must pass the registration mask, recipient severity permission, registration policy and supplied policy. Logger captures supplied policies before callbacks too; an earlier callback cannot change a later recipient's checks for the current call. No global transaction across separate destination objects is promised.

M5 Carrier Data

The current source implements three public data types in ProphetsWay.Utilities, with internal, library-only constructors. There is no public constructor or entry-construction factory; the inbound provider described below creates entries from Microsoft logging calls.

Type Captured data
LogBridgeEntry.cs: LogBridgeEntry Common view: CategoryName, nullable EventId, full nonzero native OriginalLevel, separate RawMessage and cached FormattedMessage, original Exception, ordered Properties, external Scopes, explicit Annotations, original NativeContext and separate BridgeMetadata.
LogBridgeEntryOfT.cs: LogBridgeEntry<TState> Sealed typed entry retaining original State and exact ProducerFormatter delegate, including absent/default inputs. StateType is the declared typeof(TState); OriginalState and OriginalProducerFormatter expose the common views.
LogBridgeScope.cs: LogBridgeScope Sealed external frame retaining opaque/scalar State, ordered Properties and explicitly mapped Annotations; data, not a live scope or disposal handle.

Owned read-only membership preserves supplied order, duplicate keys, null keys/values, default pairs, repeated frames and label occurrences despite later source-list edits. An absent EventId differs from a present default value; available identity includes its name. An absent annotation differs from a present-empty attachment. Bridge-owned metadata does not overwrite identically named application properties.

NativeContext keeps its original native frames and origin indices. External origins belong to the entry attachment or a position in Scopes, then that attachment's occurrence position. The domains remain separate, without reindexing or inventing cross-system order.

Read-only membership is not deep freezing or authorization. Original state, exception and nested objects can remain mutable or sensitive; the retained delegate is an executable capability. Construction/readback does not invoke it, inspect nested graphs, classify payloads, open ambient scopes or dispose supplied objects. You own safe retention and later handling.

The carriers themselves perform no delivery, scope replay or private cycle control. Their construction/readback specifications concern this data component, not current-package qualification or release readiness.

The public IMicrosoftLogLabelMapper interface in ProphetsWay.Utilities is also available in current source. MapEntry<TState> and MapScope return optional LogAnnotations for an external entry or scope frame, respectively; null means no attachment. Both accept ordered, read-only properties as ReadOnlyCollection<KeyValuePair<string, object>>; state and nested values are not frozen. You supply classification explicitly; this is not automatic classification or sanitization.

Microsoft Logging Inbound Bridge

The current source exposes MicrosoftLoggerFactoryExtensions.AddProphetsWay(ILoggerFactory, IMicrosoftLogLabelMapper = null). An explicit call creates one MicrosoftLoggerProvider, registers that provider with the supplied factory, and returns the same provider. It is a factory extension, not dependency-injection or host configuration. MicrosoftLoggerProvider.CreateLogger creates category-bound MicrosoftLogger instances that share the provider's lifetime and scope source.

Inbound entries are dispatched through the exact LogBridgeEntry metadata route; the payload retains its concrete LogBridgeEntry<TState> type. The optional mapper is borrowed and is invoked only when explicitly supplied to map external entries and scope frames to optional annotations. The factory is also borrowed. The host must arrange provider cleanup, either by explicitly disposing the returned provider or through the factory/provider's normal lifetime handling; provider disposal is idempotent. The provider does not dispose the factory, mapper, a caller-supplied external scope source, or native destinations. The provider starts with its own logical-flow scope source; a source supplied through factory scope integration is borrowed. The caller/factory remains responsible for disposing scope handles through that source's normal cleanup.

This is current unreleased source behavior, not a claim that the published package includes the bridge. Enabling inbound does not install outbound; the outbound direction is a separate, explicitly registered destination path described next. This documentation does not claim M5/M6 completion, current-package qualification, or release readiness.

Microsoft Logging Outbound Destinations

To send native Logger entries to Microsoft logging abstractions, construct and explicitly register a destination. Construction alone does not register it, create an inbound provider, or configure a host. The ordinary and exact-declared-T destinations have these public constructors:

Destination Public constructors
MicrosoftLoggerDestination MicrosoftLoggerDestination(LogLevels reportingLevel, ILoggerFactory factory, string defaultCategoryName = "ProphetsWay.Logger"); MicrosoftLoggerDestination(LogLevels reportingLevel, ILogger logger)
GenericMicrosoftLoggerDestination<T> GenericMicrosoftLoggerDestination<T>(LogLevels reportingLevel, ILoggerFactory factory, string defaultCategoryName = "ProphetsWay.Logger"); GenericMicrosoftLoggerDestination<T>(LogLevels reportingLevel, ILogger logger)

Register the ordinary destination with Logger.AddDestination(destination) and an exact route with Logger.AddDestination<T>(destination), where T is the declared native metadata type used by that route. Runtime subtype compatibility does not select the exact-T route. The factory and fixed logger overloads are alternatives; the factory overload creates a logger for each admitted attempt, using the source category when available and defaultCategoryName only when that category is null. Empty or whitespace categories are retained as supplied. A fixed logger keeps its own category. The default factory category is ProphetsWay.Logger.

The reportingLevel constructor argument must be a known native mask from 0 through 63; zero is a valid active reject-all mask. Native registration severity and label policies are evaluated before Microsoft callbacks. The adapter maps the lowest set bit of the permitted native mask to one Microsoft level (Critical, Error, Warning, Information, Debug, or Trace) and retains the complete original mask in the bridge entry. It calls ILogger.IsEnabled once for that mapped level; false is an ordinary rejection, not a failure or a reason to activate fallback. A composite mask is not expanded into multiple Microsoft records.

For a fresh ordinary native call, the entry's typed state is the original message string; for an exact-T call, it is the original declared-T metadata, including null or default(T). The completed LogBridgeEntry retains available category/event identity, original mask, exception, state, formatted text, and ordered structured properties when metadata supplies IEnumerable<KeyValuePair<string, object>>, as well as annotation/context facts. Other metadata remains opaque; application property membership and duplicate keys are preserved rather than flattened. A controlled return from the inbound bridge preserves its original typed entry and producer-formatter association rather than wrapping the entry as new metadata or re-running its producer formatter; a fresh call with carrier-shaped metadata is still a new event. Private transfer bookkeeping suppresses only a route already visited by that same controlled entry; the guard is not enumerable state, and fresh or unrelated recursive calls remain eligible. The Microsoft call receives an internal ordered transport envelope with three separate items: ProphetsWay.Entry, ProphetsWay.NativeContexts, and ProphetsWay.ExternalScopes. The native-context group retains the source capture first, then distinct controlled/current captures in encounter order; only a capture already present by reference is omitted, not a distinct capture with overlapping frames or labels. Event properties remain inside the entry; native contexts and external scope frames are not flattened into application properties. Scope replay supplies a separate one-frame envelope per native or external frame, preserving each frame's state/properties/annotations and occurrence; native frames follow context order and each capture's outer-to-inner order, then external frames follow their retained order. Existing Microsoft host scopes remain in place; successfully returned scope handles are cleaned up in reverse opening order. A null BeginScope result means there is no handle to clean up, not a failed scope capture.

Native labels and explicitly mapped external annotations remain distinct from application properties and are evaluated as whole-entry policy before the destination's Microsoft callbacks. The bridge does not infer labels from property names, classify or sanitize payloads, or promise that consumer-owned state is safe to retain. The destination borrows its supplied factory or fixed logger; Logger registration, removal, clearing, or replacement does not dispose them. The adapter owns only per-attempt transport/bookkeeping and returned scope-handle cleanup. Calls are synchronous; there is no category cache, queue, retry, remote-delivery receipt, or durability guarantee. An IsEnabled rejection is normal; factory, logger, scope, or cleanup failures follow Logger's safe output-failure reporting and propagation contract after independent eligible attempts.

API Reference

The tables summarize the current declarations, not proposed APIs.

Member Current use
SensitivityLabel(string identifier) Create an immutable identity; read Identifier, compare with Equals, use GetHashCode for collections.
LogAnnotations(IEnumerable<SensitivityLabel> labels) Copy one attachment's ordered label occurrences, including repeats; empty input is valid.
MicrosoftLoggerDestination(...) Opt-in ordinary outbound route to a borrowed Microsoft logger or factory.
GenericMicrosoftLoggerDestination<T>(...) Opt-in outbound route for exactly declared native metadata type T.
LogAnnotations.LabelOccurrences Getter-only ReadOnlyCollection<SensitivityLabel>; captured occurrence count and order stay fixed.
DestinationLabelPolicy(LabelFilterMode mode, IEnumerable<SensitivityLabel> labels) Required mode and configured membership; no default constructor.
DestinationLabelPolicy.Mode / Labels Read the selected mode and copied, unique, read-only membership.
DestinationLabelPolicy.Allows(IEnumerable<SensitivityLabel> effectiveLabels) Synchronous Boolean membership decision; no output operation.
Logger.AddDestination / RemoveDestination / ClearDestinations Manage plain registrations; generic overloads manage registrations keyed by T.
Logger.ConfigureAutomaticFileHostDirectory(string directory) Set only the automatic file's primary directory before initial establishment starts; no filesystem I/O or recipient registration.
ILoggerMetadata / MetadataExtensions Optional empty marker and the six metadata extension helpers below.

Native Scope And Delivery Members

These producer methods belong to Logger; generic T is unconstrained. The settings and context types are in ProphetsWay.Utilities.

Member Current use
BeginScope(LogAnnotations annotations) Return a LogScopeHandle; null opens an unlabeled frame with empty properties.
BeginScope(LogAnnotations annotations, IEnumerable<KeyValuePair<string, object>> properties) Capture the complete property sequence before opening the frame.
LogAnnotated(LogAnnotations annotations, LogLevels level, string message = null, Exception ex = null) Ordinary raw entry with optional explicit annotations and mask 1-63.
LogAnnotated<T>(LogAnnotations annotations, LogLevels level, T metadata, string message = null, Exception ex = null) Exact-T raw entry; metadata remains separate from annotations.
AddDestination(ILoggingDestination newDest, DestinationRegistrationSettings settings) Register an ordinary borrowed recipient with explicit settings.
AddDestination<T>(ILoggingDestination<T> newDest, DestinationRegistrationSettings settings) Register only on the declared metadata route.
SetDestinationSettings(ILoggingDestination destination, DestinationRegistrationSettings settings) Replace an existing ordinary registration's complete settings.
SetDestinationSettings<T>(ILoggingDestination<T> destination, DestinationRegistrationSettings settings) Replace settings only on that exact-T route.
LoggingDestinationCore.LabelPolicy Get/replace the supplied destination's additional immutable policy, including direct delivery.
IContextLoggingDestination.LogWithContext(LogContext context, LogLevels level, string message = null, Exception ex = null) Optional ordinary full-context receiver.
Generics.IContextLoggingDestination<T>.LogWithContext(LogContext context, LogLevels level, T metadata, string message = null, Exception ex = null) Optional exact-T full-context receiver.
Logger.DispatchFailed / LogDispatchException.Report Observe bounded original-failure facts; see the distinct return/throw policies below.

LogAnnotated uses raw rules: null message/exception and null annotations are valid, even at ErrorOnly or Critical. It is not a convenience helper with their required arguments. Null/default metadata is valid, and even T = LogAnnotations is only metadata, never an implicit label source. Use an explicit generic invocation when inference would not select the route you intend.

All Eighteen Helper Forms

All helpers return void. Ordinary and typed methods belong to ProphetsWay.Utilities.Logger; typed T is unconstrained. Extensions belong to ProphetsWay.Utilities.Generics.MetadataExtensions and each has only where T : ILoggerMetadata. Parameter order and optional defaults are:

Ordinary Logger method Typed Logger method Metadata extension declaration
Trace(string message) Trace<T>(string message, T metadata) Trace<T>(this T metadata, string message)
Debug(string message) Debug<T>(string message, T metadata) Debug<T>(this T metadata, string message)
Info(string message) Info<T>(string message, T metadata) Info<T>(this T metadata, string message)
Warn(string message, Exception ex = null) Warn<T>(string message, T metadata, Exception ex = null) Warn<T>(this T metadata, string message, Exception ex = null)
Error(Exception ex, string message = null) Error<T>(Exception ex, T metadata, string message = null) Error<T>(this T metadata, Exception ex, string message = null)
Critical(Exception ex, string message) Critical<T>(Exception ex, T metadata, string message) Critical<T>(this T metadata, Exception ex, string message)

Trace/Debug/Info/Warn require a non-null message. Warn's exception may be omitted or null. Error requires a non-null exception; its context message may be omitted or null. Critical requires both exception and message. Empty and whitespace-only messages are valid and are not trimmed or replaced. Required-null checks run before routing, eligibility checks, rendering or fallback effects, even when every destination would reject the entry.

Metadata is a required argument, not a required non-null value: null and default(T) are valid. Extension receivers may also be null or value-type marker implementations. Destinations must handle the metadata values they accept; Logger does not clone or transform them.

Destinations

Destination or extension point Current use
ConsoleDestination Text output; reporting level defaults to Debug, excluding Trace.
FileDestination Required filename; defaults: Debug (excluding Trace), resetFile: false (append), EncodingOptions.UTF8; no added BOM.
EventDestination Required reporting level; subscribe to LoggingEvent.
GenericEventDestination<T> Typed callback; event arguments also expose Metadata.
ILoggingDestination / ILoggingDestination<T> Log receives severity, optional message/exception, and metadata for the generic form; IDestination supplies ValidateMessageLevel.
BaseLoggingDestination / BaseLoggingDestination<T> Pass a reporting level to the base constructor and override protected LogCore; public Log and LogWithContext are nonvirtual guards.
LoggingDestinationCore Shared severity/exception handling and the protected value-formatting hook.
TextBasedDestination / GenericTextBasedDestination<T> Ordinary/exact-T text bases; render captured context, then call your protected PrintLogEntry(string message) override once with no terminator. The typed base adds metadata.
LoggingDestinationCore.FormatValue(object value) Protected virtual string hook for metadata/property values; return unescaped text or null, or delegate to the closed scalar default.
LogContext.EventTimestampUtc Immutable call-time UTC readback; distinct from event arguments' legacy local Timestamp.

For a reusable application-specific destination, including a database destination, implement your own storage behavior behind the appropriate base. The new ordinary hook is protected override void LogCore(LogContext context, LogLevels level, string message, Exception ex); the generic hook is protected override void LogCore(LogContext context, LogLevels level, T metadata, string message, Exception ex). Neither hook declares optional arguments. This replaces the old public Log override and is a source and binary break for subclasses: rebuild and move the output body to the matching hook, using its supplied context. Existing direct callers retain the public Log signatures and optional null message/exception defaults. Independent implementations of the old destination interfaces need not adopt a context interface. No database context, schema, or WriteLogRecord API is provided by this library.

The core and these bases/event destinations accept LogLevels reportingLevel, string strReportingLevel, or int intReportingLevel constructors. Console/file constructors forward the same mask rules. ValidateMessageLevel(LogLevels messageLevel) queries eligibility without dispatching or changing the captured mask. There is no public raw Logger.Log method; Logger.LogAnnotated is the raw producer API, while destination Log methods are direct entrypoints.

Common Scenarios

Keep Detailed And Warning Logs

Choose paths whose contents and access you control. This example writes files beneath local application data and explicitly appends. With the explicit Trace mask, Debug.log receives all six severities; Warnings.log receives Warning/Error/Critical.

Illustrative — not currently present in the repo.

using System;
using System.IO;
using ProphetsWay.Utilities;
using ProphetsWay.Utilities.LoggerDestinations;

public static class Program
{
    public static void Main()
    {
        var directory = Path.Combine(
            Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData),
            "ProphetsWay.Logger.Example");
        var detailed = new FileDestination(Path.Combine(directory, "Debug.log"),
            LogLevels.Trace, resetFile: false);
        var warnings = new FileDestination(Path.Combine(directory, "Warnings.log"),
            LogLevels.Warning, resetFile: false);
        Logger.AddDestination(detailed);
        Logger.AddDestination(warnings);
        try
        {
            Logger.Trace("Trace detail.");
            Logger.Debug("Detailed diagnostic.");
            Logger.Warn("Check configuration.");
            Logger.Critical(new InvalidOperationException("Example failure."), "Cannot continue.");
        }
        finally
        {
            Logger.RemoveDestination(detailed);
            Logger.RemoveDestination(warnings);
        }
    }
}

For Debug/Information only, choose LogLevels.DebugOnly | LogLevels.InformationOnly. All three existing FileDestination overloads now default to resetFile: false; the example spells out that append choice. Explicit resetFile: true deletes only the selected existing file during construction, not on each write. Use it only for an intentional reset. Construction prepares missing parent directories but does not create a missing log file; eligible output creates it. Constructor preparation is separate from per-entry severity and label selection.

The fourth parameter, encoder, accepts FileDestination.EncodingOptions.ASCII, BigEndianUnicode, Unicode, UTF8 (the constructor default), or UTF32. default(FileDestination.EncodingOptions) is ASCII, not the optional UTF8 default. Each write appends the selected BCL encoding's bytes for the completed native record followed by exactly one Environment.NewLine. It adds no leading newline, extra blank line or encoding preamble/BOM. Encoding replacement follows the selected BCL encoding; ASCII does not promise arbitrary Unicode round-tripping.

Appending leaves all existing bytes untouched, including any existing BOM. It does not inspect or transcode old content, detect binary or incompatible encoding, or insert a corrective separator after an unterminated prefix. You choose compatible existing content and encoding. See Explicit File Output for path and failure boundaries. The behavior is exercised in FileDestinationTests.cs, which remains deliberately separate from the default local check below.

Receive Messages In A Callback

Subscribe before registering the destination. Callbacks run synchronously on the logging thread; marshal to your UI thread in your own handler when needed. Event arguments expose Message, RawMessage, Exception, LogLevel, Timestamp, and Context.

Illustrative — not currently present in the repo.

using System;
using ProphetsWay.Utilities;
using ProphetsWay.Utilities.LoggerDestinations;

public static class Program
{
    public static void Main()
    {
        var destination = new EventDestination("Critical, InformationOnly");
        destination.LoggingEvent += (sender, entry) =>
            Console.WriteLine($"{entry.LogLevel}: {entry.RawMessage}");
        Logger.AddDestination(destination);
        try
        {
            Logger.Info("Ready.");
            destination.Log(LogLevels.Critical | LogLevels.InformationOnly, "Composite.");
        }
        finally
        {
            Logger.RemoveDestination(destination);
        }
    }
}

The first callback prints InformationOnly: Ready. The direct call also passes: its full mask 9 is present in the destination's mask 9. It would be rejected by InformationOnly = 8. The callback receives that complete composite mask, not a single-bit reduction. The registration/event pattern is also in EventDestinationTests.cs.

Both event argument types expose non-null Context on actual library delivery, even with no scopes or labels. Their existing public constructors leave Context null and perform no ambient capture. Normal LoggingEvent multicast rules remain: a throwing handler stops that invocation and counts as one output failure; other independent destinations are still attempted. This differs from the individually contained subscribers of the safe Logger.DispatchFailed event.

Carry Metadata And Use Extension Calls

Typed logging accepts your application object; it does not require ILoggerMetadata. Implement that empty marker only when you want the convenience extension calls as well. This example replaces a hypothetical database writer with an actual typed event destination.

Illustrative — not currently present in the repo.

using System;
using ProphetsWay.Utilities;
using ProphetsWay.Utilities.Generics;
using ProphetsWay.Utilities.LoggerDestinations;

public sealed class DbMetadata : ILoggerMetadata
{
    public int UserId { get; set; }
    public string EntryPointMethod { get; set; }
    public object Permissions { get; set; }
}

public static class Program
{
    public static void Main()
    {
        var destination = new GenericEventDestination<DbMetadata>(LogLevels.Trace);
        destination.LoggingEvent += (sender, entry) =>
            Console.WriteLine($"{entry.Metadata.UserId}: {entry.RawMessage}");
        Logger.AddDestination(destination);
        var metadata = new DbMetadata
        {
            UserId = 42, EntryPointMethod = nameof(Main), Permissions = "Synthetic example"
        };
        try
        {
            Logger.Trace("Routing detail.", metadata);
            Logger.Debug("Starting.", metadata);
            metadata.Info("Finished.");
            Logger.Error(new InvalidOperationException("Example failure."), metadata, "Stopped.");
            metadata.Critical(new InvalidOperationException("Critical failure."), "Cannot continue.");
        }
        finally
        {
            Logger.RemoveDestination(destination);
        }
    }
}

Expected output is 42: Routing detail., 42: Starting., 42: Finished., 42: Stopped., then 42: Cannot continue. Metadata remains available as an object; this callback chooses what to print. See the real call patterns in GenericLoggerTests.cs and MetadataLoggerTests.cs.

Ordinary explicit registrations and every exact declared-T route are independent, including interface types such as T = ILoggingDestination. Typed routing does not search base types, implemented interfaces, or the metadata object's runtime subtype. If that exact type has no enabled registered destination, its automatic recipient uses the native typed renderer and the same session file as ordinary automatic output. It retains metadata, including null/default values, with the original annotation, native scopes and UTC event time. Rendering still follows the closed scalar rules, not arbitrary object serialization. Typed calls never forward to ordinary registrations. Any enabled compatible explicit recipient suppresses only its own route's automatic output, even when it rejects or fails; another route can still use the shared file.

Implement A Guarded Custom Destination

Move an old public Log override into protected LogCore. Keep formatting/output inside that hook so the supplied guards run first, and use its context instead of recapturing ambient state. This callback sink needs no files or external service; its added constructor belongs to the example, not the library. The base requires a reporting level and has no parameterless constructor.

Illustrative — not currently present in the repo.

using System;
using ProphetsWay.Utilities;

public sealed class CallbackDestination : BaseLoggingDestination
{
    private readonly Action<LogContext, LogLevels, string, Exception> _write;

    public CallbackDestination(LogLevels reportingLevel,
        Action<LogContext, LogLevels, string, Exception> write)
        : base(reportingLevel)
    {
        if (write == null)
            throw new ArgumentNullException(nameof(write));
        _write = write;
    }

    protected override void LogCore(LogContext context, LogLevels level,
        string message, Exception ex)
    {
        _write(context, level, message, ex);
    }
}

public static class CustomDestinationExample
{
    public static void Run()
    {
        var personal = new SensitivityLabel("PersonalData");
        var destination = new CallbackDestination(LogLevels.Trace,
            (context, level, message, exception) =>
                Console.WriteLine("{0}: {1} ({2} labels)",
                    level, message, context.Labels.EffectiveLabels.Count));
        destination.LabelPolicy = new DestinationLabelPolicy(
            LabelFilterMode.Exclude, new[] { personal });
        Logger.AddDestination(destination);
        try
        {
            using (Logger.BeginScope(new LogAnnotations(new[] { personal })))
            {
                Logger.Info("Withheld before the callback.");
                destination.Log(LogLevels.InformationOnly, "Direct call also withheld.");
            }
            Logger.Info("Synthetic public message.");
        }
        finally
        {
            Logger.RemoveDestination(destination);
        }
    }
}

The generic base uses the same pattern, adding T metadata between level and message in LogCore. Neither hook has optional parameters; the inherited public Log methods still default message and ex to null. MassageLogStatement and PrintLogEntry overrides retain their existing signatures. Hook or callback exceptions are output failures handled by the invoking guarded boundary, not a request to retry or activate another output.

Capture A Text Record In Memory

Override PrintLogEntry to receive a fully rendered ordinary record without a terminator. This sink stores one string; it neither opens a file nor writes to the console. Explicit registration avoids fallback, but any other registered recipients can still receive the call. Use these in-memory examples with one synchronous producer and no unrelated recipients; they are not concurrent storage implementations.

Illustrative — not currently present in the repo.

using System.Collections.Generic;
using ProphetsWay.Utilities;
using ProphetsWay.Utilities.LoggerDestinations;

public sealed class RecordingTextDestination : TextBasedDestination
{
    public RecordingTextDestination() : base(LogLevels.Trace)
    {
    }

    public string Record { get; private set; }

    protected override void PrintLogEntry(string message)
    {
        Record = message;
    }
}

public static class TextRecordExample
{
    public static string Run()
    {
        var destination = new RecordingTextDestination();
        Logger.AddDestination(destination);
        try
        {
            var label = new SensitivityLabel("Internal");
            var properties = new[]
            {
                new KeyValuePair<string, object>("Step", "Receive"),
                new KeyValuePair<string, object>("Step", "Validate"),
                new KeyValuePair<string, object>(null, null)
            };
            using (Logger.BeginScope(new LogAnnotations(new[] { label, label }), properties))
            {
                Logger.LogAnnotated(new LogAnnotations(new SensitivityLabel[0]),
                    LogLevels.InformationOnly, message: "First line.\nSecond line.");
            }
            return destination.Record;
        }
        finally
        {
            Logger.RemoveDestination(destination);
        }
    }
}

On delivery, the returned string has one escaped message token, entryLabels=[], and one scope with labels=["Internal","Internal"] and properties=[("Step","Receive"),("Step","Validate"),(null,null)]. No duplicate is flattened. A null returned record means no print occurred; normal return alone is not proof of delivery. The public example types above are application code, not additional library APIs.

Extend Typed Value Formatting

Derive from GenericTextBasedDestination<T> to retain exact-T routing and render metadata. This example explicitly reads two known application properties and delegates other values to the default formatter. Return ordinary text: the base quotes and escapes it afterward, including the newline and quotes in Stage. The same hook formats scope values.

Illustrative — not currently present in the repo.

using System.Collections.Generic;
using System.Globalization;
using ProphetsWay.Utilities;
using ProphetsWay.Utilities.LoggerDestinations;

public sealed class OrderMetadata
{
    public int OrderId { get; set; }
    public string Stage { get; set; }
}

public sealed class OrderTextDestination : GenericTextBasedDestination<OrderMetadata>
{
    public OrderTextDestination() : base(LogLevels.Trace)
    {
    }

    public string Record { get; private set; }

    protected override string FormatValue(object value)
    {
        var order = value as OrderMetadata;
        if (order != null)
            return string.Format(CultureInfo.InvariantCulture,
                "Order {0}: {1}", order.OrderId, order.Stage);

        return base.FormatValue(value);
    }

    protected override void PrintLogEntry(string message)
    {
        Record = message;
    }
}

public static class FormatterExample
{
    public static string Run()
    {
        var destination = new OrderTextDestination();
        Logger.AddDestination<OrderMetadata>(destination);
        try
        {
            var metadata = new OrderMetadata { OrderId = 42, Stage = "Queued\n\"Review\"" };
            var properties = new[]
            {
                new KeyValuePair<string, object>("Attempt", 2),
                new KeyValuePair<string, object>("Unformatted", new object())
            };
            using (Logger.BeginScope(null, properties))
            {
                Logger.LogAnnotated<OrderMetadata>(null, LogLevels.InformationOnly,
                    metadata, message: "Synthetic order.");
            }
            return destination.Record;
        }
        finally
        {
            Logger.RemoveDestination<OrderMetadata>(destination);
        }
    }
}

The metadata token is "Order 42: Queued\n\"Review\""; the scope values are "2" and "[no formatter: Object]". Without the override, this metadata would be "[no formatter: OrderMetadata]", not an automatic property dump. These are expected tokens, not captured program output. The sink has the same single-producer/registration assumptions as the previous example. No ILoggerMetadata marker or formatter registration is needed. See TextRenderingTests.cs for the real in-memory text, explicit formatter, rejection and escaping specifications.

Behavior And Limitations

Native Argument Errors

These errors apply to the core and its forwarding constructors, helpers, registrations, and supplied direct Log implementations, as indicated. Valid rejection is not an error.

Invalid input Exception ParamName
Enum destination mask outside 0-63 ArgumentOutOfRangeException reportingLevel
Integer destination mask outside 0-63 ArgumentOutOfRangeException intReportingLevel
Null string destination mask ArgumentNullException strReportingLevel
Any other invalid string mask, including parsed negative/unknown bits or overflow ArgumentException strReportingLevel
Raw mask outside 1-63 passed to ValidateMessageLevel ArgumentOutOfRangeException messageLevel
Raw mask outside 1-63 passed to a supplied destination's Log ArgumentOutOfRangeException level
Null required helper message or exception ArgumentNullException message or ex
Null ordinary or typed AddDestination argument ArgumentNullException newDest
Same object reference added again on the same ordinary or exact-T route ArgumentException newDest
Null registration settings on add or replacement ArgumentNullException settings
Null/absent destination on settings replacement ArgumentNullException / ArgumentException respectively destination
Null policy in settings construction / supplied policy assignment ArgumentNullException labelPolicy / value respectively
Null property sequence for BeginScope ArgumentNullException properties
Invalid raw mask for LogAnnotated ArgumentOutOfRangeException level
Null/noncurrent context on a supplied LogWithContext call ArgumentNullException / ArgumentException respectively context

No competing-error priority is promised when both Critical arguments are null. Exception message text is not a configuration contract. Equivalent valid mask representations have the same eligibility, but invalid strings deliberately use different errors from invalid enums/integers.

Dispatch And Direct Calls

For enabled ordinary and exact-T registrations, every registration and supplied-destination restriction must permit the full captured entry before handoff. Logger invokes a custom ValidateMessageLevel callback at most once per attempted recipient and requires true; an earlier rejection may skip it. No ordering among rejecting checks is promised. Label denial withholds message, exception, metadata and the complete context, including scope properties, before recipient-owned formatting, hooks, callbacks or export. Permitted recipients continue.

A recipient implementing the optional IContextLoggingDestination or exact-T counterpart receives one LogWithContext handoff instead of the legacy Log, never both. Independent implementations of the old interfaces remain valid and receive no new context parameter. Supplied bases deliver once through Logger's internal captured path to LogCore, without recapturing callback-mutated scopes or repeating policy checks/reporting. That path is internal, not a consumer API or reusable permission token; public reentry always starts a new guarded attempt.

The supplied bases' public Log and LogWithContext are nonvirtual guards, inherited by event/text/console/file destinations. Direct Log captures active frames with no entry annotation and checks the destination's own mask and LabelPolicy, not registration settings. A valid mismatch returns without massage, hook, event construction, text composition, output or fallback. Invalid masks throw before recipient work, even without event subscribers.

Direct LogWithContext requires the same ordered scope openings currently active, including empty and unlabeled frames. Equal labels/properties from a different opening are insufficient. Both empty frame lists match; the supplied entry annotation may be non-null. Reuse while those openings remain current still rechecks current destination configuration. Added, ended or replaced frames make the context noncurrent and cause a local argument error before output. Possession or earlier successful delivery is not authorization. Arbitrary independent direct implementations, hidden or reimplemented members, and consumer methods calling their own hooks are not sandboxed.

An accepted supplied-base LogWithContext invocation delivers a newly stamped context with that direct call's UTC time and the supplied immutable scope/label facts, including entry annotations. It does not mutate the retained context or replace its facts with current labels. Timestamp equality is not part of the current-opening check and grants no delivery permission.

Direct/raw content is distinct from helper preconditions: message and exception may each be absent, even at Critical or ErrorOnly. Typed metadata may still be null/default. For accepted callbacks, RawMessage, Exception, the complete LogLevel mask, and typed Metadata retain their supplied values/references. Message contains the massaged text, not a replacement raw payload; Error's omitted context remains null in RawMessage.

Without an exception, the base MassageLogStatement returns the original message, including null, empty or whitespace. With an exception, it preserves context and includes exception and nested-exception messages and available stack traces at every valid mask, including warnings and composites. It does not serialize exception Data, redact content, or clone raw objects. Timestamp remains each event carrier's construction-time local DateTime.Now, not a shared UTC timestamp. Use the delivered Context.EventTimestampUtc for shared call time instead. Event Message and RawMessage are not text-record tokens: message/exception text stays unescaped, and metadata and scope values retain original references. Accepted raw objects are not sanitized reporting objects; framing a neighboring text destination does not make a callback safe to export.

Label And Policy Arguments

Invalid input Exception ParamName
Null identifier ArgumentNullException identifier
Empty, overlong, whitespace-containing or control-containing identifier ArgumentException identifier
Mode other than 0, 1, or 2, including combined value 3 ArgumentOutOfRangeException mode
Null configured/effective sequence ArgumentNullException labels / effectiveLabels respectively
Null element anywhere in a finite sequence ArgumentException labels / effectiveLabels respectively

NoFilter and a decisive match do not bypass finite-input validation. Sequence-access failure completes exceptionally, without a usable partial policy or Boolean result. Exact foreign exception details and competing-error precedence are unspecified. Supplied sequence code can have side effects; the policy does not sandbox it, undo those effects, or bound nonterminating inputs.

Keep inputs stable during capture. Repeated/concurrent evaluation of unchanged valid membership preserves policy state and results, but concurrent producer mutation is unsupported. Readback order, collection-reference identity, and representative label-reference identity are unspecified. Mutation through readback collection interfaces throws NotSupportedException.

Annotation Capture And Readback

Supply a finite, stable, non-null sequence of non-null labels to LogAnnotations. Null labels throws ArgumentNullException; a null element anywhere throws ArgumentException. Both name labels in ParamName; exception wording is not promised.

Sequence access includes enumerator acquisition, iteration, element access and disposal. If any fails, construction produces no usable partial value. Foreign sequence errors are local construction errors, not sanitized dispatch reports; their details, competing-error precedence and access counts are unspecified. Caller code may have side effects: capture does not sandbox or roll them back, support mutation during capture, or guarantee termination for unbounded input.

After successful construction, LabelOccurrences is non-null and supports concurrent reads. Writes through its collection interfaces throw NotSupportedException; its ICollection.SyncRoot does not expose occurrence storage. View and representative label-reference identity are unspecified. These readback guarantees describe LogAnnotations specifically.

Scope-property capture follows the same complete-before-publication discipline, including enumerator disposal. A null sequence or failed acquisition/iteration/current/disposal publishes no scope or usable handle and emits no dispatch report. Opening cannot undo side effects in caller sequence code, bound an infinite input or support concurrent producer mutation. Scope cleanup errors are local errors too, not LogDispatchException or DispatchFailed notifications.

Failure Reports And Return Policy

On explicit or automatic routes and supplied guarded direct calls, failure handling depends on the observed boundary, not foreign exception text or type. Valid severity/label rejection is not a failure and does not activate fallback. Independent recipients are attempted once in captured order, without rollback or retries; another recipient succeeding does not cancel a mandatory failure.

Original failure Safe fact Result after independent attempts and reporting
Logger-invoked severity callback throws LogFailureStage.Eligibility = 1 Throw LogDispatchException.
Selected legacy/contextual invocation, delivery hook, rendering or callback throws LogFailureStage.Output = 2 Throw LogDispatchException.
Automatic initial establishment fails at both locations, remembered initial failure, or automatic output fails One LogFailureStage.Output descriptor at the implicit slot after all captured explicit slots; no core-capture failure Throw LogDispatchException; qualifying initial secondary success is normal success.
Opted-in label-policy evaluation unexpectedly fails LogFailureStage.LabelCheck = 3 Withhold that recipient, report and return unless a mandatory failure also occurred.
Shared entry/context capture unexpectedly fails CoreCaptureFailureCount = 1, no recipient descriptor Withhold the incomplete entry from all affected recipients, report and return.

No strict-mode selector is supplied by these APIs. A normal return proves neither delivery nor successful capture/checks. Value/scope construction and argument errors remain local exceptions, not fabricated dispatch failures. A mandatory failure still throws if its descriptor falls beyond the retained limit; result selection is not inferred from the truncated descriptor list.

If neither initial automatic location is usable, Logger remembers a safe failure marker, not the raw causes. Later default-dependent calls get fresh reports/correlations and exceptions without new path or permission probes. LogDispatchException.Message, ToString() and best-effort stderr give fixed guidance to make an appropriate default location writable or configure a compatible destination, never the resolved path or payload. Fixing permissions alone does not retry this session: use a compatible enabled explicit recipient to bypass failure only on its route, or start a fresh loaded Logger session. Removing/disabling/clearing that recipient exposes the same remembered failure.

LogFailureReport contains a generated CorrelationId, at most eight immutable Failures in encounter order, OverflowCount for further failed recipients, and CoreCaptureFailureCount (zero or one). A core-only report has an empty recipient list and zero overflow. Total failures are (long)report.CoreCaptureFailureCount + report.Failures.Count + report.OverflowCount. Each descriptor's RegistrationId is a one-based position in this call's full capture, including preceding disabled, rejected and successful slots. A supplied direct attempt uses 1; zero is never a fabricated core recipient. These are not durable registration IDs.

Reports retain no entry, labels, origins, properties, destinations, delegates, raw causes or control backlinks. Their owned membership remains unchanged across observers and later calls. LogDispatchException.Report carries the same safe facts, with no raw inner cause. Its initial diagnostic view uses fixed prose, allowed IDs/codes/counts, null InnerException/HelpLink, empty Data, fixed Source, and null StackTrace. This does not erase CLR diagnostic state or sanitize reflection, debugger access, serialization, inherited post-catch mutation or a whole object graph.

Logger.DispatchFailed captures subscribers after attempts, invokes each synchronously outside registry locks, then attempts a safe stderr summary bounded to 512 UTF-16 units including its terminator. Subscriber/writer failures are contained and add no original failures or escalation. On the same managed-thread reporting stack, nested logging still runs with its own result policy but emits no nested event/stderr report; other threads are independent. No timeout, cross-thread cycle prevention, guaranteed observation or process-fatal containment is promised.

Native capture and policy checks use library-owned membership and sealed label/policy values, with no ordinary deterministic consumer fault path for the unexpected capture/LabelCheck branches. Those branches require code review, not a fabricated report presented as execution coverage. Allocation/runtime faults may prevent reporting itself: out-of-memory survival is not guaranteed. Consumer callbacks and raw payloads are not made safe by these bounded reporting facts.

Text rendering follows the same boundary: a throwing massage, FormatValue override or composition step causes no PrintLogEntry call for that recipient. Independent recipients continue, then an Output failure requires safe reporting and LogDispatchException. A print failure may already have effects; there is no rollback or retry. Valid rejection reaches neither formatter nor print, and a null formatter result is valid text absence, not a failure. Neither rendered content, event time, original values nor the formatter's raw exception is added to LogFailureReport. Intended log records are unbounded, potentially sensitive content; they are not the bounded diagnostic channel. Custom inspection and retention remain your responsibility.

Current Logging And Text Output

  • With no enabled compatible explicit recipient on the captured ordinary or exact-T route, Logger selects one implicit automatic recipient without registering it or consulting another route. It uses Trace and no label filter, covering all six bits and valid composite levels. Ordinary and typed automatic records share one UTF-8 session file; typed metadata is retained. See Automatic File Output for location, configuration and failure rules.
  • Explicit registration uses reference identity, never recipient equality or hashing. Distinct equal objects remain distinct; the same instance may register on different compatible routes. Duplicate same-route adds leave membership unchanged. Removal targets only the exact reference; null/absent removal is a no-op, and clear affects only the selected route. After removal/clear, a successful re-add goes last.
  • For a route with explicit recipients, mutations and captures are atomic: each call captures one complete insertion-ordered membership and its registration settings before callbacks. Native context and supplied policies are also captured before recipient callbacks, without promising a global transaction across registry and flow state. Registry locks span no consumer code. Callback add/remove/clear/settings changes, including self-removal, affect later captures only; an older capture can still call a removed recipient after mutation returns. Recursive logging is a new call with a fresh capture.
  • Explicit destinations are borrowed: removal/clear never dispose them and do not drain calls. Stop producers and await synchronous calls before disposing your recipients. Membership capture does not serialize callers or shared recipients, impose cross-thread delivery order, or freeze custom recipient state, eligibility results, metadata or exception graphs.
  • The failure rules above cover explicit and automatic dispatch and supplied guarded direct attempts, not arbitrary independent direct code or a guarantee that all I/O completes. Borrowed lifetime and retained-object responsibilities remain.
Automatic File Output

Ordinary and every exact-T automatic route share one session in the loaded static Logger state. Separate processes, AppDomains or independently loaded assembly copies do not share that state. An enabled compatible explicit recipient suppresses only its own route, including rejection or failure. Removing or disabling the last one resumes the same automatic session, not a new file.

The normal primary directory is the host's AppContext.BaseDirectory, not the current working directory, Logger's assembly location or the dotnet installation. To choose a different primary, configure it during startup before any automatic establishment begins:

Illustrative — not currently present in the repo.

ProphetsWay.Utilities.Logger.ConfigureAutomaticFileHostDirectory("logs");

Then, with no enabled ordinary recipient, ProphetsWay.Utilities.Logger.Trace("Startup"); uses automatic output. The relative logs directory is resolved once against the current directory at configuration time using DirectoryInfo.FullName. Configuration creates no directory/file, checks no permissions and registers no recipient. Later successful configuration calls replace the override only before initialization; once establishment starts, even the same path is rejected with InvalidOperationException. Null throws ArgumentNullException; empty or framework-rejected path syntax throws ArgumentException. Other path-normalization errors remain ordinary local errors, not sanitized dispatch diagnostics. Failed calls change nothing; invalid-input/state precedence is unspecified. Null/empty are not reset requests.

Only initial primary establishment failure permits a secondary attempt: one app- directory component followed by the full 64 lowercase SHA-256 hex digits of the normalized host-base key, directly under Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData). The key comes from the captured host base, not the primary override. Unavailable naming/root inputs fail that location; Logger does not substitute CWD or another profile. This is host-base association, not logical-application identity: equal keys share the directory, and physical aliases need not share a key. It supplies no tenant isolation, ACL protection or confidentiality.

Filesystem establishment waits for a selected, fully rendered record. Initial allocation uses Default Log <UTC>-<Guid token>.log, invariant UTC and exclusive CreateNew, leaving occupied candidates untouched. Once selected, every later call appends or creates a missing file at that same pathname, regardless of later CWD changes or route suppression/reactivation. Each record is UTF-8 with one Environment.NewLine suffix, no added BOM and no leading blank line. Existing content is neither inspected nor repaired. See the exact path rules in AutomaticFilePaths.cs and session behavior in AutomaticFileSession.cs.

File effects are serialized across automatic routes and handles close after each attempt; rendering, callbacks, registration changes and reporting remain outside that coordination. Once a path is selected, write/flush/close failures or later open failures cannot select the secondary, replay the entry or allocate another session filename. A later call is a new attempt at the selected path. There is no crash-durability or cross-process ordering guarantee, public session reset, disposal, strict-mode selector or selected-path inspection API. Intended records are not redacted; choose explicit destinations and filesystem access/retention controls for your deployment.

Explicit File Output

FileDestination.cs selects its full pathname once at construction using the framework's FileInfo semantics. Relative paths use that moment's Environment.CurrentDirectory; later directory changes do not redirect the instance. If the file is deleted, a later permitted call can recreate it at that same path. Missing parent directories are prepared at construction, not repaired on every output attempt. This fixes a pathname, not a persistent physical-file identity or filesystem sandbox.

Required arguments are validated before deletion or directory creation. An undefined encoder throws ArgumentOutOfRangeException naming encoder before those effects. Ordinary construction, preparation and reset failures outside the documented argument mappings propagate as their original framework exceptions. Their diagnostic contents are not promised sanitized or path-free; construction produces neither a console echo nor a Logger.DispatchFailed notification.

After construction, encoding/open/write/flush/close failures through supplied public direct entrypoints or Logger delivery are LogFailureStage.Output failures. A direct call safely reports its one-recipient failure and throws LogDispatchException. Logger attempts independent eligible recipients before safe reporting and the mandatory throw; reporter failures cannot suppress or replace that result. The sink emits no second report. Validly rejected entries never reach rendering or file output, but rejection does not undo earlier constructor preparation or explicit reset.

Physical writes are synchronous and serialized within one destination instance; each attempt releases its acquired file handle before completion. Rendering can still run concurrently. There is no cross-instance/process coordination, promised concurrent-call order, retry, replay, relocation, global flush or crash-safe/exactly-once/durability guarantee. A failure may follow partial effects; a later logging call is a new attempt at the same path, not a replay of the failed entry.

Record Layout

The supplied text bases render the captured UTC event time in invariant round-trip O format (including +00:00), followed by the full severity's general spelling padded left to 12 characters. The message is massaged once, then quoted and escaped. For Logger.Debug("Hello World!") without scopes or entry annotations, the shape is below. The timestamp placeholder is not literal output or a recorded execution:

<UTC event time> ::    DebugOnly:  "Hello World!" | entryLabels=null | scopes=[]

GenericTextBasedDestination<T> adds the literal prefix " | metadata=" (excluding the quotes) immediately after the message token, before entryLabels, even for null/default metadata. Ordinary text has no metadata field. There is no configurable grammar or automatic discovery of arbitrary structured objects.

Component Representation
Absent text / empty text / literal null text null / "" / "null"; non-null values are always quoted.
Entry or scope annotation null when absent; [] when present but empty; otherwise ordered quoted label identifiers, including duplicates.
Scopes [{labels=attachment,properties=[(key,value),...]},...], outermost first, including empty/unlabeled frames.
Properties Ordered pairs, not a dictionary: duplicate keys, null/empty/whitespace keys and original value slots remain separate. Keys are string tokens; values use FormatValue.

Arrays and pairs use commas without added spaces or trailing commas. Entry labels are separate from scope labels. Text preserves label occurrences rather than exporting the deduplicated EffectiveLabels set; frame positions in scopes are not the label-only ScopeIndex values.

Every content token is escaped once after formatting, including message and exception detail, metadata, scope keys/values, label identifiers, unsupported markers and explicit formatter output:

Input Emitted text
Backslash / double quote \\ / \"
CR / LF / TAB \r / \n / \t
Other Char.IsControl units and U+2028/U+2029 \uXXXX, with four uppercase hexadecimal digits.
Other UTF-16 units Preserved without normalization or truncation.

An actual newline becomes \n; an existing backslash followed by n becomes \\n. Delimiter-looking text stays inside its quoted token. This is reversible text escaping, not redaction, confidentiality, lossless object serialization or proof of downstream encoding fidelity.

Each text base builds the whole record before one PrintLogEntry call. That string is non-null, single-line and has no terminator; the sink owns termination. Console retains its WriteLine handoff. FileDestination appends one Environment.NewLine suffix using the selected encoding, as described above. Automatic output uses the same suffix with UTF-8; its separate lifecycle and initial-only recovery rules are described under Automatic File Output.

Scalars And Explicit Formatting

The default LoggingDestinationCore.FormatValue(object value) supports only these values:

Value Unescaped scalar text
Null, string, char, Boolean Null result, original string/character, or True/False.
SByte/Byte, Int16/UInt16, Int32/UInt32, Int64/UInt64, IntPtr/UIntPtr Invariant D; pointer-sized integers render their numeric value, without dereferencing.
Single/Double; Decimal Invariant R; invariant G, respectively. Floating special values remain supported.
Guid; DateTime/DateTimeOffset; TimeSpan Invariant D; O; c, respectively. Payload times retain their kind/offset; only the event time is forced to UTC.
Enum General G names/representable flag names, otherwise invariant underlying decimal; alias choice follows the BCL.
Anything else [no formatter: TypeName], using runtime Type.Name, not a full name or object string.

Nullable boxing follows the underlying value, or null when empty. Runtime-specific BCL floating spellings are not promised byte-identical across target frameworks. Dictionaries, enumerables and annotation-shaped metadata remain values, not automatically traversed structures or label sources. Default rendering calls no arbitrary getters, object ToString, IFormattable, equality, hashing or nested enumeration. It does not deep-clone values.

Override FormatValue on your text destination to opt into application-owned inspection. Return unescaped text, delegate unhandled values to base.FormatValue(value), or return null for a null text token. The renderer escapes every result as data; returning null is not a failure. Successful text rendering calls the hook once per metadata/property-value occurrence after eligibility. Duplicate slots are separate calls; call order across values is unspecified, and results are not cached across recipients. Keys, labels and message/exception text bypass this hook. Overrides may run concurrently and own their inspection, effects and retained objects.

The rules are implemented by the ordinary text base, typed text base and formatting hook, and specified in TextRenderingTests.cs.

Earlier Text Layout

The old local-time, unquoted output looked like this; it is retained only as a migration reference, not current output:

3/15/2019 11:09:33 PM ::    DebugOnly:  Hello World!

The existing example program constructs nested exceptions. This historical illustrative error excerpt shows their messages in the earlier multiline layout. Current text keeps the exception detail inside one escaped message token at every valid mask; events retain unescaped massaged text. A constructed-but-unthrown exception does not acquire a stack trace merely because its message mentions one:

3/15/2019 11:25:41 PM ::    ErrorOnly:  Another generic message about an error occuring. (friendly message to show a UI maybe?)
This exception has an inner exception. (likely details to hide from a UI)

Inner Exception Message:
This is a specific Exception Message and will contain a stack trace.

Implemented M3/M4-A And Remaining Boundaries

Native scopes, ordered origins/full properties, effective-label filtering, atomic registration settings replacement, optional contextual receivers and guarded supplied destinations are implemented. M4-A adds call-shared UTC time, invariant scalar/explicit value formatting, ordinary and exact-T text bases, and quoted single-line rendering of the message and captured native context. They extend the existing severity validation, explicit-route isolation, borrowed-recipient lifetime and independent-attempt reporting rules. This source status is not full-v4 or release certification; the permanent regression, compiled-example and parent final acceptance gates remain separate.

M4-B1 now implements append-by-default explicit files, construction-only reset, fixed selected paths and physical record encoding/termination. M4-B2 now integrates the shared automatic session, primary configuration, typed metadata retention, initial-only recovery, fixed-path reuse and remembered initialization failure. Its final documentation-compilation and independent code/security gates remain separate; this is not a claim that the whole B2 acceptance target is complete. The inbound and outbound Microsoft bridge directions are implemented in current source and documented above; neither is part of this native M3/M4 slice. Explicit membership safety is not a guarantee of all concurrency safety. The native enum itself does not define Microsoft severity or None conversion; that mapping belongs to the bridge. The implemented failure behavior above is not delivery of every policy in docs/requirements.md. Requirements readiness is not delivery.

A false policy result is an ordinary mismatch, not an output failure or instruction to activate fallback. True means only membership permission, not successful delivery, correct classification, or authorization of a recipient. The library does not automatically classify or redact payloads. You own label mapping, sanitization, recipient access/authentication, storage, retention, and audit obligations. Readable identifiers/configuration and consumer sequence exceptions can contain sensitive information; do not treat them as safe to expose just because the predicate returned.

See the scoped security review, threat model, and data classification. Their scope is not a confidentiality, compliance, sandboxing, whole-library security, or publication guarantee. Any advisory-scan results in that review are dated evidence, not license, bundled-component, SDK/runtime, or release clearance.

Breaking Migration From Earlier Logger APIs

Recompile consumers, custom destinations, and code that compares or persists enum values. Enum constants can be embedded in compiled callers; replacing a library binary does not translate their old numeric meanings. This is unreleased major-version work, not a patch-safe drop-in update.

  • Remove calls to ordinary, typed, and metadata-extension Security, plus Security/SecurityOnly configuration names. Choose the appropriate remaining severity for each call. There is no automatic security-event/concern replacement. Explicit application labels and policies are independent of severity, not an automatic translation of the removed Security level.
  • Recalculate saved integer/numeric-string masks from the intended new bits: 1 is Critical, 2 is ErrorOnly, 4 is WarningOnly, 8 is InformationOnly, 16 is DebugOnly, and 32 is TraceOnly. Do not reuse old numeric configuration without reviewing its meaning. Recheck enum-name configuration too: inclusive Error accepts Error/Critical; Debug no longer means all severities. Select Trace for all six.
  • Compare emitted Error entries to ErrorOnly, not the inclusive Error mask. For selection, require all requested bits; preserve composite masks rather than reducing them to one severity.
  • Supply the formerly optional required extension arguments: messages for Debug/Info/Warn and an exception for Error. All three helper families now reject required nulls before dispatch, even if the route rejects everything. Critical requires exception and context; Error's context and Warn's exception remain optional. Empty/whitespace messages and null/default metadata remain valid.
  • Correct malformed mask strings instead of relying on the former Information fallback. Zero is valid only as a destination mask; direct/raw zero is an error. Supplied direct destinations now reject ineligible messages before formatting/callback/output, so a direct call no longer bypasses selection.
  • Deduplicate setup by object reference per route: a repeated add now throws ArgumentException with ParamName newDest, rather than adding another delivery. Retain the exact reference for removal; an equal but distinct object no longer removes it. Do not treat removal/clear as a drain or immediate revocation: already captured calls may still use that borrowed recipient.
  • Rebuild subclasses and move public Log overrides to the matching protected LogCore signature shown above. The old virtual/abstract slot is gone: this is a binary as well as source break. Do not hide Log to bypass guards. Existing callers keep the public method defaults, and independent old-interface implementations need not adopt the optional context interface.
  • Update report readers for LabelCheck, empty recipient lists on core-only failure, and core-inclusive totals. Notifications do not all imply an exception; severity/output failures do. Event consumers may read Context on delivery but must allow null on manually constructed args.
  • Migrate text parsers from local culture-dependent, unquoted multiline output to the fixed UTC O prefix and quoted token grammar above. Parse boundaries before decoding escapes once; do not split blindly on delimiters that can occur inside quoted content. Preserve null versus empty/literal-null tokens, repeated labels/keys and full scope frames. Exception stacks now appear escaped within the message token, not as additional physical lines.
  • Keep MassageLogStatement unframed and unescaped if you need the supplied text contract: text bases frame its result, while events retain it unescaped. Use FormatValue for explicit metadata/property rendering and PrintLogEntry for the completed unterminated record. Review existing subclasses for a coincidentally named FormatValue member; replacing LogCore can replace the supplied rendering behavior. These hooks do not certify custom output code.
  • Do not reinterpret event Timestamp as UTC. Read Context.EventTimestampUtc on delivery; a public direct reuse samples anew without altering the retained context. Update text readers independently from raw/event consumers, whose original fields and local timestamp remain.
  • Recompile callers to obtain FileDestination's new omitted resetFile: false default on all three existing overloads. Previously compiled callers may still pass embedded true until rebuilt; replacing the library alone does not change those arguments. Explicit true still deletes the selected existing file during construction. No new reset method or factory is added.
  • Update file readers for one suffix terminator per appended record and no newly added BOM; existing bytes and unterminated prefixes are not repaired. Reject undefined encodings during setup, and handle ordinary constructor errors locally without expecting console echo or safe dispatch diagnostics. Guarded output failures still report safely and must throw. These are unreleased v4 behavioral changes, not a patch-safe update.
  • Review no-setup file assumptions: automatic output now uses the host base or a pre-initialization override, initial-only secondary recovery and one shared UTF-8 file with Trace coverage and typed metadata. It no longer forwards typed fallback to ordinary recipients. Clearing registrations cannot reset the selected path or remembered initial failure.

Architecture And Design Decisions

Choice Trade-off
Static entry point with configurable destinations Central setup and short calls, but process-wide state and current registration limitations.
Typed metadata separate from message text Your destination can inspect application data; Logger does not supply a database schema or automatically persist that object.
Sealed, application-defined label instead of a closed taxonomy No registry dependency and no invalid default value-type instance; consumers must agree on exact identities.
Immutable copied policy membership Later caller edits cannot change configuration; changing policy means constructing another policy.
Standalone predicate plus native enforcement Membership remains independently usable; Logger and supplied guards enforce whole-entry selection using the captured union.
Immutable membership, original nested objects Stable scope/settings structure without arbitrary deep cloning, classification or sanitization; consumers own nested-object safety and retention.
Conventional non-transferable scope handles Normal await/child inheritance and local cleanup without a creator-ID/fork protocol or universal misuse detector.
Nonvirtual entrypoints and protected output hooks Selection precedes supplied output even on direct calls, at the cost of a major subclass override migration.
Closed scalar formatting plus explicit overrides Predictable invariant text without arbitrary object inspection; your formatter owns any additional reads and effects.
Shared UTC and quoted native records One call-time fact and preserved content boundaries, at the cost of a breaking text-parser migration; physical storage remains a separate responsibility.

The accepted direction is recorded in docs/decision-log.md. M4-A implements native rendering/framing and M4-B1 implements the explicit-file sink behavior above; M4-B2 integrates the automatic session. Both M5 Microsoft bridge directions are present in current source. This does not claim the published package, M6, or remaining package/release qualification.

Building And Testing Locally

Use Windows with a .NET 10 SDK and .NET Framework 4.8 available for the Framework test leg. Run from the repository root. Build Logger.sln first; it includes the library, tests, and example. The build restores dependencies if needed. Stop if it fails before testing.

dotnet build .\Logger.sln -c Debug

The test project uses xunit.v3.mtp-off 4.0.1 through VSTest (xunit.runner.visualstudio 4.0.0 and Microsoft.NET.Test.Sdk 18.10.1); both Microsoft Testing Platform runner switches are disabled. Tests use Shouldly 4.3.0. The three remaining legacy boolean assertions in DestinationManagementTests now use Shouldly, and the unused FluentAssertions 5.10.3 reference has been removed. Assertion expressions, expected values, all four test identities and product operations are unchanged. Moq 4.20.72 supports destination mocks, and coverlet.collector 6.0.4 supplies coverage.

Use this focused selection, sequentially on both targets, with coverage:

$filter = @(
    'FullyQualifiedName~ProphetsWay.Logger.Tests.SensitivityLabelTests.'
    'FullyQualifiedName~ProphetsWay.Logger.Tests.DestinationLabelPolicyTests.'
    'FullyQualifiedName~ProphetsWay.Logger.Tests.BasicTests.'
    'FullyQualifiedName~ProphetsWay.Logger.Tests.GenericBasicTests.'
    'FullyQualifiedName~ProphetsWay.Logger.Tests.AdvancedTests.'
    'FullyQualifiedName~ProphetsWay.Logger.Tests.GenericAdvancedTests.'
    'FullyQualifiedName~ProphetsWay.Logger.Tests.LoggerTests.'
    'FullyQualifiedName~ProphetsWay.Logger.Tests.GenericLoggerTests.'
    'FullyQualifiedName~ProphetsWay.Logger.Tests.MetadataLoggerTests.'
    'FullyQualifiedName~ProphetsWay.Logger.Tests.ILoggingDestinationTests.'
    'FullyQualifiedName~ProphetsWay.Logger.Tests.LogAnnotationsTests.'
    'FullyQualifiedName~ProphetsWay.Logger.Tests.EventDestinationTests.'
    'FullyQualifiedName~ProphetsWay.Logger.Tests.DestinationRegistrationSettingsTests.'
    'FullyQualifiedName~ProphetsWay.Logger.Tests.TextRenderingTests.'
) -join '|'

dotnet test .\ProphetsWay.Logger.Tests\ProphetsWay.Logger.Tests.csproj -c Debug -f net48 --no-build --no-restore --filter $filter --collect "XPlat Code Coverage"
dotnet test .\ProphetsWay.Logger.Tests\ProphetsWay.Logger.Tests.csproj -c Debug -f net10.0 --no-build --no-restore --filter $filter --collect "XPlat Code Coverage"

This selection includes native scope/context/settings, guarded-destination and text-rendering specifications, not just the earlier severity and standalone-policy tests. Its discovered count may change as regressions are added. Every C# example above requires independent compile-only checking against both library assets; do not execute the programs as part of that check. This README update does not claim that check, the parent final gate, or release approval passed.

Historical VS Code validation tasks are archived unchanged in historical-tasks.pre-test-rename.json, not loaded as active tasks. The current .vscode/tasks.json provides Logger build current solution, Logger safe tests net48 and Logger safe tests net10.0. Build first, then run the two test tasks sequentially. They add the four bridge classes (LogBridgeRepresentationTests, MicrosoftLoggerProviderTests, MicrosoftLoggerFactoryExtensionsTests, MicrosoftLoggerDestinationTests) to the 14-class selection above, use the plural project/filter names and write generated TRX/coverage outputs under TestResults/developer/<target>, not historical run destinations. No task runs automatically. The archive preserves old commands and evidence references as history, not instructions to reactivate them.

The following figures are historical selections, not totals for the current source or rendering checks.

The recorded M2-B Windows check on 2026-09-18 EDT passed 320/320 cases on each of net48 and net10.0, with zero failures/skips: 20 new registration cases plus the original 300 preserved cases per target. Library and example builds also passed; the example was not executed. This is focused explicit-registration evidence, not full-suite or full-v4 certification, fallback/file qualification, independent review approval, or release clearance.

The earlier native Windows check on 2026-09-17 EDT passed 300 cases per target, with zero failures/skips and unchanged same-target case identities. The recorded coverage exercises all seven changed implementation files plus label/policy code; the net48 test copy matches the built netstandard2.0 library, and net10.0 matches its dedicated library. FileDestination, ConsoleDestination and ConsoleWrapper have zero covered lines in this selection. See the portable native assessment. This is a focused result, not the full suite, file/console execution, package-consumer qualification, or Mac/Linux validation.

The earlier label-policy check on the same date recorded 110 cases per target: 67 policy cases plus 43 preserved cases. Its different selection included ConsoleDestinationTests; the historical account is retained separately, not presented as the native check above.

Do not substitute an unfiltered dotnet test as the default developer check. FileDestinationTests.cs now uses isolated synthetic files, but its path/failure checks temporarily change process state; run that class in a separate reviewed test host, not in the default selection above.

The four existing cases in DestinationManagmentTests.cs now use DestinationManagementFixture.cs to exercise real public add/remove/clear/absent-remove operations against fresh loaded Logger state. Automatic output after removal or clearing is confined to owned synthetic paths, not a real application's directories. Following independent readiness review, Windows execution on 2026-10-24 passed all four cases on each of net48 and net10.0, with zero failures or skips, in separate fresh VSTest hosts against the exact readiness-reviewed inputs. Final evidence and code/docs review remain separate gates; this is not an unfiltered run, same-host full-suite proof, full M6, non-Windows verification or release approval. Counts from earlier selections are historical, not a fixed total for the evolving test tree.

For this isolated class on Windows, use the D021 parent c:/temp/logger tests/. The delivered LOGGER-CI-FIX-R1/R2 fixture repair safely prepares missing ordinary-directory ancestry, preserves the existing parent and entries, and rejects symlinks/reparse points and non-directories. On POSIX, the fixture uses the canonical OS temporary directory. On 2026-10-26, Windows Release validation passed the solution build and 863/863 tests on each of net48 and net10.0, with zero failures or skips, using the CI filter Requires!=LocalDb. Native Linux/macOS hosted reruns remain required. Use fresh uniquely owned children containing synthetic data. Clean only verified owned children after users and handles finish; never delete the parent, change pre-existing files or follow links/junctions outside the owned tree. Location permission is not permission to run old unisolated tests.

After a build of the reviewed candidate, run each command separately and sequentially from the repository root, without other test runs or concurrent builds. Each invocation starts a separate VSTest host and selects only DestinationManagementTests; do not merge it into the default 18-class selection or combine it with file/process-state classes:

dotnet test .\ProphetsWay.Logger.Tests\ProphetsWay.Logger.Tests.csproj --configuration Debug --framework net48 --no-build --no-restore --filter "FullyQualifiedName~ProphetsWay.Logger.Tests.DestinationManagementTests." --logger trx --results-directory .\TestResults\developer\destination-management\net48
dotnet test .\ProphetsWay.Logger.Tests\ProphetsWay.Logger.Tests.csproj --configuration Debug --framework net10.0 --no-build --no-restore --filter "FullyQualifiedName~ProphetsWay.Logger.Tests.DestinationManagementTests." --logger trx --results-directory .\TestResults\developer\destination-management\net10.0

The equivalent optional manual tasks are Logger isolated destination management tests net48 and Logger isolated destination management tests net10.0. They neither build nor start other tasks, and write generated TRXs to the target-specific directories above. The three existing build/safe-test tasks and their filters remain unchanged; none runs automatically.

The example program constructs a relative file destination too: build it, do not run it by default. The existing pipeline is not evidence that this exact focused selection ran in CI.

Contributing

Keep changes focused and add xUnit/Shouldly coverage for new behavior. Preserve the intentional utility namespace and consult AGENTS.md before changing public contracts or build files. Use synthetic data; file fixtures must not alter pre-existing files. The current test project, assembly and namespace use ProphetsWay.Logger.Tests; the library remains ProphetsWay.Logger with its intentional ProphetsWay.Utilities namespace. D025 authorizes this test-only rename, not unrelated contract, dependency or version changes.

Versioning And Authors

We use SemVer for versioning. For the versions available, see the tags on this repository. The owner controls version changes; this README does not authorize a bump or a release.

See also the list of contributors who participated in this project.

Changelog

See CHANGELOG.md for unreleased changes and the existing release history.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 was computed.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
4.0.0 117 10/31/2026
4.0.0-527.Beta 50 10/30/2026
4.0.0-527.Alpha 53 10/30/2026
3.0.1-420.Beta 291 5/13/2022
3.0.1-420.Alpha 260 5/13/2022
3.0.1-418.Alpha 277 5/13/2022
3.0.1-352.Beta 269 4/27/2022
3.0.1-352.Alpha 257 4/27/2022
3.0.0 694 1/26/2021
3.0.0-248.Beta 332 1/26/2021
3.0.0-248.Alpha 326 1/26/2021
2.2.0-238.Alpha 346 1/26/2021
2.1.0 731 6/3/2020
2.1.0-182.Beta 423 6/3/2020
2.1.0-182.Alpha 413 6/3/2020
2.0.0 972 4/20/2019
2.0.0-105.Alpha 473 4/21/2019
Loading failed

# Unreleased

## Hosted test-harness portability (native POSIX verification pending)

Owner-approved LOGGER-CI-FIX-R1/R2 implements safe preparation of missing Windows fixture-parent
ancestry, architecture-correct Darwin inode64 bindings, fresh POSIX directory enumeration and
platform-native inert mock paths. Reserved product-created entries must be observed explicitly
at quiescent boundaries; reset must verify selected-file absence before retiring only that old
identity, without lazy adoption or weakened no-follow checks. Windows Release validation on
2026-10-26 passed the solution build and 863/863 tests on each of `net48` and `net10.0`,
with zero failures or skips, using the CI filter `Requires!=LocalDb`.

Initial hosted Windows, Linux and macOS attempts failed, with leading defects in fixture setup,
native ABI/enumeration, ownership identity capture and Windows-only mock inputs; no shipped
Logger bug is established. No passing native Linux/macOS verification is recorded; hosted
reruns remain required, and Windows success or ABI declaration proxies cannot certify them.
This test-harness repair changes no public API, library asset, version or Logger runtime behavior.

## Assertion migration

The three remaining legacy boolean assertions in `DestinationManagementTests` now use
Shouldly instead of FluentAssertions, and the unused FluentAssertions 5.10.3 test-project
reference has been removed. Assertion expressions, expected values, all four test identities
and product operations are unchanged. This completes the assertion/dependency migration
only; it does not claim full M6, release qualification or non-Windows verification.

## Test tooling naming

The owner-approved test project name is now `ProphetsWay.Logger.Tests`, including its
directory, project file and test namespaces. Solution references and current developer
guidance follow the plural name. This mechanical rename preserves test bodies, assertions,
dependencies, target frameworks and the project GUID; the test assembly is not shipped.
Logger runtime behavior, public library namespaces, package identity and version are unchanged.
Historical evidence retains its original identities; fresh validation is required for the rename.

## Destination management test isolation

The four existing `DestinationManagementTests` cases now exercise real public destination
management through fresh loaded Logger state with owned synthetic automatic-file output beneath
the D021 parent `c:/temp/logger tests/`. Method identities and existing assertions are preserved;
Logger runtime behavior, public API, dependencies and version are unchanged. Separate fresh Windows
VSTest hosts passed 4/4 cases on each of `net48` and `net10.0`, with zero failures or skips,
against the readiness-reviewed inputs on 2026-10-24. Final evidence and code/docs review remain
separate gates; this is not same-host full-suite, unfiltered, full M6, non-Windows or release proof.

README guidance and two optional manual class-only tasks keep this execution separate from the
unchanged default 18-class filters. The three existing tasks and historical task archive remain
unchanged. These documentation changes do not requalify the updated package README or package.

## Packaging and debugging metadata

The Logger package project now declares its GitHub project URL and `logging;logger;diagnostics`
tags, uses the standard `git` repository type, and opts into XML documentation, repository metadata,
embedded untracked sources, portable symbol generation, and `.snupkg` symbol packaging. CI-only
`ContinuousIntegrationBuild` is enabled when `TF_BUILD` is `True`, so deterministic CI build metadata
is separated from local builds. These are additive packaging and debuggability improvements; they do
not add runtime API or decide the overall v4 compatibility and versioning question.

The XML documentation setting currently surfaces 58 `CS1591` compiler occurrences, which remain
unresolved. The project metadata has been updated, but package contents, evaluated local-versus-CI
properties, remote Source Link/debugger retrieval, and binary reproducibility are not claimed here.

## Logging abstractions dependency

The Logger library now directly references `Microsoft.Extensions.Logging.Abstractions` `10.0.12`. Consumers should account for the corresponding transitive restore closure, including `Microsoft.Extensions.DependencyInjection.Abstractions` and the supporting `System.*` packages selected for the target framework. This entry records dependency adoption only; it does not claim that the current build, tests, or package qualification have completed.

## Inbound Microsoft logging bridge

Current unreleased source adds `MicrosoftLoggerFactoryExtensions.AddProphetsWay(ILoggerFactory,
IMicrosoftLogLabelMapper = null)`. An explicit call creates one `MicrosoftLoggerProvider`, registers
that provider with the supplied factory, and returns the same provider. Its provider-created loggers
retain their supplied categories and share the provider's lifetime and scope source. Inbound dispatch
uses the exact `LogBridgeEntry` route while retaining concrete `LogBridgeEntry<TState>` payloads.

Callers may explicitly supply an `IMicrosoftLogLabelMapper`; the mapper and factory are borrowed.
The host must arrange provider cleanup by explicitly disposing the returned provider or ensuring
the factory/provider's normal lifetime handling retires it; provider disposal is idempotent. The
provider begins with its own logical-flow scope source; a caller-supplied external scope source and
its scope handles remain borrowed and are cleaned up by their opener. The provider does not dispose
the factory, mapper, supplied scope source, or native destinations.

This describes current source, not the published package or release qualification. The outbound
Logger-to-Microsoft destinations are described separately below; enabling this inbound provider does
not register them. This entry does not claim M5/M6 completion.

## Outbound Microsoft logging destinations

Current unreleased source adds two opt-in outbound destinations: `MicrosoftLoggerDestination` for
ordinary native entries and `GenericMicrosoftLoggerDestination<T>` for an exact declared-`T` route.
Each accepts either a borrowed `ILoggerFactory` (with an optional category fallback) or a borrowed
fixed `ILogger`. Register them explicitly with `Logger.AddDestination(destination)` or
`Logger.AddDestination<T>(destination)`; outbound registration does not install the inbound provider.

Native severity and label selection happen before Microsoft callbacks. The adapter maps one lowest
set native severity bit to one Microsoft level, retains the original mask and available entry state,
exception, event/category, structured properties, and separate native-context/external-scope facts.
The transport keeps entry, native contexts and external scopes in distinct ordered groups; scope
replay preserves individual frames and cleans returned handles in reverse order. The factory's
category fallback applies only when the source category is null; a fixed logger retains its category.
`IsEnabled == false` is normal rejection. The destination does not classify or sanitize consumer data.

Registration does not transfer ownership: clearing or removing a destination does not dispose its
factory or fixed logger. Output and cleanup failures follow Logger's safe reporting and propagation
contract. This describes current unreleased source only, not the published package, package/consumer
qualification, M6 completion, release readiness, or non-Windows verification.

## Controlled Microsoft bridge returns

- Fixed unchanged controlled outbound calls fanned out through multiple `AddProphetsWay`
 providers to preserve original entry labels and visited-route suppression on matching receipts.
- Fixed controlled-return registration selection, intrinsic/custom severity checks and native
 handoff to use the retained full native severity mask rather than the projected Microsoft level.

## Support and tooling

The library target set is now `netstandard2.0;net10.0`. This removes dedicated assets for the
older .NET Framework, .NET Standard 1.x, .NET Core, .NET 5 and .NET 6 targets, including the former
`net48` library asset. Consumers that can use the `netstandard2.0` asset remain supported; consumers
that require one of the removed assets must move to a compatible `netstandard2.0` consumer or to
`net10.0`. This target change is breaking and requires a major-version decision before publication.

The test project now exercises `net48` and `net10.0` with the refreshed xUnit v3 tooling. This changes
the verification matrix, not the Logger runtime behavior.

## Native severity and destination validation

The native Logger severity model now has six exact bits: `Critical = 1`, `ErrorOnly = 2`,
`WarningOnly = 4`, `InformationOnly = 8`, `DebugOnly = 16`, and `TraceOnly = 32`. Inclusive
destination masks are `Error = 3`, `Warning = 7`, `Information = 15`, `Debug = 31`, and
`Trace = 63`; a destination accepts a composite message only when it contains every requested bit.
The three public `Security` helper forms have been removed. The Logger's internal `Log` helpers remain
private, while `Log` on destination interfaces remains public for direct destination calls. There is
no compatibility replacement for the removed `Security` names, so callers must select the new severity
helper that matches their intent.

The ordinary, metadata-typed, and metadata extension helper families now expose the six severity
operations with exact-bit delivery and explicit argument requirements: `Trace`, `Debug`, `Info`, and
`Warn` require a message; `Error` requires an exception and permits a missing message; `Critical`
requires both. Existing callers should update removed helpers and any calls that relied on omitted
arguments or on the former cumulative severity values.

Destination masks supplied as enum values, integers, or recognized case-sensitive strings are now
validated strictly. Values from 0 through 63 are representable, including unnamed combinations such
as `9`; zero is a valid active reject-all destination mask. The new validation rejects invalid, negative,
unsupported, malformed, or null inputs with argument errors; it does not imply that all such invalid
forms previously shared one `Information` fallback. Destination eligibility continues to require every
requested message bit, while the new raw and direct destination guards require a nonzero mask from 1
through 63 and validate before callbacks or output. Valid calls preserve the original composite mask,
message, metadata, and exception. Exception details are included for valid warnings and composites as
well as errors, including when the raw message is null; no synthetic message or exception is fabricated.

This is breaking for consumers that compile against the removed `Security` members or depend on the
old enum numbers, permissive helper arguments, or inputs now rejected by strict validation. The current
tree is unreleased v4-direction source; this entry describes the native severity change, not full v4
integration or the output-failure policy. The outbound Microsoft bridge is recorded in its separate
current-source entry below. Native text framing is covered by the M4-A entry; remaining qualification
work is not claimed here.

## Sensitivity labels

A new immutable `SensitivityLabel` reference type is available in `ProphetsWay.Utilities`. Create one
with an application-defined identifier, for example:

```csharp
var label = new SensitivityLabel("internal");
```

Labels retain their exact non-null identifier, compare by ordinal value, and provide a matching hash
code. Identifiers must contain 1 through 256 UTF-16 code units and must not contain whitespace or
control characters. Invalid input is rejected without copying the supplied identifier into argument
diagnostics.

## Pure destination-label policy

The new `LabelFilterMode` enum (`NoFilter`, `Exclude`, and `AllowOnly`) and `DestinationLabelPolicy`
class provide immutable, defensive-copying membership evaluation. `Exclude` rejects any intersecting
label; `AllowOnly` requires nonempty effective membership wholly contained in the configured labels;
`NoFilter` permits valid effective input. Duplicate identities and ordering do not affect the result,
and null labels or undeclared modes are rejected with argument errors.

This remains a standalone predicate API for callers that want to evaluate a policy directly; it does
not render or redact content, select fallback destinations, or provide confidentiality or security
guarantees. M3 also uses the immutable policy as an additional whole-entry gate through
`DestinationRegistrationSettings` and the destination's intrinsic `LabelPolicy`: both configured
and intrinsic restrictions must permit the complete effective label union before payload delivery.
A label denial is a deliberate non-failure and does not select fallback; enabled membership still
suppresses fallback on that route.

The pure destination-label policy now protects its configured membership readback from ordinary collection-interface mutation attempts, including the synchronization-root path that previously exposed its owned backing list on the modern runtime. Constructed policies retain the same deduplicated, ordinal membership, and `Mode`, `Allows`, and the public API remain unchanged; consumers do not need to change their calls.

## Explicit destination registration

The existing ordinary and metadata-typed registration methods now maintain separate, exact routes. A
typed registration is selected by its declared `T`, not by runtime metadata assignability, and a
destination-contract type does not alias the ordinary route. The same compatible destination reference
may be registered on distinct routes, but adding that same reference twice to one route now throws
`ArgumentException` with `ParamName` `newDest`. Removal is reference-only, so an equal but distinct
destination remains registered, survivor order is preserved, and remove/clear affect only their selected
route. These are breaking behavior changes for callers that relied on duplicate registration, equality-
based removal, or ordinary/typed route sharing; no method signature or public type was added, and callers
should register each intended route explicitly and retain the reference they intend to remove.

Registration and dispatch now publish complete ordered membership captures before user eligibility or
callbacks run. Mutations from those callbacks affect later captures, recursive dispatch captures again,
and an older capture may still invoke a removed or cleared destination after the mutation returns.
Registration does not invoke recipients, and remove/clear never dispose borrowed destinations; hosts
must quiesce producers and await synchronous calls before disposing them. This corrects the prior live-
enumeration and ownership hazards without promising a drain, immediate revocation, or automatic fallback.

## Log annotation occurrences

The new `LogAnnotations` value captures an explicit `IEnumerable<SensitivityLabel>` through its
constructor and exposes the successful capture through the read-only `LabelOccurrences` property.
The constructor copies the supplied occurrences in order, preserves duplicates, accepts an empty
sequence, and rejects null input or null elements. A failed or unsupported sequence capture does not
publish a usable partial value; callers remain responsible for providing a finite, stable sequence.
The returned collection is read-only. `BeginScope` can attach one to a native scope and
`LogAnnotated` can attach one to an entry; dispatch captures the enclosing scopes and entry
annotation together before recipient callbacks, while the policy predicate still uses deduplicated
ordinal membership rather than occurrence order. An annotation remains data, not authorization,
classification, formatting, redaction, or a security guarantee.

## Configured dispatch failure reporting

Configured ordinary and declared-typed routes now capture the complete route, settings, scopes and
effective labels before attempting each enabled, independently eligible recipient. Registration
severity, destination severity and both applicable label policies must permit the entry; a contextual
recipient receives one contextual handoff and a legacy recipient receives one raw handoff. A deliberate
Boolean label denial withholds the entry from that recipient without recording a failure; a
`LabelCheck` exception is recorded and returns through the safe report boundary. Neither kind of label
outcome stops later captured recipients, while an eligibility or output callback failure also does not
stop later captured recipients.
After applicable attempts, the call attempts bounded notification through `Logger.DispatchFailed` when
subscribers are present and same-thread recursive reporting is not already suppressed, along with the
ordinary stderr summary, then throws `LogDispatchException` for mandatory eligibility/output failures.
A capture or check-only failure therefore permits the whole call to return safely only when no mandatory
eligibility/output failure also occurred, so mixed outcomes remain represented by `LogDispatchException`.
The report exposes a correlation ID, encounter-ordered failure descriptors with each recipient's
one-based captured position and `LabelCheck`, `Eligibility` or `Output` stage, an overflow count when
more failures occurred than the retained descriptor limit, and a separate `CoreCaptureFailureCount`
for a shared capture failure. Subscriber failures are contained, and the safe exception/report boundary
does not retain or expose the original callback causes.

Consumers that previously handled only the first raw recipient exception should instead catch
`LogDispatchException` and inspect its `Report`, and may subscribe to `Logger.DispatchFailed` when they
need the bounded notification. This contract applies to configured routes; unconfigured fallback
behavior remains separately qualified, and it does not claim automatic fallback, retries, rollback,
or full exception-graph sanitization.

The configured-route failure behavior corrects the prior single-failure propagation boundary. This
entry records that configured-route slice, not the full v4 integration or automatic Trace/file behavior.
Native text framing is recorded in the M4-A entry below; file lifecycle/termination and broader
qualification are separate. Current outbound source behavior is described in the M5 entry above.

## Native scopes and contextual destinations

The Logger now captures native scopes and entry annotations into an immutable `LogContext`. Use
`BeginScope` for ordered scope properties and labels, and `LogAnnotated` for entry labels; captured
scope and label membership is complete at capture time, while nested property values remain the
caller-owned objects. Scope handles are flow-local and conventional: dispose them in order, and do
not treat a retained `LogContext` as authorization to bypass current destination checks.

Destination registration now has immutable per-registration `Enabled`, severity-mask, and label-policy
settings. `SetDestinationSettings` publishes a complete replacement atomically, so a callback sees
either the old settings or the new settings rather than a partially updated combination. The ordinary
and exact-declared-metadata-type routes remain separate. Existing independent destination interfaces
remain valid; contextual interfaces are optional extensions for destinations that need the captured
context.

Supplied destinations and base classes now expose guarded direct `Log` calls and optional
`LogWithContext` calls. Custom destinations deriving from `BaseLoggingDestination` or
`BaseLoggingDestination<T>` must move their implementation to the protected `LogCore` override;
the public logging entrypoints are guarded and are no longer the subclass override point. This is a
source and binary compatibility break for custom destinations that overrode the former public logging
member. Built-in event destinations expose the selected context through their event arguments, while
event delivery preserves the original payload, metadata, exception and existing event semantics. Native
text rendering and framing are covered by the separate M4-A entry below.

Failure results now distinguish a failed native capture from a destination `LabelCheck`, `Eligibility`,
or `Output` failure. Shared capture and label-check failures report safely and return without handing
the incomplete or rejected entry to that recipient; eligibility and output failures remain mandatory
`LogDispatchException` results after independent attempts. `CoreCaptureFailureCount` records the core
capture count without inventing a recipient failure, and failure-report membership no longer exposes a
writable `SyncRoot` alias through collection interfaces. Consumers reading `LogDispatchException.Report`
can therefore distinguish these safe result paths without receiving callback causes or payload data.

This M3 work is unreleased and does not by itself claim publication or release readiness. The custom
destination override change has major-version implications; the new scope, annotation, contextual
delivery, settings, and failure-report members are additive individually, but they do not make that
overall compatibility decision a minor or patch change. The accepted local validation is green on the
focused `net48` and `net10.0` matrix, with the library/example builds and compile-only README checks
also passing; it is not unfiltered real-file fixture certification. The permanent report-membership
regression and parent final gate are complete within that accepted local boundary; they are not pending release work. M4-A native text rendering and framing is now implemented as a separate unreleased slice. M4-B, the outbound Microsoft bridge, file lifecycle/termination and broader release qualification were separate from this M3 scope; later Unreleased entries describe subsequent work.

## Native text rendering and framing

Native ordinary and exact-declared-metadata text destinations now render one complete, unterminated
single-line record from the call's captured `LogContext.EventTimestampUtc`. The prefix uses invariant
UTC `O` formatting and the existing full severity spelling; entry labels and every captured native scope
frame follow in their original order, including empty frames, duplicate labels, repeated or null keys,
and null values. Message, exception, metadata, label, key, and formatted property-value content is
escaped as data, so null, empty, whitespace, literal `null`, and embedded line boundaries remain
distinct without being silently discarded. Raw/event transport and the existing local event timestamp
semantics are unchanged.

This changes the default text layout and is a breaking output-contract change for consumers that parse,
snapshot, or otherwise depend on the former local-time prefix and message-only text. Update those parsers
and fixtures to the structured record layout; custom text destinations still implement `PrintLogEntry`,
but must treat its input as the new complete record rather than reconstructing the old layout. The new
`LogContext.EventTimestampUtc`, protected `FormatValue(object value)` hook, and
`GenericTextBasedDestination<T>` are additive individually. The default formatter supports the documented
scalar set with invariant formats, returns `[no formatter: TypeName]` for unsupported values, and emits
null as a null token; an override may extend scalar formatting, but a thrown formatter, massage, render,
or print operation remains an output failure. Consumers overriding `FormatValue` should return unescaped
text and leave framing/escaping to the destination.

This M4-A slice does not claim automatic Trace/file behavior, physical file termination or lifecycle,
either Microsoft bridge direction, fallback completion, or publication/release qualification. Current
inbound and outbound Microsoft source behavior is described in separate entries above; neither was
part of this native text-framing slice. This is an unreleased v4-direction slice; no version number is
changed here.

## Explicit file destinations

`FileDestination` now defaults all three constructor overloads to `resetFile: false`, so constructing a
destination no longer deletes an existing selected file unless deletion is explicitly requested with
`resetFile: true`. This is a breaking v4-direction behavior change for source callers that omitted the
argument: recompile them with the desired value. Previously compiled callers retain the default value
embedded in their call site until rebuilt, and callers that already pass `true` retain eager deletion.

The destination captures the selected `fileName` path at construction and writes back to that same path,
creating a missing file there on permitted output. Each write appends the rendered record followed by one
`Environment.NewLine`, using the selected one of the five declared encodings (`ASCII`, `BigEndianUnicode`,
`Unicode`, `UTF8`, or `UTF32`). It does not add a BOM, repair an unterminated existing prefix, inspect or
transcode existing bytes, or relocate output. Undefined encoding values now fail with
`ArgumentOutOfRangeException` for `encoder` before deletion or directory creation. Invalid `fileName`
values identify `fileName`; ordinary framework filesystem and access diagnostics remain the originating
exceptions rather than being replaced by a console echo.

This remains an explicit-file implementation only. It does not claim automatic fallback, recovery, retry,
replay, relocation, shared-session behavior, or publication/release qualification. The default change and
the established file-output contract have major-version implications; the version file remains unchanged.

## Automatic file destinations

Automatic file output is now enabled as the implicit final `Trace` recipient for an ordinary route and
for each exact declared-metadata-type route when that route has no enabled compatible explicit
registration. An enabled explicit destination that rejects or fails still suppresses that route's
automatic output; automatic output does not rescue it, and a label denial remains a deliberate
non-failure. Ordinary and typed automatic routes share one session and one selected pathname, while
remaining distinct for rendering and metadata retention. The typed route preserves its declared
metadata, including `null` or `default(T)`.

The default primary directory is the consuming host's `AppContext.BaseDirectory`. Before the first
automatic attempt, applications may select a different primary directory:

```csharp
Logger.ConfigureAutomaticFileHostDirectory(directory);
```

The path is normalized when configured and must be supplied before automatic establishment starts;
configuration performs no directory or permission probe and cannot reset failure state or move an
existing file. If the captured primary location is unavailable during initial establishment, the
session tries one application-associated directory under
`Environment.SpecialFolder.LocalApplicationData`. It selects one UTF-8 file named with the UTC
allocation timestamp and a GUID token, creates missing directories and avoids an existing-name
collision. The selected pathname is retained for the session, and later records append one
`Environment.NewLine` after the complete native rendered record.

Initial inability to establish either location is remembered: the automatic attempt returns a
mandatory output failure on that call and later calls do not keep probing or silently switch
locations. After a pathname is selected, a later open, write, flush or disposal failure also remains
an output failure; the record is not replayed, relocated or retried. Consumers should handle the
existing `LogDispatchException` failure contract and should configure the primary directory before
the first log call when the host's base directory is not an appropriate output location. This is
additive API surface within the unreleased v4-direction change, whose automatic output, fallback
suppression and failure semantics are breaking behavior decisions; the version file remains `3.0.1`.

## Bridge carrier representation

The Logger now exposes the assembly-created `LogBridgeEntry`, `LogBridgeEntry<TState>`, and
`LogBridgeScope` carrier types. They preserve original typed or opaque state, declared state type,
producer delegate, exception, cached text, ordered structured property and scope frames, annotations,
and native source-origin context; their constructors remain assembly-only, and captured membership is
read-only without deep-freezing nested caller-owned values. As recorded with the carrier-only source
on 2026-10-03, that change did not add inbound or outbound adapters, activation, routing, loop guards,
or lifecycle behavior. Later M5 entries above describe the subsequent inbound and outbound source behavior.

## Microsoft log label mapper contract

The v4-direction contract now includes the public `IMicrosoftLogLabelMapper` interface for explicit
mapping of external Microsoft logging input to optional `LogAnnotations`. Implementations may map each
entry through `MapEntry<TState>` and each captured external scope frame through `MapScope`; the
callbacks receive the completed original facts and may return no attachment or a present annotation.
At the time this mapper contract was recorded on 2026-10-03, it was contract surface only and did not
include a provider implementation, callback invocation, routing, activation, or lifecycle behavior.
Current inbound callback use and outbound behavior are described in separate entries above; outbound
is not part of this mapper contract, and no release qualification is claimed here.