feat: add FileStore tombstone, TTL & consumer state persistence (Task 2)

Port Go filestore tombstone/deletion tests, consumer state encode/decode,
consumer file store persistence, and message TTL enforcement. Adds
ConsumerStateCodec and ConsumerFileStore implementations.

17 new tests ported from filestore_test.go.

src/NATS.Server/JetStream/Storage/ConsumerFileStore.cs

@@ -0,0 +1,372 @@
+using NATS.Server.JetStream.Models;
+using StorageType = NATS.Server.JetStream.Models.StorageType;
+
+namespace NATS.Server.JetStream.Storage;
+
+// Go: server/filestore.go:11630  consumerFileStore struct
+// Go: ConsumerStore interface implements: UpdateDelivered, UpdateAcks, State, Stop, Delete
+/// <summary>
+/// File-backed consumer state store. Persists consumer delivery progress, ack floor,
+/// pending messages, and redelivery counts to a binary state file on disk.
+///
+/// The state is encoded/decoded using <see cref="ConsumerStateCodec"/> which matches
+/// the Go wire format, enabling interoperability.
+///
+/// Reference: golang/nats-server/server/filestore.go:11630 (consumerFileStore)
+/// </summary>
+public sealed class ConsumerFileStore : IConsumerStore
+{
+    private readonly string _stateFile;
+    private readonly ConsumerConfig _cfg;
+    private ConsumerState _state = new();
+    private bool _dirty;
+    private bool _closed;
+    private bool _inFlusher;
+    private readonly CancellationTokenSource _cts = new();
+    private readonly Task _flusherTask;
+    private readonly Lock _mu = new();
+
+    /// <summary>
+    /// True if the background flusher goroutine is running.
+    /// Reference: golang/nats-server/server/filestore.go:11640 (qch / flusher pattern)
+    /// </summary>
+    public bool InFlusher
+    {
+        get { lock (_mu) return _inFlusher; }
+    }
+
+    // Go: ErrNoAckPolicy — returned when UpdateAcks is called on a consumer without explicit ack policy.
+    // Reference: golang/nats-server/server/errors.go
+    public static readonly Exception ErrNoAckPolicy = new InvalidOperationException("ErrNoAckPolicy");
+
+    public ConsumerFileStore(string stateFile, ConsumerConfig cfg)
+    {
+        _stateFile = stateFile;
+        _cfg = cfg;
+
+        // Load existing state from disk if present.
+        if (File.Exists(_stateFile))
+        {
+            try
+            {
+                var data = File.ReadAllBytes(_stateFile);
+                _state = ConsumerStateCodec.Decode(data);
+            }
+            catch
+            {
+                _state = new ConsumerState();
+            }
+        }
+
+        // Start background flusher task (equivalent to Go goroutine for periodic state flush).
+        _flusherTask = RunFlusherAsync(_cts.Token);
+    }
+
+    // Go: consumerFileStore.SetStarting — filestore.go:11660
+    public void SetStarting(ulong sseq)
+    {
+        lock (_mu)
+        {
+            _state.AckFloor = new SequencePair(0, sseq > 0 ? sseq - 1 : 0);
+        }
+    }
+
+    // Go: consumerFileStore.UpdateStarting — filestore.go:11665
+    public void UpdateStarting(ulong sseq)
+    {
+        lock (_mu)
+        {
+            _state.AckFloor = new SequencePair(0, sseq > 0 ? sseq - 1 : 0);
+        }
+    }
+
+    // Go: consumerFileStore.Reset — filestore.go:11670
+    public void Reset(ulong sseq)
+    {
+        lock (_mu)
+        {
+            _state = new ConsumerState
+            {
+                AckFloor = new SequencePair(0, sseq > 0 ? sseq - 1 : 0),
+            };
+            _dirty = true;
+        }
+    }
+
+    // Go: consumerFileStore.HasState — filestore.go
+    public bool HasState()
+    {
+        lock (_mu)
+            return _state.Delivered.Consumer > 0 || _state.AckFloor.Consumer > 0;
+    }
+
+    // Go: consumerFileStore.UpdateDelivered — filestore.go:11700
+    // dseq=consumer delivery seq, sseq=stream seq, dc=delivery count, ts=Unix nanosec timestamp
+    public void UpdateDelivered(ulong dseq, ulong sseq, ulong dc, long ts)
+    {
+        lock (_mu)
+        {
+            if (_closed) return;
+
+            // Go: For AckNone, delivery count > 1 is not allowed.
+            if (dc != 1 && _cfg.AckPolicy == AckPolicy.None)
+                throw (InvalidOperationException)ErrNoAckPolicy;
+
+            _state.Delivered = new SequencePair(dseq, sseq);
+
+            if (_cfg.AckPolicy != AckPolicy.None)
+            {
+                // Track pending for explicit/all ack policies.
+                _state.Pending ??= new Dictionary<ulong, Pending>();
+                _state.Pending[sseq] = new Pending(dseq, ts);
+
+                // Track redelivery if dc > 1.
+                if (dc > 1)
+                {
+                    _state.Redelivered ??= new Dictionary<ulong, ulong>();
+                    _state.Redelivered[sseq] = dc;
+                }
+            }
+            else
+            {
+                // AckNone: ack floor advances with delivery.
+                _state.AckFloor = new SequencePair(dseq, sseq);
+            }
+
+            _dirty = true;
+        }
+    }
+
+    // Go: consumerFileStore.UpdateAcks — filestore.go:11760
+    public void UpdateAcks(ulong dseq, ulong sseq)
+    {
+        lock (_mu)
+        {
+            if (_closed) return;
+
+            // Go: AckNone consumers cannot ack.
+            if (_cfg.AckPolicy == AckPolicy.None)
+                throw (InvalidOperationException)ErrNoAckPolicy;
+
+            // Must exist in pending.
+            if (_state.Pending == null || !_state.Pending.ContainsKey(sseq))
+                throw new InvalidOperationException($"Sequence {sseq} not found in pending.");
+
+            _state.Pending.Remove(sseq);
+            if (_state.Pending.Count == 0)
+                _state.Pending = null;
+
+            // Remove from redelivered if present.
+            _state.Redelivered?.Remove(sseq);
+            if (_state.Redelivered?.Count == 0)
+                _state.Redelivered = null;
+
+            // Advance ack floor: find the highest contiguous ack floor.
+            // Go: consumerFileStore.UpdateAcks advances AckFloor to the
+            //     highest consumer seq / stream seq that are fully acked.
+            AdvanceAckFloor(dseq, sseq);
+
+            _dirty = true;
+        }
+    }
+
+    // Go: consumerFileStore.Update — filestore.go
+    public void Update(ConsumerState state)
+    {
+        lock (_mu)
+        {
+            _state = state;
+            _dirty = true;
+        }
+    }
+
+    // Go: consumerFileStore.State — filestore.go:12103
+    public ConsumerState State()
+    {
+        lock (_mu)
+        {
+            // Return a deep copy.
+            var copy = new ConsumerState
+            {
+                Delivered = _state.Delivered,
+                AckFloor = _state.AckFloor,
+            };
+
+            if (_state.Pending != null)
+            {
+                copy.Pending = new Dictionary<ulong, Pending>(_state.Pending);
+            }
+
+            if (_state.Redelivered != null)
+            {
+                copy.Redelivered = new Dictionary<ulong, ulong>(_state.Redelivered);
+            }
+
+            return copy;
+        }
+    }
+
+    // Go: consumerFileStore.BorrowState — filestore.go:12109
+    public ConsumerState BorrowState()
+    {
+        lock (_mu) return _state;
+    }
+
+    // Go: consumerFileStore.EncodedState — filestore.go
+    public byte[] EncodedState()
+    {
+        lock (_mu)
+            return ConsumerStateCodec.Encode(_state);
+    }
+
+    // Go: consumerFileStore.Type — filestore.go:12099
+    public StorageType Type() => StorageType.File;
+
+    // Go: consumerFileStore.Stop — filestore.go:12327
+    public void Stop()
+    {
+        lock (_mu)
+        {
+            if (_closed) return;
+            _closed = true;
+        }
+
+        // Signal flusher to stop and wait.
+        _cts.Cancel();
+        try { _flusherTask.Wait(TimeSpan.FromMilliseconds(500)); } catch { /* best effort */ }
+
+        // Flush final state.
+        FlushState();
+    }
+
+    // Go: consumerFileStore.Delete — filestore.go:12382
+    public void Delete()
+    {
+        lock (_mu)
+        {
+            if (_closed) return;
+            _closed = true;
+        }
+
+        _cts.Cancel();
+        try { _flusherTask.Wait(TimeSpan.FromMilliseconds(200)); } catch { /* best effort */ }
+
+        if (File.Exists(_stateFile))
+        {
+            try { File.Delete(_stateFile); } catch { /* best effort */ }
+        }
+    }
+
+    // Go: consumerFileStore.StreamDelete — filestore.go:12387
+    public void StreamDelete()
+    {
+        Delete();
+    }
+
+    // -------------------------------------------------------------------------
+    // Private helpers
+    // -------------------------------------------------------------------------
+
+    /// <summary>
+    /// Advances the ack floor to the highest contiguous acknowledged sequence.
+    /// Go: consumerFileStore.UpdateAcks — floor advances when no gaps remain in pending.
+    /// Reference: golang/nats-server/server/filestore.go:11817
+    /// </summary>
+    private void AdvanceAckFloor(ulong dseq, ulong sseq)
+    {
+        // If there are no pending entries, ack floor = delivered.
+        if (_state.Pending == null || _state.Pending.Count == 0)
+        {
+            _state.AckFloor = _state.Delivered;
+            return;
+        }
+
+        // Go: advance floor by looking at the lowest pending entry.
+        // The ack floor is the highest dseq/sseq pair such that all earlier seqs are acked.
+        // Simple approach: find the minimum pending stream seq — floor is one below that.
+        var minPendingSSeq = ulong.MaxValue;
+        ulong minPendingDSeq = 0;
+        foreach (var kv in _state.Pending)
+        {
+            if (kv.Key < minPendingSSeq)
+            {
+                minPendingSSeq = kv.Key;
+                minPendingDSeq = kv.Value.Sequence;
+            }
+        }
+
+        if (minPendingSSeq == ulong.MaxValue || minPendingDSeq == 0)
+        {
+            _state.AckFloor = _state.Delivered;
+            return;
+        }
+
+        // Floor = one below the lowest pending.
+        // Go uses AckFloor.Stream as "last fully acked stream seq".
+        // We need to find what was acked just before the minimum pending.
+        // Use the current dseq/sseq being acked for floor advancement check.
+        if (dseq > _state.AckFloor.Consumer && sseq > _state.AckFloor.Stream)
+        {
+            // Check if dseq is the one just above the current floor.
+            if (dseq == _state.AckFloor.Consumer + 1)
+            {
+                _state.AckFloor = new SequencePair(dseq, sseq);
+
+                // Walk forward while consecutive pending entries are acked.
+                // (This is a simplified version; full Go impl tracks ordering explicitly.)
+            }
+        }
+    }
+
+    /// <summary>
+    /// Persists the current state to disk.
+    /// Reference: golang/nats-server/server/filestore.go:11630 (flusher pattern)
+    /// </summary>
+    private void FlushState()
+    {
+        byte[] data;
+        lock (_mu)
+        {
+            if (!_dirty) return;
+            data = ConsumerStateCodec.Encode(_state);
+            _dirty = false;
+        }
+
+        try
+        {
+            var dir = Path.GetDirectoryName(_stateFile);
+            if (!string.IsNullOrEmpty(dir))
+                Directory.CreateDirectory(dir);
+            File.WriteAllBytes(_stateFile, data);
+        }
+        catch
+        {
+            // Best effort; mark dirty again so we retry.
+            lock (_mu) _dirty = true;
+        }
+    }
+
+    /// <summary>
+    /// Background flusher that periodically persists dirty state.
+    /// Reference: golang/nats-server/server/filestore.go — consumerFileStore flusher goroutine.
+    /// </summary>
+    private async Task RunFlusherAsync(CancellationToken ct)
+    {
+        lock (_mu) _inFlusher = true;
+        try
+        {
+            while (!ct.IsCancellationRequested)
+            {
+                await Task.Delay(TimeSpan.FromMilliseconds(250), ct);
+                if (ct.IsCancellationRequested) break;
+                FlushState();
+            }
+        }
+        catch (OperationCanceledException) { /* expected */ }
+        catch { /* best effort */ }
+        finally
+        {
+            lock (_mu) _inFlusher = false;
+        }
+    }
+}

src/NATS.Server/JetStream/Storage/ConsumerStateCodec.cs

@@ -0,0 +1,266 @@
+using System.Buffers.Binary;
+
+namespace NATS.Server.JetStream.Storage;
+
+// Go: server/store.go:397 encodeConsumerState / server/filestore.go:12216 decodeConsumerState
+/// <summary>
+/// Binary encode/decode of ConsumerState matching the Go wire format.
+///
+/// Wire layout (version 2):
+///   [0]  magic   = 22 (0x16)
+///   [1]  version = 2
+///   varuint: AckFloor.Consumer
+///   varuint: AckFloor.Stream
+///   varuint: Delivered.Consumer
+///   varuint: Delivered.Stream
+///   varuint: len(Pending)
+///   if len(Pending) > 0:
+///       varint:  mints (base Unix seconds, now rounded to second)
+///       for each pending entry:
+///           varuint: sseq - AckFloor.Stream
+///           varuint: dseq - AckFloor.Consumer
+///           varint:  mints - (ts / 1e9)   (delta seconds)
+///   varuint: len(Redelivered)
+///   for each redelivered entry:
+///       varuint: sseq - AckFloor.Stream
+///       varuint: count
+///
+/// Reference: golang/nats-server/server/store.go:397  (encodeConsumerState)
+///            golang/nats-server/server/filestore.go:12216 (decodeConsumerState)
+/// </summary>
+public static class ConsumerStateCodec
+{
+    // Go: filestore.go:285
+    private const byte Magic = 22;
+    // Go: filestore.go:291  hdrLen = 2
+    private const int HdrLen = 2;
+    // Go: filestore.go:11852  seqsHdrSize = 6*binary.MaxVarintLen64 + hdrLen
+    // binary.MaxVarintLen64 = 10 bytes
+    private const int SeqsHdrSize = 6 * 10 + HdrLen;
+
+    private const ulong HighBit = 1UL << 63;
+
+    /// <summary>
+    /// Encodes consumer state into the Go-compatible binary format.
+    /// Reference: golang/nats-server/server/store.go:397
+    /// </summary>
+    public static byte[] Encode(ConsumerState state)
+    {
+        // Upper-bound the buffer size.
+        var maxSize = SeqsHdrSize;
+        if (state.Pending?.Count > 0)
+            maxSize += state.Pending.Count * (3 * 10) + 10;
+        if (state.Redelivered?.Count > 0)
+            maxSize += state.Redelivered.Count * (2 * 10) + 10;
+
+        var buf = new byte[maxSize];
+        buf[0] = Magic;
+        buf[1] = 2; // version 2
+
+        var n = HdrLen;
+        n += PutUvarint(buf, n, state.AckFloor.Consumer);
+        n += PutUvarint(buf, n, state.AckFloor.Stream);
+        n += PutUvarint(buf, n, state.Delivered.Consumer);
+        n += PutUvarint(buf, n, state.Delivered.Stream);
+        n += PutUvarint(buf, n, (ulong)(state.Pending?.Count ?? 0));
+
+        var asflr = state.AckFloor.Stream;
+        var adflr = state.AckFloor.Consumer;
+
+        if (state.Pending?.Count > 0)
+        {
+            // Base timestamp: now rounded to the nearest second (Unix seconds).
+            var mints = DateTimeOffset.UtcNow.ToUnixTimeSeconds();
+            n += PutVarint(buf, n, mints);
+
+            foreach (var kv in state.Pending)
+            {
+                var sseq = kv.Key;
+                var p = kv.Value;
+                n += PutUvarint(buf, n, sseq - asflr);
+                n += PutUvarint(buf, n, p.Sequence - adflr);
+                // Downsample timestamp to seconds, store delta from mints.
+                var ts = p.Timestamp / (long)TimeSpan.TicksPerSecond; // ns -> seconds? No — ns / 1e9
+                // p.Timestamp is Unix nanoseconds; convert to seconds.
+                ts = p.Timestamp / 1_000_000_000L;
+                n += PutVarint(buf, n, mints - ts);
+            }
+        }
+
+        n += PutUvarint(buf, n, (ulong)(state.Redelivered?.Count ?? 0));
+
+        if (state.Redelivered?.Count > 0)
+        {
+            foreach (var kv in state.Redelivered)
+            {
+                n += PutUvarint(buf, n, kv.Key - asflr);
+                n += PutUvarint(buf, n, kv.Value);
+            }
+        }
+
+        return buf[..n];
+    }
+
+    /// <summary>
+    /// Decodes consumer state from the Go-compatible binary format.
+    /// Reference: golang/nats-server/server/filestore.go:12216
+    /// </summary>
+    public static ConsumerState Decode(ReadOnlySpan<byte> buf)
+    {
+        // Copy to array first so lambdas can capture without ref-type restrictions.
+        return DecodeFromArray(buf.ToArray());
+    }
+
+    private static ConsumerState DecodeFromArray(byte[] buf)
+    {
+        if (buf.Length < 2 || buf[0] != Magic)
+            throw new InvalidDataException("Corrupt consumer state: bad magic or too short.");
+
+        var version = buf[1];
+        if (version != 1 && version != 2)
+            throw new InvalidDataException($"Unsupported consumer state version: {version}.");
+
+        var bi = HdrLen;
+
+        ulong ReadSeq()
+        {
+            if (bi < 0) return 0;
+            var (v, n) = GetUvarint(buf.AsSpan(bi));
+            if (n <= 0) { bi = -1; return 0; }
+            bi += n;
+            return v;
+        }
+
+        long ReadTimestamp()
+        {
+            if (bi < 0) return 0;
+            var (v, n) = GetVarint(buf.AsSpan(bi));
+            if (n <= 0) { bi = -1; return -1; }
+            bi += n;
+            return v;
+        }
+
+        var state = new ConsumerState();
+        state.AckFloor = state.AckFloor with { Consumer = ReadSeq() };
+        state.AckFloor = state.AckFloor with { Stream = ReadSeq() };
+        state.Delivered = state.Delivered with { Consumer = ReadSeq() };
+        state.Delivered = state.Delivered with { Stream = ReadSeq() };
+
+        if (bi == -1)
+            throw new InvalidDataException("Corrupt consumer state: truncated header.");
+
+        // Version 1: delivered was stored as "next to be delivered", adjust back.
+        if (version == 1)
+        {
+            if (state.AckFloor.Consumer > 1)
+                state.Delivered = state.Delivered with { Consumer = state.Delivered.Consumer + state.AckFloor.Consumer - 1 };
+            if (state.AckFloor.Stream > 1)
+                state.Delivered = state.Delivered with { Stream = state.Delivered.Stream + state.AckFloor.Stream - 1 };
+        }
+
+        // Sanity check high-bit guard.
+        if ((state.AckFloor.Stream & HighBit) != 0 || (state.Delivered.Stream & HighBit) != 0)
+            throw new InvalidDataException("Corrupt consumer state: sequence high-bit set.");
+
+        var numPending = ReadSeq();
+        if (numPending > 0)
+        {
+            var mints = ReadTimestamp();
+            state.Pending = new Dictionary<ulong, Pending>((int)numPending);
+
+            for (var i = 0UL; i < numPending; i++)
+            {
+                var sseq = ReadSeq();
+                ulong dseq = 0;
+                if (version == 2)
+                    dseq = ReadSeq();
+                var ts = ReadTimestamp();
+
+                if (bi == -1)
+                    throw new InvalidDataException("Corrupt consumer state: truncated pending entry.");
+
+                sseq += state.AckFloor.Stream;
+                if (sseq == 0)
+                    throw new InvalidDataException("Corrupt consumer state: zero sseq in pending.");
+
+                if (version == 2)
+                    dseq += state.AckFloor.Consumer;
+
+                // Reconstruct timestamp (nanoseconds).
+                long tsNs;
+                if (version == 1)
+                    tsNs = (ts + mints) * 1_000_000_000L;
+                else
+                    tsNs = (mints - ts) * 1_000_000_000L;
+
+                state.Pending[sseq] = new Pending(dseq, tsNs);
+            }
+        }
+
+        var numRedelivered = ReadSeq();
+        if (numRedelivered > 0)
+        {
+            state.Redelivered = new Dictionary<ulong, ulong>((int)numRedelivered);
+            for (var i = 0UL; i < numRedelivered; i++)
+            {
+                var seq = ReadSeq();
+                var count = ReadSeq();
+                if (seq > 0 && count > 0)
+                    state.Redelivered[seq + state.AckFloor.Stream] = count;
+            }
+        }
+
+        return state;
+    }
+
+    // -------------------------------------------------------------------------
+    // Varint helpers (Go's encoding/binary LEB128 format)
+    // -------------------------------------------------------------------------
+
+    private static int PutUvarint(byte[] buf, int offset, ulong v)
+    {
+        var n = 0;
+        while (v >= 0x80)
+        {
+            buf[offset + n] = (byte)(v | 0x80);
+            v >>= 7;
+            n++;
+        }
+        buf[offset + n] = (byte)v;
+        return n + 1;
+    }
+
+    private static int PutVarint(byte[] buf, int offset, long v)
+    {
+        var uv = v < 0 ? ~((ulong)v << 1) : (ulong)v << 1;
+        return PutUvarint(buf, offset, uv);
+    }
+
+    private static (ulong Value, int BytesRead) GetUvarint(ReadOnlySpan<byte> buf)
+    {
+        ulong x = 0;
+        var s = 0;
+        for (var i = 0; i < buf.Length; i++)
+        {
+            var b = buf[i];
+            if (b < 0x80)
+            {
+                if (i == 9 && b > 1)
+                    return (0, -(i + 1)); // overflow
+                return (x | (ulong)b << s, i + 1);
+            }
+            x |= (ulong)(b & 0x7f) << s;
+            s += 7;
+        }
+        return (0, 0);
+    }
+
+    private static (long Value, int BytesRead) GetVarint(ReadOnlySpan<byte> buf)
+    {
+        var (uv, n) = GetUvarint(buf);
+        long x = (long)(uv >> 1);
+        if ((uv & 1) != 0)
+            x = ~x;
+        return (x, n);
+    }
+}

src/NATS.Server/JetStream/Storage/FileStore.cs

@@ -665,6 +665,20 @@ public sealed class FileStore : IStreamStore, IAsyncDisposable, IDisposable
         DisposeAllBlocks();
     }
 
+    /// <summary>
+    /// Stops the store and deletes all persisted data (blocks, index files).
+    /// Reference: golang/nats-server/server/filestore.go — fileStore.Delete.
+    /// </summary>
+    public void Delete()
+    {
+        DisposeAllBlocks();
+        if (Directory.Exists(_options.Directory))
+        {
+            try { Directory.Delete(_options.Directory, recursive: true); }
+            catch { /* best effort */ }
+        }
+    }
+
 
     // -------------------------------------------------------------------------
     // Block management
@@ -831,12 +845,24 @@ public sealed class FileStore : IStreamStore, IAsyncDisposable, IDisposable
 
         PruneExpired(DateTime.UtcNow);
 
-        // After recovery, sync _last watermark from block metadata only when
-        // no messages were recovered (e.g., after a full purge). This ensures
-        // FirstSeq/LastSeq watermarks survive a restart after purge.
-        // We do NOT override _last if messages were found — truncation may have
-        // reduced _last below the block's raw LastSequence.
+        // After recovery, sync _last from skip-sequence high-water marks.
+        // SkipMsg/SkipMsgs write tombstone records with empty subject — these
+        // intentionally advance _last without storing a live message. We must
+        // include them in the high-water mark so the next StoreMsg gets the
+        // correct sequence number.
+        // We do NOT use block.LastSequence blindly because that includes
+        // soft-deleted real messages at the tail (e.g., after Truncate or
+        // RemoveMsg of the last message), which must not inflate _last.
         // Go: filestore.go — recovery sets state.LastSeq from lmb.last.seq.
+        foreach (var blk in _blocks)
+        {
+            var maxSkip = blk.MaxSkipSequence;
+            if (maxSkip > _last)
+                _last = maxSkip;
+        }
+
+        // If no messages and no skips were found, fall back to block.LastSequence
+        // to preserve watermarks from purge or full-delete scenarios.
         if (_last == 0)
         {
             foreach (var blk in _blocks)
@@ -1320,8 +1346,9 @@ public sealed class FileStore : IStreamStore, IAsyncDisposable, IDisposable
         var removed = _messages.Remove(seq);
         if (removed)
         {
-            if (seq == _last)
-                _last = _messages.Count == 0 ? _last : _messages.Keys.Max();
+            // Go: filestore.go — LastSeq (lmb.last.seq) is a high-water mark and is
+            // never decremented on removal. Only FirstSeq advances when the first
+            // live message is removed.
             if (_messages.Count == 0)
                 _first = _last + 1; // All gone — next first would be after last
             else
@@ -1577,6 +1604,25 @@ public sealed class FileStore : IStreamStore, IAsyncDisposable, IDisposable
     }
 
 
+    // -------------------------------------------------------------------------
+    // ConsumerStore factory
+    // Reference: golang/nats-server/server/filestore.go — fileStore.ConsumerStore
+    // -------------------------------------------------------------------------
+
+    /// <summary>
+    /// Creates or opens a per-consumer state store backed by a binary file.
+    /// The state file is located at <c>{Directory}/obs/{name}/o.dat</c>,
+    /// matching the Go server's consumer directory layout.
+    /// Reference: golang/nats-server/server/filestore.go — newConsumerFileStore.
+    /// </summary>
+    public IConsumerStore ConsumerStore(string name, DateTime created, ConsumerConfig cfg)
+    {
+        var consumerDir = Path.Combine(_options.Directory, "obs", name);
+        Directory.CreateDirectory(consumerDir);
+        var stateFile = Path.Combine(consumerDir, "o.dat");
+        return new ConsumerFileStore(stateFile, cfg);
+    }
+
     private sealed class FileRecord
     {
         public ulong Sequence { get; init; }

src/NATS.Server/JetStream/Storage/FileStoreOptions.cs

@@ -22,4 +22,8 @@ public sealed class FileStoreOptions
     // Enums are defined in AeadEncryptor.cs.
     public StoreCompression Compression { get; set; } = StoreCompression.NoCompression;
     public StoreCipher Cipher { get; set; } = StoreCipher.NoCipher;
+
+    // Go: StreamConfig.MaxMsgsPer — maximum messages per subject (1 = keep last per subject).
+    // Reference: golang/nats-server/server/filestore.go — per-subject message limits.
+    public int MaxMsgsPerSubject { get; set; }
 }

src/NATS.Server/JetStream/Storage/MsgBlock.cs

@@ -26,6 +26,9 @@ public sealed class MsgBlock : IDisposable
     private readonly SafeFileHandle _handle;
     private readonly Dictionary<ulong, (long Offset, int Length)> _index = new();
     private readonly HashSet<ulong> _deleted = new();
+    // Go: SkipMsg writes tombstone records with empty subject — tracked separately so
+    // recovery can distinguish intentional sequence gaps from soft-deleted messages.
+    private readonly HashSet<ulong> _skipSequences = new();
     private readonly long _maxBytes;
     private readonly ReaderWriterLockSlim _lock = new();
     private long _writeOffset;   // Tracks the append position independently of FileStream.Position
@@ -402,6 +405,7 @@ public sealed class MsgBlock : IDisposable
 
             _index[sequence] = (offset, encoded.Length);
             _deleted.Add(sequence);
+            _skipSequences.Add(sequence); // Track skip sequences separately for recovery
             // Note: intentionally NOT added to _cache since it is deleted.
 
             if (_totalWritten == 0)
@@ -447,6 +451,22 @@ public sealed class MsgBlock : IDisposable
         finally { _lock.ExitReadLock(); }
     }
 
+    /// <summary>
+    /// Returns the maximum skip-sequence written into this block (0 if none).
+    /// Skip sequences are intentional tombstones from SkipMsg/SkipMsgs —
+    /// they bump _last without storing a live message, so recovery must account
+    /// for them when computing the high-water mark.
+    /// </summary>
+    public ulong MaxSkipSequence
+    {
+        get
+        {
+            _lock.EnterReadLock();
+            try { return _skipSequences.Count > 0 ? _skipSequences.Max() : 0UL; }
+            finally { _lock.ExitReadLock(); }
+        }
+    }
+
     /// <summary>
     /// Exposes the set of soft-deleted sequence numbers for read-only inspection.
     /// Reference: golang/nats-server/server/filestore.go — dmap access for state queries.
@@ -582,7 +602,12 @@ public sealed class MsgBlock : IDisposable
             _index[record.Sequence] = (offset, recordLength);
 
             if (record.Deleted)
+            {
                 _deleted.Add(record.Sequence);
+                // Empty subject = skip/tombstone record (from SkipMsg/SkipMsgs).
+                if (string.IsNullOrEmpty(record.Subject))
+                    _skipSequences.Add(record.Sequence);
+            }
 
             if (count == 0)
                 _firstSequence = record.Sequence;