Fixed critical seqNo renumbering bug in TopicWriter

[polRk]

What

Fixed critical seqNo renumbering bug in TopicWriter and simplified API by removing return value from write() method.

Why

Bug fix:
Previously, when messages were written before session initialization (before receiving lastSeqNo from server), auto-generated seqNo started from 0 and were never renumbered after session initialization. This caused seqNo conflicts when:

• Multiple writers used the same producerId
• Writer reconnected after network issues
• Messages were written immediately after writer creation

The fix ensures that all pending messages in auto seqNo mode are properly renumbered to continue from server's lastSeqNo + 1 after session initialization.

API simplification:
The write() method previously returned seqNo values that could be misleading - they were temporary before session initialization and could change after reconnection. Removing the return value simplifies the API and prevents misuse.

Changes

Bug Fix: seqNo Renumbering

• machine.ts: Implemented proper seqNo renumbering in updateWriteSession action
  • In auto seqNo mode: messages written before session initialization are now renumbered sequentially starting from serverLastSeqNo + 1
  • In manual seqNo mode: user-provided seqNo remain unchanged (as before)
  • Properly handles sliding window compaction and message renumbering

API Changes

• writer.ts:
  • write() method now returns void instead of bigint (removed seqNo return value)
  • Added isSessionInitialized flag to track session state
  • Updated writer.session event handling to use nextSeqNo from state machine
  • Added seqNoMode parameter to writer.write event for state machine

Code Improvements

• types.ts: Updated WriterEmitted type to include nextSeqNo in writer.session event
• seqno-manager.ts: Enhanced to support mode detection and state tracking
• Tests: Updated to remove assertions on write() return values, verify seqNo renumbering works correctly

Migration Guide

If you were storing seqNo from write() return value:

// Before
let seqNo = writer.write(data)
await saveToDatabase(seqNo)

// After
writer.write(data)
let lastSeqNo = await writer.flush() // Get final seqNo after flush
await saveToDatabase(lastSeqNo)Important:

• User-provided seqNo (via extra.seqNo) remain final and unchanged - no migration needed
• After flush() completes, all seqNo values up to returned lastSeqNo are final
• Use sequential order of write() calls to track individual messages if needed

Testing

• ✅ Added tests verifying seqNo renumbering works correctly during reconnections
• ✅ Updated existing tests to work with new API (no return value from write())
• ✅ Verified messages are properly sequenced after session initialization
• ✅ All existing tests pass

Files Changed

• packages/topic/src/writer2/machine.ts - Implemented seqNo renumbering logic
• packages/topic/src/writer2/writer.ts - Removed return value, added session tracking
• packages/topic/src/writer2/types.ts - Updated event types
• packages/topic/src/writer2/seqno-manager.ts - Enhanced seqNo management
• packages/topic/tests/writer2.test.ts - Updated tests
• .changeset/remove-write-seqno-return.md - Added changeset

Checklist

• ✅ Changeset added
• ✅ Tests updated
• ✅ Linter passes
• ✅ Build passes

[nikolaymatrosov]

If the seqNo returned by write() cannot be reliably used until the session is initialized or flushed, perhaps it would be safer not to return a value that looks like a final sequence number at all.

Instead, we could return an opaque object (e.g. a SeqToken) that encapsulates the temporary state and provides a method like resolveSeqNo() to obtain the final value later. This approach would prevent users from mistakenly persisting or relying on a non-final seqNo and make the API usage pattern more explicit.

interface SeqToken {
  resolveSeqNo(): bigint
}

class TopicWriter {
  write(
    data: Uint8Array,
    extra?: {
      seqNo?: bigint
      createdAt?: Date
      metadataItems?: Record<string, Uint8Array>
    }
  ): SeqToken {
    ...
  }
}

[polRk]

it would be safer not to return a value that looks like

I thought about it, but it's a loss of backward compatibility.

write(): SeqToken

I intentionally did not make the return value an object so that there would not be many references and the GC could dispose of memory more efficiently.