Added more usage samples

Author: Developer

samples/ByTech.EmbeddedCommitLog.LedgerSample/AccountSink.cs

@@ -16,10 +16,15 @@ namespace ByTech.EmbeddedCommitLog.LedgerSample;
 /// read-side view rebuilt by replaying a shared, ordered log.
 /// </para>
 /// <para>
-/// <see cref="Record.Header.SeqNo"/> is the record's global position in the pipeline —
+/// <see cref="Statement.SeqNo"/> is the record's global position in the pipeline —
 /// the same sequence number appears in every consumer's view of the log, making it
 /// straightforward to correlate entries across accounts.
 /// </para>
+/// <para>
+/// Pass <paramref name="initialBalance"/> when restarting a pipeline from a previously
+/// saved cursor position. The sink will project from that starting balance, receiving
+/// only the records that were posted after the cursor was last flushed to disk.
+/// </para>
 /// </remarks>
 public sealed class AccountSink : ISink
 {
@@ -31,7 +36,16 @@ public sealed record Statement(ulong SeqNo, LedgerEntry Entry, decimal RunningBa
     private decimal _balance;
 
     /// <summary>Initialises the sink for the given account.</summary>
-    public AccountSink(string accountId) => _accountId = accountId;
+    /// <param name="accountId">Account ID to project (e.g. "ACC-001").</param>
+    /// <param name="initialBalance">
+    /// Starting balance carried forward from a previous pipeline run.
+    /// Defaults to zero for a brand-new account.
+    /// </param>
+    public AccountSink(string accountId, decimal initialBalance = 0m)
+    {
+        _accountId = accountId;
+        _balance = initialBalance;
+    }
 
     /// <summary>Account identifier this sink projects.</summary>
     public string AccountId => _accountId;

samples/ByTech.EmbeddedCommitLog.LedgerSample/AuditSink.cs

@@ -0,0 +1,35 @@
+using ByTech.EmbeddedCommitLog.Consumer;
+using ByTech.EmbeddedCommitLog.Sinks;
+
+namespace ByTech.EmbeddedCommitLog.LedgerSample;
+
+/// <summary>
+/// Push-mode sink that records every entry in the general ledger without filtering.
+/// </summary>
+/// <remarks>
+/// Unlike <see cref="AccountSink"/>, this sink does not filter by account — it
+/// receives the full broadcast and stores every record in arrival order. The result
+/// is an immutable, ordered audit trail of the entire log, identical to what a
+/// human auditor would see when reading the segment files directly.
+/// </remarks>
+public sealed class AuditSink : ISink
+{
+    /// <summary>Immutable snapshot of one audit log entry.</summary>
+    public sealed record Entry(ulong SeqNo, LedgerEntry LedgerEntry);
+
+    private readonly List<Entry> _entries = [];
+
+    /// <summary>All entries received, in delivery order (which matches SeqNo order).</summary>
+    public IReadOnlyList<Entry> Entries => _entries;
+
+    /// <inheritdoc/>
+    public Task WriteAsync(IReadOnlyList<LogRecord> batch, CancellationToken ct)
+    {
+        foreach (LogRecord record in batch)
+        {
+            _entries.Add(new Entry(record.Header.SeqNo, LedgerEntry.Deserialize(record.Payload)));
+        }
+
+        return Task.CompletedTask;
+    }
+}

samples/ByTech.EmbeddedCommitLog.LedgerSample/LedgerEntry.cs

@@ -27,7 +27,12 @@ public sealed record LedgerEntry(
     public byte[] Serialize() =>
         JsonSerializer.SerializeToUtf8Bytes(this, _jsonOptions);
 
-    /// <summary>Deserialises a <see cref="LedgerEntry"/> from a UTF-8 JSON payload byte array.</summary>
-    public static LedgerEntry Deserialize(byte[] payload) =>
+    /// <summary>Deserialises a <see cref="LedgerEntry"/> from a UTF-8 JSON payload.</summary>
+    /// <remarks>
+    /// Accepts <see cref="byte"/>[] (push-mode <c>LogRecord.Payload</c>) and
+    /// <see cref="ReadOnlySpan{T}"/> (pull-mode <c>RecordReadResult.Payload.Span</c>)
+    /// without allocating an intermediate array.
+    /// </remarks>
+    public static LedgerEntry Deserialize(ReadOnlySpan<byte> payload) =>
         JsonSerializer.Deserialize<LedgerEntry>(payload, _jsonOptions)!;
 }