Add documentation for replication client

[morgo]

A Pull Request should be associated with an Issue.

We wish to have discussions in Issues. A single issue may be targeted by multiple PRs.
If you're offering a new feature or fixing anything, we'd like to know beforehand in Issues,
and potentially we'll be able to point development in a particular direction.
Further notes in https://github.com/block/spirit/blob/main/.github/CONTRIBUTING.md

Provides documentation for the replication client package.

[Copilot]

Pull request overview

Adds a new README documenting how the pkg/repl replication client works and how its subscription implementations handle binlog deltas during migrations.

Changes:

• Introduces pkg/repl/README.md explaining the replication client’s purpose and architecture.
• Documents the three subscription implementations (delta map, delta queue, buffered map) with tradeoffs and examples.
• Describes key operational behaviors: watermark optimization, checkpointing, and cutover coordination.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 3 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[aparajon]

Is there force-cutover behavior that can help here?

[morgo]

Force cutover applies to the lock acquisition. This threshold is about once we have the lock, what we can reasonably do before we decide that we're taking too long.

The repl.FlushUnderTableLock() call requires that you have to have pre-created the lock, which is done here:

spirit/pkg/migration/cutover.go

Lines 122 to 129 in 35bd921

	tableLock, err := dbconn.NewTableLock(ctx, c.db, tablesToLock, c.dbConfig, c.logger)
	if err != nil {
	return err
	}
	defer utils.CloseAndLogWithContext(ctx, tableLock)
	if err := c.feed.FlushUnderTableLock(ctx, tableLock); err != nil {
	return err
	}

(This is where force / non-force matters).