diff --git a/Core/Interface/ExternC.h b/Core/Interface/ExternC.h
index ed9f96b0..e8f6dde2 100644
--- a/Core/Interface/ExternC.h
+++ b/Core/Interface/ExternC.h
@@ -1,3 +1,6 @@
+/** @file
+ *  The C-linkage guard macros (EXTERN_C_BEGIN / EXTERN_C_END) that wrap every
+ *  public header so a C++ consumer links the declarations with C linkage. */
 #ifndef EXTERNC_H
 #define EXTERNC_H
 
diff --git a/Core/Interface/SolidSyslog.h b/Core/Interface/SolidSyslog.h
index a24ef413..14f2a19d 100644
--- a/Core/Interface/SolidSyslog.h
+++ b/Core/Interface/SolidSyslog.h
@@ -1,3 +1,6 @@
+/** @file
+ *  The application logging API: SolidSyslog_Log / _LogWithSd to emit an event,
+ *  SolidSyslog_Service to drive delivery, and the SolidSyslogMessage struct. */
 #ifndef SOLIDSYSLOG_H
 #define SOLIDSYSLOG_H
 
diff --git a/Core/Interface/SolidSyslogAddress.h b/Core/Interface/SolidSyslogAddress.h
index 35aacc8b..0a6ea773 100644
--- a/Core/Interface/SolidSyslogAddress.h
+++ b/Core/Interface/SolidSyslogAddress.h
@@ -1,3 +1,6 @@
+/** @file
+ *  The opaque resolved-destination handle a Resolver writes and a Datagram or
+ *  Stream reads; the concrete layout is private to each platform's sources. */
 #ifndef SOLIDSYSLOGADDRESS_H
 #define SOLIDSYSLOGADDRESS_H
 
diff --git a/Core/Interface/SolidSyslogAtomicCounter.h b/Core/Interface/SolidSyslogAtomicCounter.h
index bb25c0e6..f588f933 100644
--- a/Core/Interface/SolidSyslogAtomicCounter.h
+++ b/Core/Interface/SolidSyslogAtomicCounter.h
@@ -1,3 +1,7 @@
+/** @file
+ *  The atomic-counter role: hand out the next sequenceId (Increment), wrap-aware
+ *  over [1, 2^31 - 1] and never 0 per RFC 5424 §7.3.1. This call dispatches to
+ *  the injected counter's vtable, so behaviour is that counter's. */
 #ifndef SOLIDSYSLOGATOMICCOUNTER_H
 #define SOLIDSYSLOGATOMICCOUNTER_H
 
diff --git a/Core/Interface/SolidSyslogAtomicCounterDefinition.h b/Core/Interface/SolidSyslogAtomicCounterDefinition.h
index 596002b0..0c0ba4f8 100644
--- a/Core/Interface/SolidSyslogAtomicCounterDefinition.h
+++ b/Core/Interface/SolidSyslogAtomicCounterDefinition.h
@@ -1,3 +1,6 @@
+/** @file
+ *  The AtomicCounter vtable (Increment) — the contract an implementor fills in
+ *  (the AtomicCounter extension point). */
 #ifndef SOLIDSYSLOGATOMICCOUNTERDEFINITION_H
 #define SOLIDSYSLOGATOMICCOUNTERDEFINITION_H
 
diff --git a/Core/Interface/SolidSyslogBlockDevice.h b/Core/Interface/SolidSyslogBlockDevice.h
index 5e858a55..598d5905 100644
--- a/Core/Interface/SolidSyslogBlockDevice.h
+++ b/Core/Interface/SolidSyslogBlockDevice.h
@@ -1,3 +1,8 @@
+/** @file
+ *  The block-device role: block-indexed storage (Acquire / Dispose / Exists /
+ *  Read / Append / WriteAt / Size / GetBlockSize) beneath a BlockStore. These
+ *  calls dispatch to the injected device's vtable, so behaviour is that
+ *  device's. */
 #ifndef SOLIDSYSLOGBLOCKDEVICE_H
 #define SOLIDSYSLOGBLOCKDEVICE_H
 
diff --git a/Core/Interface/SolidSyslogBlockDeviceDefinition.h b/Core/Interface/SolidSyslogBlockDeviceDefinition.h
index 9ee284d3..73a38254 100644
--- a/Core/Interface/SolidSyslogBlockDeviceDefinition.h
+++ b/Core/Interface/SolidSyslogBlockDeviceDefinition.h
@@ -1,3 +1,7 @@
+/** @file
+ *  The BlockDevice vtable (Acquire / Dispose / Exists / Read / Append / WriteAt /
+ *  Size / GetBlockSize) — the contract an implementor fills in (the BlockDevice
+ *  extension point). */
 #ifndef SOLIDSYSLOGBLOCKDEVICEDEFINITION_H
 #define SOLIDSYSLOGBLOCKDEVICEDEFINITION_H
 
diff --git a/Core/Interface/SolidSyslogBlockStore.h b/Core/Interface/SolidSyslogBlockStore.h
index 432a0e87..e79555ec 100644
--- a/Core/Interface/SolidSyslogBlockStore.h
+++ b/Core/Interface/SolidSyslogBlockStore.h
@@ -1,3 +1,24 @@
+/** @file
+ *  A store-and-forward Store backed by a BlockDevice: records are appended to
+ *  the current write block, and once a block fills the write rolls to the next,
+ *  giving durable retention across a restart. Create resumes from whatever
+ *  records are already on the device (scanning the read block, honouring any
+ *  per-record integrity trailer from the injected SecurityPolicy) so a reboot
+ *  keeps unsent records queued.
+ *
+ *  MaxBlocks caps retention; DiscardPolicy governs the overflow once every block
+ *  is full — Oldest evicts the oldest block to keep accepting writes, Newest
+ *  refuses the incoming record, Halt refuses it, latches (IsHalted stops
+ *  Service), and fires OnStoreFull once. An optional capacity-threshold function
+ *  (queried each Write) drives an edge-triggered OnThresholdCrossed callback for
+ *  early back-pressure signalling. Mind the recursion gotcha: under a
+ *  PassthroughBuffer, SolidSyslog_Log sends inline, so logging from the
+ *  threshold callback re-enters Write — drive the logger from a returning Buffer
+ *  or gate the Log instead.
+ *
+ *  Internally each pool slot composes an inner RecordStore over a BlockSequence,
+ *  both drawn from sibling pools; a block too small for one worst-case record is
+ *  grown to fit and reported as a WARNING rather than failing Create. */
 #ifndef SOLIDSYSLOGBLOCKSTORE_H
 #define SOLIDSYSLOGBLOCKSTORE_H
 
diff --git a/Core/Interface/SolidSyslogBlockStoreErrors.h b/Core/Interface/SolidSyslogBlockStoreErrors.h
index ce6d3ba9..59c22abb 100644
--- a/Core/Interface/SolidSyslogBlockStoreErrors.h
+++ b/Core/Interface/SolidSyslogBlockStoreErrors.h
@@ -1,3 +1,5 @@
+/** @file
+ *  Error codes and Source identity for the BlockStore. */
 #ifndef SOLIDSYSLOGBLOCKSTOREERRORS_H
 #define SOLIDSYSLOGBLOCKSTOREERRORS_H
 
diff --git a/Core/Interface/SolidSyslogBuffer.h b/Core/Interface/SolidSyslogBuffer.h
index e310d93f..0f221885 100644
--- a/Core/Interface/SolidSyslogBuffer.h
+++ b/Core/Interface/SolidSyslogBuffer.h
@@ -1,3 +1,8 @@
+/** @file
+ *  The buffer role: producer Write / consumer Read that decouples
+ *  SolidSyslog_Log from Service. These calls dispatch to the injected buffer's
+ *  vtable, so behaviour — notably whether Write blocks or returns at once — is
+ *  that buffer's. */
 #ifndef SOLIDSYSLOGBUFFER_H
 #define SOLIDSYSLOGBUFFER_H
 
diff --git a/Core/Interface/SolidSyslogBufferCategories.h b/Core/Interface/SolidSyslogBufferCategories.h
index aeabce0f..c0369e5c 100644
--- a/Core/Interface/SolidSyslogBufferCategories.h
+++ b/Core/Interface/SolidSyslogBufferCategories.h
@@ -1,3 +1,6 @@
+/** @file
+ *  Portable category constants (uint16_t macros) for the Buffer role:
+ *  SOLIDSYSLOG_CAT_BUFFER_BACKEND_FAILED. */
 #ifndef SOLIDSYSLOGBUFFERCATEGORIES_H
 #define SOLIDSYSLOGBUFFERCATEGORIES_H
 
diff --git a/Core/Interface/SolidSyslogBufferDefinition.h b/Core/Interface/SolidSyslogBufferDefinition.h
index f0d85c5f..aa169fce 100644
--- a/Core/Interface/SolidSyslogBufferDefinition.h
+++ b/Core/Interface/SolidSyslogBufferDefinition.h
@@ -1,3 +1,6 @@
+/** @file
+ *  The Buffer vtable (Write / Read) — the contract an implementor fills in (the
+ *  Buffer extension point). */
 #ifndef SOLIDSYSLOGBUFFERDEFINITION_H
 #define SOLIDSYSLOGBUFFERDEFINITION_H
 
diff --git a/Core/Interface/SolidSyslogCircularBuffer.h b/Core/Interface/SolidSyslogCircularBuffer.h
index 0c2171ba..aa5e5d4e 100644
--- a/Core/Interface/SolidSyslogCircularBuffer.h
+++ b/Core/Interface/SolidSyslogCircularBuffer.h
@@ -1,3 +1,19 @@
+/** @file
+ *  An in-memory ring Buffer that decouples Log (enqueue) from Service (drain),
+ *  backed entirely by caller-supplied storage — no allocation of its own.
+ *
+ *  Records are framed with a uint16 length prefix and stored back-to-back. A
+ *  record is never split across the ring's end: one that would straddle the
+ *  wrap point is written whole to the front, leaving a gap that the reader skips
+ *  via a wrap marker. On a full ring the newest record is dropped (the write is
+ *  simply refused) rather than overwriting unsent data, so the oldest queued
+ *  records survive. A record larger than SOLIDSYSLOG_MAX_MESSAGE_SIZE is
+ *  rejected outright, and a Read whose buffer is too small for the head record
+ *  leaves the record in place and reports nothing delivered.
+ *
+ *  Every enqueue and drain is bracketed by the injected mutex, so the two sides
+ *  are safe on separate tasks; inject SolidSyslogNullMutex_Get() for single-task
+ *  use where the lock is pure overhead. */
 #ifndef SOLIDSYSLOGCIRCULARBUFFER_H
 #define SOLIDSYSLOGCIRCULARBUFFER_H
 
diff --git a/Core/Interface/SolidSyslogCircularBufferErrors.h b/Core/Interface/SolidSyslogCircularBufferErrors.h
index 63d66a44..da65ecf2 100644
--- a/Core/Interface/SolidSyslogCircularBufferErrors.h
+++ b/Core/Interface/SolidSyslogCircularBufferErrors.h
@@ -1,3 +1,5 @@
+/** @file
+ *  Error codes and Source identity for the CircularBuffer. */
 #ifndef SOLIDSYSLOGCIRCULARBUFFERERRORS_H
 #define SOLIDSYSLOGCIRCULARBUFFERERRORS_H
 
diff --git a/Core/Interface/SolidSyslogConfig.h b/Core/Interface/SolidSyslogConfig.h
index a788d9e5..d129bf1f 100644
--- a/Core/Interface/SolidSyslogConfig.h
+++ b/Core/Interface/SolidSyslogConfig.h
@@ -1,3 +1,6 @@
+/** @file
+ *  The setup-time wiring: the SolidSyslogConfig struct and SolidSyslog_Create /
+ *  _Destroy that build and release a logger from it. */
 #ifndef SOLIDSYSLOGCONFIG_H
 #define SOLIDSYSLOGCONFIG_H
 
diff --git a/Core/Interface/SolidSyslogConfigLock.h b/Core/Interface/SolidSyslogConfigLock.h
index 3352aff9..646d952f 100644
--- a/Core/Interface/SolidSyslogConfigLock.h
+++ b/Core/Interface/SolidSyslogConfigLock.h
@@ -1,3 +1,6 @@
+/** @file
+ *  The config-time critical-section injection pair guarding every pool
+ *  Create/Destroy slot-walk; the no-op default suits single-task setup. */
 #ifndef SOLIDSYSLOGCONFIGLOCK_H
 #define SOLIDSYSLOGCONFIGLOCK_H
 
diff --git a/Core/Interface/SolidSyslogCrc16.h b/Core/Interface/SolidSyslogCrc16.h
index 6fd67b50..0cbd711b 100644
--- a/Core/Interface/SolidSyslogCrc16.h
+++ b/Core/Interface/SolidSyslogCrc16.h
@@ -1,3 +1,8 @@
+/** @file
+ *  CRC-16/CCITT-FALSE checksum (poly 0x1021, init 0xFFFF, no reflection, no
+ *  final XOR; a.k.a. CRC-16/IBM-3740, check value 0x29B1). A pure function over
+ *  a byte range — no state, no lifecycle. Used by SolidSyslogCrc16Policy for an
+ *  unkeyed at-rest integrity trailer. */
 #ifndef SOLIDSYSLOGCRC16_H
 #define SOLIDSYSLOGCRC16_H
 
diff --git a/Core/Interface/SolidSyslogCrc16Policy.h b/Core/Interface/SolidSyslogCrc16Policy.h
index 4ea18f1b..3c9639d6 100644
--- a/Core/Interface/SolidSyslogCrc16Policy.h
+++ b/Core/Interface/SolidSyslogCrc16Policy.h
@@ -1,3 +1,13 @@
+/** @file
+ *  A SecurityPolicy that appends a two-byte CRC-16 trailer to each stored
+ *  record. Seal computes the CRC over the whole content; Open recomputes and
+ *  compares. This is an unkeyed checksum — it catches accidental corruption
+ *  (bit-rot, a truncated write) but is not tamper-evidence: anyone who edits a
+ *  record can recompute a matching CRC. For tamper-evidence or confidentiality
+ *  use a keyed policy. Being a checksum (not an AEAD), it ignores the record's
+ *  header/body split and checks the whole content as one span. The instance is
+ *  a shared stateless singleton, so it holds no pool slot and Destroy is a
+ *  no-op. */
 #ifndef SOLIDSYSLOGCRC16POLICY_H
 #define SOLIDSYSLOGCRC16POLICY_H
 
diff --git a/Core/Interface/SolidSyslogDatagram.h b/Core/Interface/SolidSyslogDatagram.h
index 2ef32590..b1005a38 100644
--- a/Core/Interface/SolidSyslogDatagram.h
+++ b/Core/Interface/SolidSyslogDatagram.h
@@ -1,3 +1,7 @@
+/** @file
+ *  The datagram role: connectionless send of one message to an address (Open /
+ *  SendTo / Close), with a path-MTU hint (MaxPayload). These calls dispatch to
+ *  the injected datagram's vtable, so behaviour is that datagram's. */
 #ifndef SOLIDSYSLOGDATAGRAM_H
 #define SOLIDSYSLOGDATAGRAM_H
 
diff --git a/Core/Interface/SolidSyslogDatagramDefinition.h b/Core/Interface/SolidSyslogDatagramDefinition.h
index 2d239031..974269f5 100644
--- a/Core/Interface/SolidSyslogDatagramDefinition.h
+++ b/Core/Interface/SolidSyslogDatagramDefinition.h
@@ -1,3 +1,7 @@
+/** @file
+ *  The Datagram vtable (Open / SendTo / MaxPayload / Close) — the unconnected
+ *  (UDP) transport contract an implementor fills in (the Datagram extension
+ *  point). */
 #ifndef SOLIDSYSLOGDATAGRAMDEFINITION_H
 #define SOLIDSYSLOGDATAGRAMDEFINITION_H
 
diff --git a/Core/Interface/SolidSyslogEndpoint.h b/Core/Interface/SolidSyslogEndpoint.h
index e1827d74..b1809583 100644
--- a/Core/Interface/SolidSyslogEndpoint.h
+++ b/Core/Interface/SolidSyslogEndpoint.h
@@ -1,3 +1,6 @@
+/** @file
+ *  The destination a sender is directed at (host sink + port) and the callbacks
+ *  a sender uses to pull it and to detect when it changes. */
 #ifndef SOLIDSYSLOGENDPOINT_H
 #define SOLIDSYSLOGENDPOINT_H
 
diff --git a/Core/Interface/SolidSyslogEndpointHost.h b/Core/Interface/SolidSyslogEndpointHost.h
index 0d804a84..19d482f6 100644
--- a/Core/Interface/SolidSyslogEndpointHost.h
+++ b/Core/Interface/SolidSyslogEndpointHost.h
@@ -1,3 +1,6 @@
+/** @file
+ *  The value sink an endpoint callback writes the destination host into —
+ *  copied verbatim so a DNS name or IP literal reaches the resolver intact. */
 #ifndef SOLIDSYSLOGENDPOINTHOST_H
 #define SOLIDSYSLOGENDPOINTHOST_H
 
diff --git a/Core/Interface/SolidSyslogError.h b/Core/Interface/SolidSyslogError.h
index 5eda1a4d..5d6c95e9 100644
--- a/Core/Interface/SolidSyslogError.h
+++ b/Core/Interface/SolidSyslogError.h
@@ -1,3 +1,7 @@
+/** @file
+ *  The error-reporting API: SolidSyslog_SetErrorHandler to install a handler,
+ *  SolidSyslog_Error to emit, and the event's Severity / Source / Category /
+ *  Detail axes a handler reads. */
 #ifndef SOLIDSYSLOGERROR_H
 #define SOLIDSYSLOGERROR_H
 
diff --git a/Core/Interface/SolidSyslogErrorCategory.h b/Core/Interface/SolidSyslogErrorCategory.h
index 0dcdd584..803b788a 100644
--- a/Core/Interface/SolidSyslogErrorCategory.h
+++ b/Core/Interface/SolidSyslogErrorCategory.h
@@ -1,3 +1,6 @@
+/** @file
+ *  The portable error-category axis: the universal lifecycle category macros
+ *  and the per-role base ranges a handler switches on or an emit site picks. */
 #ifndef SOLIDSYSLOGERRORCATEGORY_H
 #define SOLIDSYSLOGERRORCATEGORY_H
 
diff --git a/Core/Interface/SolidSyslogErrors.h b/Core/Interface/SolidSyslogErrors.h
index 1b8ea900..dbe4cee7 100644
--- a/Core/Interface/SolidSyslogErrors.h
+++ b/Core/Interface/SolidSyslogErrors.h
@@ -1,3 +1,5 @@
+/** @file
+ *  Error codes and Source identity for the SolidSyslog instance. */
 #ifndef SOLIDSYSLOGERRORS_H
 #define SOLIDSYSLOGERRORS_H
 
diff --git a/Core/Interface/SolidSyslogFile.h b/Core/Interface/SolidSyslogFile.h
index ec63b576..83740e7e 100644
--- a/Core/Interface/SolidSyslogFile.h
+++ b/Core/Interface/SolidSyslogFile.h
@@ -1,3 +1,7 @@
+/** @file
+ *  The file role: byte-file I/O (Open / Close / IsOpen / Read / Write / SeekTo /
+ *  Size / Truncate / Exists / Delete) backing the store. These calls dispatch to
+ *  the injected file's vtable, so behaviour is that file's. */
 #ifndef SOLIDSYSLOGFILE_H
 #define SOLIDSYSLOGFILE_H
 
diff --git a/Core/Interface/SolidSyslogFileBlockDevice.h b/Core/Interface/SolidSyslogFileBlockDevice.h
index f3d08474..b6faa5a8 100644
--- a/Core/Interface/SolidSyslogFileBlockDevice.h
+++ b/Core/Interface/SolidSyslogFileBlockDevice.h
@@ -1,3 +1,17 @@
+/** @file
+ *  A BlockDevice that maps each block to its own file, named by a caller-given
+ *  prefix plus a two-digit block index and ".log" (block 0 is "<prefix>00.log").
+ *  The two-digit sequence caps the device at 100 blocks: an index above 99 is
+ *  rejected, which also stops a wide index being narrowed and aliasing an
+ *  existing block.
+ *
+ *  It caches a single open file handle and re-points it only when the addressed
+ *  block changes, so it upholds the one-open-handle-per-path invariant the
+ *  storage layer relies on and never leaves two handles racing on the same file.
+ *  Acquire opens (creating if needed) and truncates a block for fresh writes;
+ *  Append writes at end-of-file, WriteAt/Read seek to an explicit offset, and
+ *  Dispose deletes the block's file. GetBlockSize reports the configured
+ *  per-block capacity that a BlockStore reads once at construction. */
 #ifndef SOLIDSYSLOGFILEBLOCKDEVICE_H
 #define SOLIDSYSLOGFILEBLOCKDEVICE_H
 
diff --git a/Core/Interface/SolidSyslogFileBlockDeviceErrors.h b/Core/Interface/SolidSyslogFileBlockDeviceErrors.h
index 54294e8c..1767a691 100644
--- a/Core/Interface/SolidSyslogFileBlockDeviceErrors.h
+++ b/Core/Interface/SolidSyslogFileBlockDeviceErrors.h
@@ -1,3 +1,5 @@
+/** @file
+ *  Error codes and Source identity for the FileBlockDevice. */
 #ifndef SOLIDSYSLOGFILEBLOCKDEVICEERRORS_H
 #define SOLIDSYSLOGFILEBLOCKDEVICEERRORS_H
 
diff --git a/Core/Interface/SolidSyslogFileDefinition.h b/Core/Interface/SolidSyslogFileDefinition.h
index 31504837..d37db017 100644
--- a/Core/Interface/SolidSyslogFileDefinition.h
+++ b/Core/Interface/SolidSyslogFileDefinition.h
@@ -1,3 +1,7 @@
+/** @file
+ *  The File vtable (Open / Close / IsOpen / Read / Write / SeekTo / Size /
+ *  Truncate / Exists / Delete) — the contract a porter fills in (the File
+ *  extension point). */
 #ifndef SOLIDSYSLOGFILEDEFINITION_H
 #define SOLIDSYSLOGFILEDEFINITION_H
 
diff --git a/Core/Interface/SolidSyslogHeaderField.h b/Core/Interface/SolidSyslogHeaderField.h
index 09706ef7..cb9963db 100644
--- a/Core/Interface/SolidSyslogHeaderField.h
+++ b/Core/Interface/SolidSyslogHeaderField.h
@@ -1,3 +1,6 @@
+/** @file
+ *  The value sink a callback writes an RFC 5424 header field (HOSTNAME /
+ *  APP-NAME / PROCID) into; the sink owns the charset and the field width. */
 #ifndef SOLIDSYSLOGHEADERFIELD_H
 #define SOLIDSYSLOGHEADERFIELD_H
 
diff --git a/Core/Interface/SolidSyslogHeaderFieldFunction.h b/Core/Interface/SolidSyslogHeaderFieldFunction.h
index a4a2f33c..f05adc69 100644
--- a/Core/Interface/SolidSyslogHeaderFieldFunction.h
+++ b/Core/Interface/SolidSyslogHeaderFieldFunction.h
@@ -1,3 +1,6 @@
+/** @file
+ *  The header-field callback typedef the integrator supplies to
+ *  SolidSyslogConfig for HOSTNAME / APP-NAME / PROCID. */
 #ifndef SOLIDSYSLOGHEADERFIELDFUNCTION_H
 #define SOLIDSYSLOGHEADERFIELDFUNCTION_H
 
diff --git a/Core/Interface/SolidSyslogKeyFunction.h b/Core/Interface/SolidSyslogKeyFunction.h
index c34a85a6..42ff9a95 100644
--- a/Core/Interface/SolidSyslogKeyFunction.h
+++ b/Core/Interface/SolidSyslogKeyFunction.h
@@ -1,3 +1,6 @@
+/** @file
+ *  The on-demand secret-key callback typedef the integrator supplies to a keyed
+ *  SecurityPolicy, so the key never lives on the policy instance. */
 #ifndef SOLIDSYSLOGKEYFUNCTION_H
 #define SOLIDSYSLOGKEYFUNCTION_H
 
diff --git a/Core/Interface/SolidSyslogMetaSd.h b/Core/Interface/SolidSyslogMetaSd.h
index 9f11de0f..979f2194 100644
--- a/Core/Interface/SolidSyslogMetaSd.h
+++ b/Core/Interface/SolidSyslogMetaSd.h
@@ -1,3 +1,10 @@
+/** @file
+ *  A StructuredData source for the RFC 5424 §7.3 "meta" SD-ELEMENT (IANA SD-ID,
+ *  so no enterprise-number suffix), emitted on every message the owning logger
+ *  formats. It always carries sequenceId, taken from one Increment of the
+ *  injected AtomicCounter per message, and optionally sysUpTime and language.
+ *  The two optional PARAMs are independently omitted when their config member is
+ *  NULL, so a bare meta element is just [meta sequenceId="..."]. */
 #ifndef SOLIDSYSLOGMETASD_H
 #define SOLIDSYSLOGMETASD_H
 
diff --git a/Core/Interface/SolidSyslogMetaSdErrors.h b/Core/Interface/SolidSyslogMetaSdErrors.h
index aefab2cb..5e3d9312 100644
--- a/Core/Interface/SolidSyslogMetaSdErrors.h
+++ b/Core/Interface/SolidSyslogMetaSdErrors.h
@@ -1,3 +1,5 @@
+/** @file
+ *  Error codes and Source identity for the MetaSd. */
 #ifndef SOLIDSYSLOGMETASDERRORS_H
 #define SOLIDSYSLOGMETASDERRORS_H
 
diff --git a/Core/Interface/SolidSyslogMutex.h b/Core/Interface/SolidSyslogMutex.h
index 66ceab13..f251bb64 100644
--- a/Core/Interface/SolidSyslogMutex.h
+++ b/Core/Interface/SolidSyslogMutex.h
@@ -1,3 +1,7 @@
+/** @file
+ *  The mutex role: mutual exclusion (Lock / Unlock) around buffer and pool
+ *  critical sections. These calls dispatch to the injected mutex's vtable, so
+ *  behaviour — including whether Lock blocks — is that mutex's. */
 #ifndef SOLIDSYSLOGMUTEX_H
 #define SOLIDSYSLOGMUTEX_H
 
diff --git a/Core/Interface/SolidSyslogMutexDefinition.h b/Core/Interface/SolidSyslogMutexDefinition.h
index c8c46ddf..5213db39 100644
--- a/Core/Interface/SolidSyslogMutexDefinition.h
+++ b/Core/Interface/SolidSyslogMutexDefinition.h
@@ -1,3 +1,6 @@
+/** @file
+ *  The Mutex vtable (Lock / Unlock) — the contract an implementor fills in (the
+ *  Mutex extension point). */
 #ifndef SOLIDSYSLOGMUTEXDEFINITION_H
 #define SOLIDSYSLOGMUTEXDEFINITION_H
 
diff --git a/Core/Interface/SolidSyslogNullAtomicCounter.h b/Core/Interface/SolidSyslogNullAtomicCounter.h
index b714f5a6..72f96320 100644
--- a/Core/Interface/SolidSyslogNullAtomicCounter.h
+++ b/Core/Interface/SolidSyslogNullAtomicCounter.h
@@ -1,3 +1,6 @@
+/** @file
+ *  The no-op AtomicCounter Null object: Increment returns 1U unconditionally, the safest
+ *  value when a real counter is unavailable (RFC 5424 §7.3.1 forbids a sequenceId of 0). */
 #ifndef SOLIDSYSLOGNULLATOMICCOUNTER_H
 #define SOLIDSYSLOGNULLATOMICCOUNTER_H
 
diff --git a/Core/Interface/SolidSyslogNullBlockDevice.h b/Core/Interface/SolidSyslogNullBlockDevice.h
index 3ab72d59..dcbe8541 100644
--- a/Core/Interface/SolidSyslogNullBlockDevice.h
+++ b/Core/Interface/SolidSyslogNullBlockDevice.h
@@ -1,3 +1,7 @@
+/** @file
+ *  The no-op BlockDevice Null object: every method reports a device that does not exist —
+ *  Acquire, Dispose, Exists, Read, Append and WriteAt return false, Size and GetBlockSize
+ *  return 0. */
 #ifndef SOLIDSYSLOGNULLBLOCKDEVICE_H
 #define SOLIDSYSLOGNULLBLOCKDEVICE_H
 
diff --git a/Core/Interface/SolidSyslogNullBuffer.h b/Core/Interface/SolidSyslogNullBuffer.h
index 9b31e296..79692e63 100644
--- a/Core/Interface/SolidSyslogNullBuffer.h
+++ b/Core/Interface/SolidSyslogNullBuffer.h
@@ -1,3 +1,6 @@
+/** @file
+ *  The no-op Buffer Null object: Write swallows the record, Read returns false (nothing to
+ *  deliver) so the Service algorithm sees an empty buffer and stops draining. */
 #ifndef SOLIDSYSLOGNULLBUFFER_H
 #define SOLIDSYSLOGNULLBUFFER_H
 
diff --git a/Core/Interface/SolidSyslogNullDatagram.h b/Core/Interface/SolidSyslogNullDatagram.h
index 0729d3d9..a7c35029 100644
--- a/Core/Interface/SolidSyslogNullDatagram.h
+++ b/Core/Interface/SolidSyslogNullDatagram.h
@@ -1,3 +1,7 @@
+/** @file
+ *  The no-op Datagram Null object: SendTo returns SENT (drops the datagram on the floor so
+ *  the Store does not fill with undeliverables), MaxPayload returns the IPv6-safe default,
+ *  Open and Close are no-ops. */
 #ifndef SOLIDSYSLOGNULLDATAGRAM_H
 #define SOLIDSYSLOGNULLDATAGRAM_H
 
diff --git a/Core/Interface/SolidSyslogNullFile.h b/Core/Interface/SolidSyslogNullFile.h
index c5954ad1..8a47528b 100644
--- a/Core/Interface/SolidSyslogNullFile.h
+++ b/Core/Interface/SolidSyslogNullFile.h
@@ -1,3 +1,7 @@
+/** @file
+ *  The no-op File Null object: Open, IsOpen, Read and Exists return false (consumers take
+ *  their error path), Write and Delete return true (success reported vacuously), SeekTo,
+ *  Truncate and Close are no-ops, Size returns 0. */
 #ifndef SOLIDSYSLOGNULLFILE_H
 #define SOLIDSYSLOGNULLFILE_H
 
diff --git a/Core/Interface/SolidSyslogNullMutex.h b/Core/Interface/SolidSyslogNullMutex.h
index 360758f7..5ea85f75 100644
--- a/Core/Interface/SolidSyslogNullMutex.h
+++ b/Core/Interface/SolidSyslogNullMutex.h
@@ -1,3 +1,6 @@
+/** @file
+ *  The no-op Mutex Null object: Lock and Unlock are no-ops, giving unsynchronised access
+ *  for single-task targets that need no mutual exclusion. */
 #ifndef SOLIDSYSLOGNULLMUTEX_H
 #define SOLIDSYSLOGNULLMUTEX_H
 
diff --git a/Core/Interface/SolidSyslogNullResolver.h b/Core/Interface/SolidSyslogNullResolver.h
index fe538111..8d036455 100644
--- a/Core/Interface/SolidSyslogNullResolver.h
+++ b/Core/Interface/SolidSyslogNullResolver.h
@@ -1,3 +1,6 @@
+/** @file
+ *  The no-op Resolver Null object: Resolve returns false (could not resolve) so the
+ *  caller's existing unresolved-host error path runs naturally. */
 #ifndef SOLIDSYSLOGNULLRESOLVER_H
 #define SOLIDSYSLOGNULLRESOLVER_H
 
diff --git a/Core/Interface/SolidSyslogNullSd.h b/Core/Interface/SolidSyslogNullSd.h
index 6f40a2fc..dc57e1d8 100644
--- a/Core/Interface/SolidSyslogNullSd.h
+++ b/Core/Interface/SolidSyslogNullSd.h
@@ -1,3 +1,6 @@
+/** @file
+ *  The no-op Structured Data Null object: Format writes nothing, so this SD slot
+ *  contributes no SD-ELEMENT to the message. */
 #ifndef SOLIDSYSLOGNULLSD_H
 #define SOLIDSYSLOGNULLSD_H
 
diff --git a/Core/Interface/SolidSyslogNullSecurityPolicy.h b/Core/Interface/SolidSyslogNullSecurityPolicy.h
index ded73623..a3e498a0 100644
--- a/Core/Interface/SolidSyslogNullSecurityPolicy.h
+++ b/Core/Interface/SolidSyslogNullSecurityPolicy.h
@@ -1,3 +1,6 @@
+/** @file
+ *  The no-op SecurityPolicy Null object: pass-through integrity — Seal and Open both return
+ *  true without touching the record, adding no integrity data and accepting every record. */
 #ifndef SOLIDSYSLOGNULLSECURITYPOLICY_H
 #define SOLIDSYSLOGNULLSECURITYPOLICY_H
 
diff --git a/Core/Interface/SolidSyslogNullSender.h b/Core/Interface/SolidSyslogNullSender.h
index 5172dcf7..fd93e881 100644
--- a/Core/Interface/SolidSyslogNullSender.h
+++ b/Core/Interface/SolidSyslogNullSender.h
@@ -1,3 +1,6 @@
+/** @file
+ *  The no-op Sender Null object: Send returns true (drops the record on the floor so the
+ *  Store does not fill with undeliverables), Disconnect is a no-op. */
 #ifndef SOLIDSYSLOGNULLSENDER_H
 #define SOLIDSYSLOGNULLSENDER_H
 
diff --git a/Core/Interface/SolidSyslogNullStore.h b/Core/Interface/SolidSyslogNullStore.h
index e3ad48be..5ecc0450 100644
--- a/Core/Interface/SolidSyslogNullStore.h
+++ b/Core/Interface/SolidSyslogNullStore.h
@@ -1,3 +1,7 @@
+/** @file
+ *  The no-op Store Null object (no store-and-forward): Write returns false and IsTransient
+ *  returns true, so the Service algorithm falls through to a direct send instead of
+ *  buffering. ReadNextUnsent and HasUnsent report empty, IsHalted reports false. */
 #ifndef SOLIDSYSLOGNULLSTORE_H
 #define SOLIDSYSLOGNULLSTORE_H
 
diff --git a/Core/Interface/SolidSyslogNullStream.h b/Core/Interface/SolidSyslogNullStream.h
index 142b1264..4482d91a 100644
--- a/Core/Interface/SolidSyslogNullStream.h
+++ b/Core/Interface/SolidSyslogNullStream.h
@@ -1,3 +1,7 @@
+/** @file
+ *  The no-op Stream Null object: Send returns true (drops the bytes on the floor so the
+ *  Store does not fill with undeliverables), Read returns 0 (would-block, so the caller
+ *  does not tear the connection down), Open and Close are no-ops. */
 #ifndef SOLIDSYSLOGNULLSTREAM_H
 #define SOLIDSYSLOGNULLSTREAM_H
 
diff --git a/Core/Interface/SolidSyslogOriginSd.h b/Core/Interface/SolidSyslogOriginSd.h
index 21239461..486c183e 100644
--- a/Core/Interface/SolidSyslogOriginSd.h
+++ b/Core/Interface/SolidSyslogOriginSd.h
@@ -1,3 +1,12 @@
+/** @file
+ *  A StructuredData source for the RFC 5424 §7.2 "origin" SD-ELEMENT (IANA
+ *  SD-ID, so no enterprise-number suffix), emitted on every message the owning
+ *  logger formats. It can carry software, swVersion, enterpriseId, and any
+ *  number of repeated ip PARAMs. Every field is independently optional: a NULL
+ *  string omits its PARAM, and the ip PARAMs appear only when both GetIpCount
+ *  and GetIpAt are supplied (GetIpAt is then called once per index). The config
+ *  strings are borrowed, not copied, and read at Format time — they must outlive
+ *  the created SD. */
 #ifndef SOLIDSYSLOGORIGINSD_H
 #define SOLIDSYSLOGORIGINSD_H
 
diff --git a/Core/Interface/SolidSyslogOriginSdErrors.h b/Core/Interface/SolidSyslogOriginSdErrors.h
index 84c71045..4f6ae52a 100644
--- a/Core/Interface/SolidSyslogOriginSdErrors.h
+++ b/Core/Interface/SolidSyslogOriginSdErrors.h
@@ -1,3 +1,5 @@
+/** @file
+ *  Error codes and Source identity for the OriginSd. */
 #ifndef SOLIDSYSLOGORIGINSDERRORS_H
 #define SOLIDSYSLOGORIGINSDERRORS_H
 
diff --git a/Core/Interface/SolidSyslogPassthroughBuffer.h b/Core/Interface/SolidSyslogPassthroughBuffer.h
index 18813e6b..4d3cc1fc 100644
--- a/Core/Interface/SolidSyslogPassthroughBuffer.h
+++ b/Core/Interface/SolidSyslogPassthroughBuffer.h
@@ -1,3 +1,10 @@
+/** @file
+ *  The no-queue Buffer. Write forwards the record straight to the injected
+ *  sender inline, so SolidSyslog_Log blocks on the send and returns only once it
+ *  completes; Read always reports empty because nothing is ever queued, so
+ *  Service has nothing to drain. This is the simplest wiring for a single-task
+ *  setup with no store-and-forward — no ring, no mutex, no background drain. The
+ *  cost is that a slow or blocking sender stalls the logging thread. */
 #ifndef SOLIDSYSLOGPASSTHROUGHBUFFER_H
 #define SOLIDSYSLOGPASSTHROUGHBUFFER_H
 
diff --git a/Core/Interface/SolidSyslogPassthroughBufferErrors.h b/Core/Interface/SolidSyslogPassthroughBufferErrors.h
index 805cf805..edc1b733 100644
--- a/Core/Interface/SolidSyslogPassthroughBufferErrors.h
+++ b/Core/Interface/SolidSyslogPassthroughBufferErrors.h
@@ -1,3 +1,5 @@
+/** @file
+ *  Error codes and Source identity for the PassthroughBuffer. */
 #ifndef SOLIDSYSLOGPASSTHROUGHBUFFERERRORS_H
 #define SOLIDSYSLOGPASSTHROUGHBUFFERERRORS_H
 
diff --git a/Core/Interface/SolidSyslogPrival.h b/Core/Interface/SolidSyslogPrival.h
index 5b6e451e..e9ce0591 100644
--- a/Core/Interface/SolidSyslogPrival.h
+++ b/Core/Interface/SolidSyslogPrival.h
@@ -1,3 +1,5 @@
+/** @file
+ *  The RFC 5424 facility and severity enums that compose a message's PRIVAL. */
 #ifndef SOLIDSYSLOGPRIVAL_H
 #define SOLIDSYSLOGPRIVAL_H
 
diff --git a/Core/Interface/SolidSyslogResolver.h b/Core/Interface/SolidSyslogResolver.h
index 4ce24a58..2b309a48 100644
--- a/Core/Interface/SolidSyslogResolver.h
+++ b/Core/Interface/SolidSyslogResolver.h
@@ -1,3 +1,8 @@
+/** @file
+ *  The resolver role: turn a host/port into a destination address (Resolve) for
+ *  a later Datagram or Stream to send to. This call dispatches to the injected
+ *  resolver's vtable, so behaviour — DNS lookup, numeric parse, or a pinned
+ *  fixed destination, and whether it blocks — is that resolver's. */
 #ifndef SOLIDSYSLOGRESOLVER_H
 #define SOLIDSYSLOGRESOLVER_H
 
diff --git a/Core/Interface/SolidSyslogResolverCategories.h b/Core/Interface/SolidSyslogResolverCategories.h
index 5ceba9fc..1b257330 100644
--- a/Core/Interface/SolidSyslogResolverCategories.h
+++ b/Core/Interface/SolidSyslogResolverCategories.h
@@ -1,3 +1,6 @@
+/** @file
+ *  Portable category constants (uint16_t macros) for the Resolver role:
+ *  SOLIDSYSLOG_CAT_RESOLVER_RESOLVE_FAILED. */
 #ifndef SOLIDSYSLOGRESOLVERCATEGORIES_H
 #define SOLIDSYSLOGRESOLVERCATEGORIES_H
 
diff --git a/Core/Interface/SolidSyslogResolverDefinition.h b/Core/Interface/SolidSyslogResolverDefinition.h
index 0ea3a347..5f65d867 100644
--- a/Core/Interface/SolidSyslogResolverDefinition.h
+++ b/Core/Interface/SolidSyslogResolverDefinition.h
@@ -1,3 +1,6 @@
+/** @file
+ *  The Resolver vtable (Resolve) — the host-to-address contract an implementor
+ *  fills in (the Resolver extension point). */
 #ifndef SOLIDSYSLOGRESOLVERDEFINITION_H
 #define SOLIDSYSLOGRESOLVERDEFINITION_H
 
diff --git a/Core/Interface/SolidSyslogSdElement.h b/Core/Interface/SolidSyslogSdElement.h
index 266a7cf8..4ec40b2f 100644
--- a/Core/Interface/SolidSyslogSdElement.h
+++ b/Core/Interface/SolidSyslogSdElement.h
@@ -1,3 +1,7 @@
+/** @file
+ *  The SD authoring API for one [SD-ID PARAM="value"...] element: _Begin /
+ *  _Param / _End, which own the brackets and SD-NAME charset so the author
+ *  writes only names and values. */
 #ifndef SOLIDSYSLOGSDELEMENT_H
 #define SOLIDSYSLOGSDELEMENT_H
 
diff --git a/Core/Interface/SolidSyslogSdValue.h b/Core/Interface/SolidSyslogSdValue.h
index 6e4b7b55..c4e0d32c 100644
--- a/Core/Interface/SolidSyslogSdValue.h
+++ b/Core/Interface/SolidSyslogSdValue.h
@@ -1,3 +1,7 @@
+/** @file
+ *  The per-param value sink of the SD authoring API: streams a PARAM value with
+ *  RFC 5424 escaping applied by the library, so an author cannot break SD
+ *  framing. */
 #ifndef SOLIDSYSLOGSDVALUE_H
 #define SOLIDSYSLOGSDVALUE_H
 
diff --git a/Core/Interface/SolidSyslogSdValueFunction.h b/Core/Interface/SolidSyslogSdValueFunction.h
index 889fddf1..9839f22d 100644
--- a/Core/Interface/SolidSyslogSdValueFunction.h
+++ b/Core/Interface/SolidSyslogSdValueFunction.h
@@ -1,3 +1,6 @@
+/** @file
+ *  The SD-value callback typedef the integrator supplies for dynamic PARAM
+ *  values (e.g. MetaSd language, OriginSd fields). */
 #ifndef SOLIDSYSLOGSDVALUEFUNCTION_H
 #define SOLIDSYSLOGSDVALUEFUNCTION_H
 
diff --git a/Core/Interface/SolidSyslogSecurityPolicyCategories.h b/Core/Interface/SolidSyslogSecurityPolicyCategories.h
index c9a1a3d1..435dacd9 100644
--- a/Core/Interface/SolidSyslogSecurityPolicyCategories.h
+++ b/Core/Interface/SolidSyslogSecurityPolicyCategories.h
@@ -1,3 +1,6 @@
+/** @file
+ *  Portable category constants (uint16_t macros) for the SecurityPolicy role:
+ *  SOLIDSYSLOG_CAT_SECURITYPOLICY_KEY_UNAVAILABLE / _SEAL_FAILED / _OPEN_FAILED. */
 #ifndef SOLIDSYSLOGSECURITYPOLICYCATEGORIES_H
 #define SOLIDSYSLOGSECURITYPOLICYCATEGORIES_H
 
diff --git a/Core/Interface/SolidSyslogSecurityPolicyDefinition.h b/Core/Interface/SolidSyslogSecurityPolicyDefinition.h
index 544c1cd4..1cce1159 100644
--- a/Core/Interface/SolidSyslogSecurityPolicyDefinition.h
+++ b/Core/Interface/SolidSyslogSecurityPolicyDefinition.h
@@ -1,3 +1,9 @@
+/** @file
+ *  The SecurityPolicy vtable (SealRecord / OpenRecord) — the at-rest
+ *  integrity/confidentiality contract an implementor fills in (the SecurityPolicy
+ *  extension point). SealRecord authenticates (AEAD policies also encrypt) and
+ *  writes a trailer on the way in; OpenRecord verifies (and decrypts) on replay,
+ *  failing closed so a tampered or unkeyed record is dropped rather than replayed. */
 #ifndef SOLIDSYSLOGSECURITYPOLICYDEFINITION_H
 #define SOLIDSYSLOGSECURITYPOLICYDEFINITION_H
 
diff --git a/Core/Interface/SolidSyslogSender.h b/Core/Interface/SolidSyslogSender.h
index 06d7af31..833a7dc5 100644
--- a/Core/Interface/SolidSyslogSender.h
+++ b/Core/Interface/SolidSyslogSender.h
@@ -1,3 +1,7 @@
+/** @file
+ *  The sender role: deliver a framed message (Send) / drop the connection
+ *  (Disconnect). These calls dispatch to the injected sender's vtable, so
+ *  behaviour — transport, framing, connect-on-first-use — is that sender's. */
 #ifndef SOLIDSYSLOGSENDER_H
 #define SOLIDSYSLOGSENDER_H
 
diff --git a/Core/Interface/SolidSyslogSenderCategories.h b/Core/Interface/SolidSyslogSenderCategories.h
index 54bea2ae..224179fc 100644
--- a/Core/Interface/SolidSyslogSenderCategories.h
+++ b/Core/Interface/SolidSyslogSenderCategories.h
@@ -1,3 +1,6 @@
+/** @file
+ *  Portable category constants (uint16_t macros) for the Sender role:
+ *  SOLIDSYSLOG_CAT_SENDER_DELIVERY_FAILED / _DELIVERY_RESTORED. */
 #ifndef SOLIDSYSLOGSENDERCATEGORIES_H
 #define SOLIDSYSLOGSENDERCATEGORIES_H
 
diff --git a/Core/Interface/SolidSyslogSenderDefinition.h b/Core/Interface/SolidSyslogSenderDefinition.h
index 82c3e7b5..7ed74e85 100644
--- a/Core/Interface/SolidSyslogSenderDefinition.h
+++ b/Core/Interface/SolidSyslogSenderDefinition.h
@@ -1,3 +1,6 @@
+/** @file
+ *  The Sender vtable (Send / Disconnect) — the contract an implementor fills in
+ *  (the Sender extension point). */
 #ifndef SOLIDSYSLOGSENDERDEFINITION_H
 #define SOLIDSYSLOGSENDERDEFINITION_H
 
diff --git a/Core/Interface/SolidSyslogServiceStatus.h b/Core/Interface/SolidSyslogServiceStatus.h
index f5418ba0..42b8e387 100644
--- a/Core/Interface/SolidSyslogServiceStatus.h
+++ b/Core/Interface/SolidSyslogServiceStatus.h
@@ -1,3 +1,6 @@
+/** @file
+ *  The advisory servicing-hint enum SolidSyslog_Service returns to drive a
+ *  host loop (idle / ready / blocked / halted). */
 #ifndef SOLIDSYSLOGSERVICESTATUS_H
 #define SOLIDSYSLOGSERVICESTATUS_H
 
diff --git a/Core/Interface/SolidSyslogSleep.h b/Core/Interface/SolidSyslogSleep.h
index 8e7224d6..bb0903b9 100644
--- a/Core/Interface/SolidSyslogSleep.h
+++ b/Core/Interface/SolidSyslogSleep.h
@@ -1,3 +1,6 @@
+/** @file
+ *  The millisecond-sleep callback typedef the integrator injects to drive the
+ *  bounded wait-and-retry loops without busy-spinning. */
 #ifndef SOLIDSYSLOGSLEEP_H
 #define SOLIDSYSLOGSLEEP_H
 
diff --git a/Core/Interface/SolidSyslogStore.h b/Core/Interface/SolidSyslogStore.h
index 3bb52c01..eabf4d99 100644
--- a/Core/Interface/SolidSyslogStore.h
+++ b/Core/Interface/SolidSyslogStore.h
@@ -1,3 +1,9 @@
+/** @file
+ *  The store role: retain unsent records (Write) and replay them in order via a
+ *  read cursor (ReadNextUnsent / MarkSent), so a send failure never drops a
+ *  stored record — it stays for retry. These calls dispatch to the injected
+ *  store's vtable, so behaviour — capacity, discard policy, durability — is
+ *  that store's. */
 #ifndef SOLIDSYSLOGSTORE_H
 #define SOLIDSYSLOGSTORE_H
 
diff --git a/Core/Interface/SolidSyslogStoreDefinition.h b/Core/Interface/SolidSyslogStoreDefinition.h
index d2be8fc1..3fccd19c 100644
--- a/Core/Interface/SolidSyslogStoreDefinition.h
+++ b/Core/Interface/SolidSyslogStoreDefinition.h
@@ -1,3 +1,7 @@
+/** @file
+ *  The Store vtable (Write / ReadNextUnsent / MarkSent / HasUnsent / IsHalted /
+ *  GetTotalBytes / GetUsedBytes / IsTransient) — the store-and-forward contract
+ *  an implementor fills in (the Store extension point). */
 #ifndef SOLIDSYSLOGSTOREDEFINITION_H
 #define SOLIDSYSLOGSTOREDEFINITION_H
 
diff --git a/Core/Interface/SolidSyslogStream.h b/Core/Interface/SolidSyslogStream.h
index cb055515..bf36a2eb 100644
--- a/Core/Interface/SolidSyslogStream.h
+++ b/Core/Interface/SolidSyslogStream.h
@@ -1,3 +1,8 @@
+/** @file
+ *  The stream role: connection-oriented byte transport (Open / Send / Read /
+ *  Close) for octet-framed delivery. These calls dispatch to the injected
+ *  stream's vtable, so behaviour — connect bound, blocking discipline, any TLS
+ *  layering — is that stream's. */
 #ifndef SOLIDSYSLOGSTREAM_H
 #define SOLIDSYSLOGSTREAM_H
 
diff --git a/Core/Interface/SolidSyslogStreamDefinition.h b/Core/Interface/SolidSyslogStreamDefinition.h
index d3156748..5ae26581 100644
--- a/Core/Interface/SolidSyslogStreamDefinition.h
+++ b/Core/Interface/SolidSyslogStreamDefinition.h
@@ -1,3 +1,7 @@
+/** @file
+ *  The Stream vtable (Open / Send / Read / Close) — the byte-stream (TCP, TLS
+ *  over TCP) transport contract an implementor fills in (the Stream extension
+ *  point). */
 #ifndef SOLIDSYSLOGSTREAMDEFINITION_H
 #define SOLIDSYSLOGSTREAMDEFINITION_H
 
diff --git a/Core/Interface/SolidSyslogStreamSender.h b/Core/Interface/SolidSyslogStreamSender.h
index 5d64fa3f..4c79df81 100644
--- a/Core/Interface/SolidSyslogStreamSender.h
+++ b/Core/Interface/SolidSyslogStreamSender.h
@@ -1,3 +1,14 @@
+/** @file
+ *  A Sender that delivers each message octet-framed (RFC 6587 octet-counting: a
+ *  decimal length, a space, then the message bytes) over any injected Stream —
+ *  plain TCP, TLS, or a caller-supplied byte transport. It resolves the endpoint
+ *  and opens the stream lazily on the first Send, reconnecting when the endpoint
+ *  version changes or after any send failure (a short or failed write closes the
+ *  stream so the next Send reconnects). Repeated delivery failures and the
+ *  recovery after them are reported once each via SolidSyslog_Error
+ *  (DELIVERY_FAILED / DELIVERY_RESTORED), so a flapping link is not a log storm.
+ *  Destroy closes the stream but does not free the injected Resolver, Stream, or
+ *  Address. */
 #ifndef SOLIDSYSLOG_STREAM_SENDER_H
 #define SOLIDSYSLOG_STREAM_SENDER_H
 
diff --git a/Core/Interface/SolidSyslogStreamSenderErrors.h b/Core/Interface/SolidSyslogStreamSenderErrors.h
index 4470ec02..45fb33e7 100644
--- a/Core/Interface/SolidSyslogStreamSenderErrors.h
+++ b/Core/Interface/SolidSyslogStreamSenderErrors.h
@@ -1,3 +1,5 @@
+/** @file
+ *  Error codes and Source identity for the StreamSender. */
 #ifndef SOLIDSYSLOGSTREAMSENDERERRORS_H
 #define SOLIDSYSLOGSTREAMSENDERERRORS_H
 
diff --git a/Core/Interface/SolidSyslogStructuredData.h b/Core/Interface/SolidSyslogStructuredData.h
index 3d67bc19..59c2e978 100644
--- a/Core/Interface/SolidSyslogStructuredData.h
+++ b/Core/Interface/SolidSyslogStructuredData.h
@@ -1,3 +1,7 @@
+/** @file
+ *  The structured-data role: emit one or more RFC 5424 SD-ELEMENTs into a
+ *  message (Format). This call dispatches to the injected SD's vtable, so the
+ *  content — and whether it is stateful — is that SD's. */
 #ifndef SOLIDSYSLOGSTRUCTUREDDATA_H
 #define SOLIDSYSLOGSTRUCTUREDDATA_H
 
diff --git a/Core/Interface/SolidSyslogStructuredDataDefinition.h b/Core/Interface/SolidSyslogStructuredDataDefinition.h
index 4e4ea951..061aee0e 100644
--- a/Core/Interface/SolidSyslogStructuredDataDefinition.h
+++ b/Core/Interface/SolidSyslogStructuredDataDefinition.h
@@ -1,3 +1,6 @@
+/** @file
+ *  The StructuredData vtable (Format) — the SD-source contract an implementor
+ *  fills in (the StructuredData extension point). */
 #ifndef SOLIDSYSLOGSTRUCTUREDDATADEFINITION_H
 #define SOLIDSYSLOGSTRUCTUREDDATADEFINITION_H
 
diff --git a/Core/Interface/SolidSyslogSwitchingSender.h b/Core/Interface/SolidSyslogSwitchingSender.h
index 164c7e9b..c54ba9e6 100644
--- a/Core/Interface/SolidSyslogSwitchingSender.h
+++ b/Core/Interface/SolidSyslogSwitchingSender.h
@@ -1,3 +1,14 @@
+/** @file
+ *  A composite Sender that fronts several inner senders and routes each message
+ *  through the one the Selector picks — the wiring for dual-SIEM fan-out or an
+ *  active/standby failover stack. The Selector is called on every Send and
+ *  returns an index into the Senders array; a value at or beyond SenderCount
+ *  (including any value when the array is empty) routes to the shared
+ *  NullSender, which drops the message so a misconfigured selector never retains
+ *  records in the Store. Switching away from a sender disconnects it, so only
+ *  the currently selected inner sender holds a live connection; the inner
+ *  senders themselves are caller-owned and are not disconnected or freed on
+ *  Destroy. */
 #ifndef SOLIDSYSLOGSWITCHINGSENDER_H
 #define SOLIDSYSLOGSWITCHINGSENDER_H
 
diff --git a/Core/Interface/SolidSyslogSwitchingSenderErrors.h b/Core/Interface/SolidSyslogSwitchingSenderErrors.h
index 5c876c98..32fdd5df 100644
--- a/Core/Interface/SolidSyslogSwitchingSenderErrors.h
+++ b/Core/Interface/SolidSyslogSwitchingSenderErrors.h
@@ -1,3 +1,5 @@
+/** @file
+ *  Error codes and Source identity for the SwitchingSender. */
 #ifndef SOLIDSYSLOGSWITCHINGSENDERERRORS_H
 #define SOLIDSYSLOGSWITCHINGSENDERERRORS_H
 
diff --git a/Core/Interface/SolidSyslogTcpConnectTimeoutFunction.h b/Core/Interface/SolidSyslogTcpConnectTimeoutFunction.h
index e21ffb1f..5769c465 100644
--- a/Core/Interface/SolidSyslogTcpConnectTimeoutFunction.h
+++ b/Core/Interface/SolidSyslogTcpConnectTimeoutFunction.h
@@ -1,3 +1,6 @@
+/** @file
+ *  The callback typedef the integrator installs on a TCP stream config to
+ *  supply the bounded-connect deadline per attempt (runtime-tunable). */
 #ifndef SOLIDSYSLOGTCPCONNECTTIMEOUTFUNCTION_H
 #define SOLIDSYSLOGTCPCONNECTTIMEOUTFUNCTION_H
 
diff --git a/Core/Interface/SolidSyslogTimeQuality.h b/Core/Interface/SolidSyslogTimeQuality.h
index dda3deeb..631dab86 100644
--- a/Core/Interface/SolidSyslogTimeQuality.h
+++ b/Core/Interface/SolidSyslogTimeQuality.h
@@ -1,3 +1,6 @@
+/** @file
+ *  The clock-quality data (tzKnown / isSynced / syncAccuracy) and the callback
+ *  that supplies it, feeding the RFC 5424 "timeQuality" SD-ELEMENT. */
 #ifndef SOLIDSYSLOGTIMEQUALITY_H
 #define SOLIDSYSLOGTIMEQUALITY_H
 
diff --git a/Core/Interface/SolidSyslogTimeQualitySd.h b/Core/Interface/SolidSyslogTimeQualitySd.h
index 43ace683..9fec112e 100644
--- a/Core/Interface/SolidSyslogTimeQualitySd.h
+++ b/Core/Interface/SolidSyslogTimeQualitySd.h
@@ -1,3 +1,10 @@
+/** @file
+ *  A StructuredData source for the RFC 5424 §7.1 "timeQuality" SD-ELEMENT (IANA
+ *  SD-ID, so no enterprise-number suffix), emitted on every message the owning
+ *  logger formats. The getTimeQuality callback is queried once per message; the
+ *  element always carries tzKnown and isSynced (emitted as 0/1), and adds
+ *  syncAccuracy only when the callback supplies a value other than
+ *  SOLIDSYSLOG_SYNC_ACCURACY_OMIT. */
 #ifndef SOLIDSYSLOGTIMEQUALITYSD_H
 #define SOLIDSYSLOGTIMEQUALITYSD_H
 
diff --git a/Core/Interface/SolidSyslogTimeQualitySdErrors.h b/Core/Interface/SolidSyslogTimeQualitySdErrors.h
index e36bd5c1..838ccd9d 100644
--- a/Core/Interface/SolidSyslogTimeQualitySdErrors.h
+++ b/Core/Interface/SolidSyslogTimeQualitySdErrors.h
@@ -1,3 +1,5 @@
+/** @file
+ *  Error codes and Source identity for the TimeQualitySd. */
 #ifndef SOLIDSYSLOGTIMEQUALITYSDERRORS_H
 #define SOLIDSYSLOGTIMEQUALITYSDERRORS_H
 
diff --git a/Core/Interface/SolidSyslogTimestamp.h b/Core/Interface/SolidSyslogTimestamp.h
index 20d1f5f6..e1f83488 100644
--- a/Core/Interface/SolidSyslogTimestamp.h
+++ b/Core/Interface/SolidSyslogTimestamp.h
@@ -1,3 +1,6 @@
+/** @file
+ *  The broken-down timestamp struct and the SolidSyslogClockFunction that fills
+ *  it, supplying the RFC 5424 TIMESTAMP field. */
 #ifndef SOLIDSYSLOGTIMESTAMP_H
 #define SOLIDSYSLOGTIMESTAMP_H
 
diff --git a/Core/Interface/SolidSyslogTlsHandshakeTimeoutFunction.h b/Core/Interface/SolidSyslogTlsHandshakeTimeoutFunction.h
index 059b4923..0e60688c 100644
--- a/Core/Interface/SolidSyslogTlsHandshakeTimeoutFunction.h
+++ b/Core/Interface/SolidSyslogTlsHandshakeTimeoutFunction.h
@@ -1,3 +1,6 @@
+/** @file
+ *  The callback typedef the integrator installs on a TLS stream config to
+ *  supply the bounded-handshake deadline per attempt (runtime-tunable). */
 #ifndef SOLIDSYSLOGTLSHANDSHAKETIMEOUTFUNCTION_H
 #define SOLIDSYSLOGTLSHANDSHAKETIMEOUTFUNCTION_H
 
diff --git a/Core/Interface/SolidSyslogTlsStreamCategories.h b/Core/Interface/SolidSyslogTlsStreamCategories.h
index ac509c6e..c5eda278 100644
--- a/Core/Interface/SolidSyslogTlsStreamCategories.h
+++ b/Core/Interface/SolidSyslogTlsStreamCategories.h
@@ -1,3 +1,6 @@
+/** @file
+ *  Portable category constants (uint16_t macros) for the TLS-stream role:
+ *  SOLIDSYSLOG_CAT_TLSSTREAM_INIT_FAILED / _HANDSHAKE_FAILED. */
 #ifndef SOLIDSYSLOGTLSSTREAMCATEGORIES_H
 #define SOLIDSYSLOGTLSSTREAMCATEGORIES_H
 
diff --git a/Core/Interface/SolidSyslogTransport.h b/Core/Interface/SolidSyslogTransport.h
index 21ff3407..eecf3539 100644
--- a/Core/Interface/SolidSyslogTransport.h
+++ b/Core/Interface/SolidSyslogTransport.h
@@ -1,3 +1,6 @@
+/** @file
+ *  The transport selector enum (UDP / TCP) and the IANA default-port
+ *  convenience constants. */
 #ifndef SOLIDSYSLOGTRANSPORT_H
 #define SOLIDSYSLOGTRANSPORT_H
 
diff --git a/Core/Interface/SolidSyslogTunables.h b/Core/Interface/SolidSyslogTunables.h
index b329b42f..126c6b51 100644
--- a/Core/Interface/SolidSyslogTunables.h
+++ b/Core/Interface/SolidSyslogTunables.h
@@ -1,3 +1,6 @@
+/** @file
+ *  The compile-time tunables umbrella: pulls the optional user override first,
+ *  then SolidSyslogTunablesDefaults.h so unset knobs fall back to defaults. */
 #ifndef SOLIDSYSLOG_TUNABLES_H
 #define SOLIDSYSLOG_TUNABLES_H
 
diff --git a/Core/Interface/SolidSyslogTunablesDefaults.h b/Core/Interface/SolidSyslogTunablesDefaults.h
index a3a088fa..19193876 100644
--- a/Core/Interface/SolidSyslogTunablesDefaults.h
+++ b/Core/Interface/SolidSyslogTunablesDefaults.h
@@ -1,3 +1,7 @@
+/** @file
+ *  The default values for every compile-time tunable — pool sizes, message /
+ *  path / integrity limits, and timeouts — each #ifndef-guarded so a user
+ *  override wins. Reached through the SolidSyslogTunables.h umbrella. */
 #ifndef SOLIDSYSLOG_TUNABLES_DEFAULTS_H
 #define SOLIDSYSLOG_TUNABLES_DEFAULTS_H
 
diff --git a/Core/Interface/SolidSyslogUdpPayload.h b/Core/Interface/SolidSyslogUdpPayload.h
index 3f26e902..571f96d5 100644
--- a/Core/Interface/SolidSyslogUdpPayload.h
+++ b/Core/Interface/SolidSyslogUdpPayload.h
@@ -1,3 +1,7 @@
+/** @file
+ *  UDP payload sizing helpers: the usable payload for a given MTU and the
+ *  UTF-8-safe trim used to fit a message into a datagram without splitting a
+ *  codepoint. */
 #ifndef SOLIDSYSLOGUDPPAYLOAD_H
 #define SOLIDSYSLOGUDPPAYLOAD_H
 
diff --git a/Core/Interface/SolidSyslogUdpSender.h b/Core/Interface/SolidSyslogUdpSender.h
index ae898d21..01e1920a 100644
--- a/Core/Interface/SolidSyslogUdpSender.h
+++ b/Core/Interface/SolidSyslogUdpSender.h
@@ -1,3 +1,15 @@
+/** @file
+ *  A Sender that transmits each message as a single UDP datagram over the
+ *  injected Datagram, resolving the endpoint and opening the socket lazily on
+ *  the first Send and re-resolving when the endpoint version changes. A datagram
+ *  the path reports as oversize is retried once, trimmed to the datagram's
+ *  MaxPayload on a UTF-8 codepoint boundary rather than dropped; an
+ *  untransmittable record (trims to nothing, or still oversize on retry) is
+ *  swallowed as sent so Service does not loop on it. A NULL send buffer is
+ *  reported and rejected without touching delivery health. Repeated delivery
+ *  failures and the recovery after them are reported once each via
+ *  SolidSyslog_Error (DELIVERY_FAILED / DELIVERY_RESTORED). Destroy disconnects
+ *  but does not free the injected Resolver, Datagram, or Address. */
 #ifndef SOLIDSYSLOGUDPSENDER_H
 #define SOLIDSYSLOGUDPSENDER_H
 
diff --git a/Core/Interface/SolidSyslogUdpSenderErrors.h b/Core/Interface/SolidSyslogUdpSenderErrors.h
index 8bde550b..92f0a7a3 100644
--- a/Core/Interface/SolidSyslogUdpSenderErrors.h
+++ b/Core/Interface/SolidSyslogUdpSenderErrors.h
@@ -1,3 +1,5 @@
+/** @file
+ *  Error codes and Source identity for the UdpSender. */
 #ifndef SOLIDSYSLOGUDPSENDERERRORS_H
 #define SOLIDSYSLOGUDPSENDERERRORS_H