# Pinned MongoDB 7.0.22 session-history transfer and commit-drain boundaries > Source-anchored research for Pinned MongoDB 7.0.22 session-history transfer and commit-drain boundaries. Run status: COMPLETED. Parent: [Chunk migration commit, range deleter and orphan cleanup internals](https://llms-explorer.com/tree/chunk-migration-commit-range-deleter-and-orphan-cleanup-internals/) · 5 facets · 23 facts · page: https://llms-explorer.com/tree/pinned-mongodb-7-0-22-session-history-transfer-and-commit-drain-boundaries/ ## Structure and components - The donor scans the session transaction table for parent-session records without a transaction UUID and committed internal sessions that contain a parent transaction number. It sorts session identifiers descending, skips histories whose parent transaction number is below the previously observed maximum for that parent, and creates history iterators only for non-null last-write times. The filter excludes aborted, prepared and in-progress retryable internal transactions, and all non-retryable internal sessions. (low confidence) — [source](https://raw.githubusercontent.com/mongodb/mongo/dacdbc3df2fbe579b03336a2f01fc9aedf406a41/src/mongo/db/s/session_catalog_migration_source.cpp) · [also](https://api.github.com/repos/mongodb/mongo/git/ref/tags/r7.0.22) · [also](https://api.github.com/repos/mongodb/mongo/git/tags/ef98696d6009abf1b6f73a935c9f7bb3fa3ea4c4) · [also](https://www.mongodb.com/docs/v7.0/release-notes/7.0/) - The recipient fetches from the donor primary with the no-retry command policy. It rejects a response whose oplog field is not an array. Each incoming oplog entry must parse successfully, contain a session identifier and transaction number, and have a nonempty statement-identifier list. (low confidence) — [source](https://raw.githubusercontent.com/mongodb/mongo/dacdbc3df2fbe579b03336a2f01fc9aedf406a41/src/mongo/db/s/session_catalog_migration_destination.cpp) · [also](https://api.github.com/repos/mongodb/mongo/git/ref/tags/r7.0.22) · [also](https://api.github.com/repos/mongodb/mongo/git/tags/ef98696d6009abf1b6f73a935c9f7bb3fa3ea4c4) · [also](https://www.mongodb.com/docs/v7.0/release-notes/7.0/) - For a non-image record, the recipient logs the new no-op and updates the session transaction record in one write unit of work under write-conflict retry, using the same wall-clock time and without setting the persisted transaction-state field. The transaction participant requires an active write unit of work, writes the session table without an extra replicated write, and registers its statement-cache update for commit. An image alone does not advance the session transaction record. (high confidence) — [source](https://raw.githubusercontent.com/mongodb/mongo/dacdbc3df2fbe579b03336a2f01fc9aedf406a41/src/mongo/db/s/session_catalog_migration_destination.cpp) · [also](https://raw.githubusercontent.com/mongodb/mongo/dacdbc3df2fbe579b03336a2f01fc9aedf406a41/src/mongo/db/transaction/transaction_participant.cpp) · [also](https://api.github.com/repos/mongodb/mongo/git/ref/tags/r7.0.22) · [also](https://api.github.com/repos/mongodb/mongo/git/tags/ef98696d6009abf1b6f73a935c9f7bb3fa3ea4c4) · [also](https://www.mongodb.com/docs/v7.0/release-notes/7.0/) ## How it works - When history traversal raises incomplete-history, the donor compares the current rollback identifier with the identifier captured at construction and aborts if it changed. If it has not changed, retryable-write records and prepared or committed transaction records produce a lost-history sentinel; other transaction states are skipped, and the iterator is reset. The rollback fixture increments the rollback identifier and asserts that the next history fetch throws. The incomplete-history fixture asserts a sentinel with the incomplete-history statement identifier, followed by exhaustion. These are fixture assertions, not integration or workload measurements. (high confidence) — [source](https://raw.githubusercontent.com/mongodb/mongo/dacdbc3df2fbe579b03336a2f01fc9aedf406a41/src/mongo/db/s/session_catalog_migration_source.cpp) · [also](https://raw.githubusercontent.com/mongodb/mongo/dacdbc3df2fbe579b03336a2f01fc9aedf406a41/src/mongo/db/s/session_catalog_migration_source_test.cpp) · [also](https://api.github.com/repos/mongodb/mongo/git/ref/tags/r7.0.22) · [also](https://api.github.com/repos/mongodb/mongo/git/tags/ef98696d6009abf1b6f73a935c9f7bb3fa3ea4c4) · [also](https://www.mongodb.com/docs/v7.0/release-notes/7.0/) - Treat this evidence as the historical MongoDB 7.0.22 source-defined session-history protocol. The donor explicitly substitutes lost-history markers because it does not support retrying entire transactions; the recipient records retryable history as no-ops without setting the persisted transaction-state field. These mechanisms do not establish full transaction replay. Do not extrapolate them into a universal client retry guarantee, measured latency, replication-lag throttling, current-release behavior, CDC sink co-commit or a production-safety guarantee. (high confidence) — [source](https://raw.githubusercontent.com/mongodb/mongo/dacdbc3df2fbe579b03336a2f01fc9aedf406a41/src/mongo/db/s/session_catalog_migration_source.cpp) · [also](https://raw.githubusercontent.com/mongodb/mongo/dacdbc3df2fbe579b03336a2f01fc9aedf406a41/src/mongo/db/s/session_catalog_migration_destination.cpp) · [also](https://api.github.com/repos/mongodb/mongo/git/ref/tags/r7.0.22) · [also](https://api.github.com/repos/mongodb/mongo/git/tags/ef98696d6009abf1b6f73a935c9f7bb3fa3ea4c4) · [also](https://www.mongodb.com/docs/v7.0/release-notes/7.0/) - When a session-history source exists, the cloner forwards non-null retryable-write operation times into its history queue. The transaction-commit handler excludes non-retryable internal sessions and queues each eligible touched namespace with an active cloner at most once. The donor fixture for writes arriving after depletion repeatedly asserts that newly queued entries become fetchable and require a majority wait. (high confidence) — [source](https://raw.githubusercontent.com/mongodb/mongo/dacdbc3df2fbe579b03336a2f01fc9aedf406a41/src/mongo/db/s/migration_chunk_cloner_source.cpp) · [also](https://raw.githubusercontent.com/mongodb/mongo/dacdbc3df2fbe579b03336a2f01fc9aedf406a41/src/mongo/db/s/session_catalog_migration_source_test.cpp) · [also](https://api.github.com/repos/mongodb/mongo/git/ref/tags/r7.0.22) · [also](https://api.github.com/repos/mongodb/mongo/git/tags/ef98696d6009abf1b6f73a935c9f7bb3fa3ea4c4) · [also](https://www.mongodb.com/docs/v7.0/release-notes/7.0/) ## Problems, failure modes and limitations - The donor looks up a retry image by session identity and can forge an image no-op only when the image exists and its transaction number matches the originating operation. It copies the image, session and statement information, and emits the image before its operation. Both receive parent-session identity conversion when necessary. If no usable image exists, it strips needsRetryImage; the source comment says a destination retry then surfaces an error, so the transfer does not promise successful retry-result reconstruction for an unavailable image. Classic image links instead fetch the referenced oplog record. The recipient rewrites the image reference to a local oplog image link. (low confidence) — [source](https://raw.githubusercontent.com/mongodb/mongo/dacdbc3df2fbe579b03336a2f01fc9aedf406a41/src/mongo/db/s/session_catalog_migration_source.cpp) · [also](https://raw.githubusercontent.com/mongodb/mongo/dacdbc3df2fbe579b03336a2f01fc9aedf406a41/src/mongo/db/s/session_catalog_migration_destination.cpp) · [also](https://api.github.com/repos/mongodb/mongo/git/ref/tags/r7.0.22) · [also](https://api.github.com/repos/mongodb/mongo/git/tags/ef98696d6009abf1b6f73a935c9f7bb3fa3ea4c4) · [also](https://www.mongodb.com/docs/v7.0/release-notes/7.0/) - The donor batch builder chooses the highest operation time among entries marked as requiring a majority wait. The command handler waits for that operation time, then checks the rollback identifier; its comment requires this ordering so a rolled-back entry cannot escape detection. The header separately specifies that callers must reject a change of term within a batch. The cited implementation shows the majority wait and rollback check; it does not justify attributing an explicit term-comparison branch to the batch-building loop. The session-mods command waits on a notification when it has no batch and continues until it has entries or completion; returned batches participate in that stateful buffer-draining protocol. (high confidence) — [source](https://raw.githubusercontent.com/mongodb/mongo/dacdbc3df2fbe579b03336a2f01fc9aedf406a41/src/mongo/db/s/migration_chunk_cloner_source.cpp) · [also](https://raw.githubusercontent.com/mongodb/mongo/dacdbc3df2fbe579b03336a2f01fc9aedf406a41/src/mongo/db/s/migration_chunk_cloner_source_legacy_commands.cpp) · [also](https://raw.githubusercontent.com/mongodb/mongo/dacdbc3df2fbe579b03336a2f01fc9aedf406a41/src/mongo/db/s/session_catalog_migration_source.h) · [also](https://api.github.com/repos/mongodb/mongo/git/ref/tags/r7.0.22) · [also](https://api.github.com/repos/mongodb/mongo/git/tags/ef98696d6009abf1b6f73a935c9f7bb3fa3ea4c4) · [also](https://www.mongodb.com/docs/v7.0/release-notes/7.0/) - start changes NotStarted to Migrating and spawns the transfer thread. On an empty batch, the recipient majority-waits for its last local result and changes Migrating to ReadyToCommit only if it is still Migrating after that wait. This first-drain state is not Done. finish changes a non-error state to Committing. Readiness leaves the retrieval loop active for the finish signal and additional donor history. The public class interface distinguishes migrating, ready-to-commit, committing, error and done states. (low confidence) — [source](https://raw.githubusercontent.com/mongodb/mongo/dacdbc3df2fbe579b03336a2f01fc9aedf406a41/src/mongo/db/s/session_catalog_migration_destination.cpp) · [also](https://raw.githubusercontent.com/mongodb/mongo/dacdbc3df2fbe579b03336a2f01fc9aedf406a41/src/mongo/db/s/session_catalog_migration_destination.h) · [also](https://api.github.com/repos/mongodb/mongo/git/ref/tags/r7.0.22) · [also](https://api.github.com/repos/mongodb/mongo/git/tags/ef98696d6009abf1b6f73a935c9f7bb3fa3ea4c4) · [also](https://www.mongodb.com/docs/v7.0/release-notes/7.0/) - Calling finish changes the recipient state to committing unless an error is already recorded. In the retrieval loop, the first empty batch observed in committing sets the post-commit drain flag and performs a majority wait; a later empty batch observed in committing breaks the loop. The flag is not reset on a nonempty batch. After the loop, the worker again waits for majority acknowledgement of its last local history operation before setting done. The fixture success helper supplies two empty responses after finish and asserts done after joining. (high confidence) — [source](https://raw.githubusercontent.com/mongodb/mongo/dacdbc3df2fbe579b03336a2f01fc9aedf406a41/src/mongo/db/s/session_catalog_migration_destination.cpp) · [also](https://raw.githubusercontent.com/mongodb/mongo/dacdbc3df2fbe579b03336a2f01fc9aedf406a41/src/mongo/db/s/session_catalog_migration_destination_test.cpp) · [also](https://api.github.com/repos/mongodb/mongo/git/ref/tags/r7.0.22) · [also](https://api.github.com/repos/mongodb/mongo/git/tags/ef98696d6009abf1b6f73a935c9f7bb3fa3ea4c4) · [also](https://www.mongodb.com/docs/v7.0/release-notes/7.0/) - Cancelable operation contexts cover recipient fetches, entry processing and the final majority wait; they are marked interruptible on stepdown or stepup. The worker records most DBExceptions as ErrorOccurred, and forceFail records that state too. The legacy CommandNotFound exception returns from the worker without setting Done. join waits for the spawned thread; the destructor records an error and joins if necessary. Manager failure paths force the session worker into an error state. The network-error fixture asserts that joining completes with an error state and a nonempty message. (low confidence) — [source](https://raw.githubusercontent.com/mongodb/mongo/dacdbc3df2fbe579b03336a2f01fc9aedf406a41/src/mongo/db/s/session_catalog_migration_destination.cpp) · [also](https://raw.githubusercontent.com/mongodb/mongo/dacdbc3df2fbe579b03336a2f01fc9aedf406a41/src/mongo/db/s/migration_destination_manager.cpp) · [also](https://raw.githubusercontent.com/mongodb/mongo/dacdbc3df2fbe579b03336a2f01fc9aedf406a41/src/mongo/db/s/session_catalog_migration_destination_test.cpp) · [also](https://api.github.com/repos/mongodb/mongo/git/ref/tags/r7.0.22) · [also](https://api.github.com/repos/mongodb/mongo/git/tags/ef98696d6009abf1b6f73a935c9f7bb3fa3ea4c4) · [also](https://www.mongodb.com/docs/v7.0/release-notes/7.0/) - In the initial migration path, MigrationDestinationManager constructs the session worker with its cancellation token and starts it during initial bulk clone. startCommit requires steady state and a matching migration session before calling finish. After document-mod draining, the migration thread joins the session worker without holding the outer session; a worker error fails migration before recipient recovery persistence and critical-section acquisition. (low confidence) — [source](https://raw.githubusercontent.com/mongodb/mongo/dacdbc3df2fbe579b03336a2f01fc9aedf406a41/src/mongo/db/s/migration_destination_manager.cpp) · [also](https://api.github.com/repos/mongodb/mongo/git/ref/tags/r7.0.22) · [also](https://api.github.com/repos/mongodb/mongo/git/tags/ef98696d6009abf1b6f73a935c9f7bb3fa3ea4c4) · [also](https://www.mongodb.com/docs/v7.0/release-notes/7.0/) ## Comparisons and alternatives - Committed retryable internal transactions are traversed as history: commit-transaction entries are skipped, and apply-operations entries are unrolled. Inner operations must have statement identifiers and the migrating namespace, then pass the shared filter. CRUD entries require a chunk key in range. Rewritten migration-tagged no-ops also undergo that range check unless they are incomplete-history markers; other no-ops pass without a chunk-key check. The committed-internal-transaction fixture includes an owning-shard-change no-op among the expected transferred operations. Before transfer, internal retryable-session identities and transaction numbers are rewritten to the parent retryable-write identity and parent transaction number. This is conversion of retryable history rather than transaction execution. (low confidence) — [source](https://raw.githubusercontent.com/mongodb/mongo/dacdbc3df2fbe579b03336a2f01fc9aedf406a41/src/mongo/db/s/session_catalog_migration_source.cpp) · [also](https://api.github.com/repos/mongodb/mongo/git/ref/tags/r7.0.22) · [also](https://api.github.com/repos/mongodb/mongo/git/tags/ef98696d6009abf1b6f73a935c9f7bb3fa3ea4c4) · [also](https://www.mongodb.com/docs/v7.0/release-notes/7.0/) · [also](https://raw.githubusercontent.com/mongodb/mongo/dacdbc3df2fbe579b03336a2f01fc9aedf406a41/src/mongo/db/s/session_catalog_migration_source_test.cpp) - Initial history is fetched before queued writes. Initial-history records and image no-ops return shouldWaitForMajority false; new originating writes return true. Cleanup signals terminal completion. Otherwise pending writes take precedence over commit-started state, so buffered history must still drain after commit starts. Commit-start and cleanup wake waiting consumers. Newly queued operation times wake a waiting notification to request another fetch. Temporary depletion therefore differs from terminal drain. (low confidence) — [source](https://raw.githubusercontent.com/mongodb/mongo/dacdbc3df2fbe579b03336a2f01fc9aedf406a41/src/mongo/db/s/session_catalog_migration_source.h) · [also](https://raw.githubusercontent.com/mongodb/mongo/dacdbc3df2fbe579b03336a2f01fc9aedf406a41/src/mongo/db/s/session_catalog_migration_source.cpp) · [also](https://api.github.com/repos/mongodb/mongo/git/ref/tags/r7.0.22) · [also](https://api.github.com/repos/mongodb/mongo/git/tags/ef98696d6009abf1b6f73a935c9f7bb3fa3ea4c4) · [also](https://www.mongodb.com/docs/v7.0/release-notes/7.0/) ## Facts and statements - The donor casts the migration session identifier to its parent identity and excludes any record with the same parent identity. The source comment explains that transferring this migration bookkeeping session could deadlock against the recipient session checkout. (low confidence) — [source](https://raw.githubusercontent.com/mongodb/mongo/dacdbc3df2fbe579b03336a2f01fc9aedf406a41/src/mongo/db/s/session_catalog_migration_source.cpp) · [also](https://api.github.com/repos/mongodb/mongo/git/ref/tags/r7.0.22) · [also](https://api.github.com/repos/mongodb/mongo/git/tags/ef98696d6009abf1b6f73a935c9f7bb3fa3ea4c4) · [also](https://www.mongodb.com/docs/v7.0/release-notes/7.0/) - The initial majority barrier handles histories from older replication terms: after collecting session last-write times, the donor writes a new initialization no-op and waits for majority acknowledgement without a timeout. The header explains that directly waiting for an older-term operation time is unsupported; the later barrier covers earlier history, while a failed history lookup can mean truncation or rollback. (high confidence) — [source](https://raw.githubusercontent.com/mongodb/mongo/dacdbc3df2fbe579b03336a2f01fc9aedf406a41/src/mongo/db/s/session_catalog_migration_source.h) · [also](https://raw.githubusercontent.com/mongodb/mongo/dacdbc3df2fbe579b03336a2f01fc9aedf406a41/src/mongo/db/s/session_catalog_migration_source.cpp) · [also](https://api.github.com/repos/mongodb/mongo/git/ref/tags/r7.0.22) · [also](https://api.github.com/repos/mongodb/mongo/git/tags/ef98696d6009abf1b6f73a935c9f7bb3fa3ea4c4) · [also](https://www.mongodb.com/docs/v7.0/release-notes/7.0/) - For ordinary retryable-write history, a namespace mismatch ends traversal of that session chain, except for the incomplete-history marker. CRUD entries outside the chunk range are skipped. Previously migrated tagged no-ops are filtered using the original operation in their secondary object, while incomplete-history tagged no-ops pass through. A skipped operation also omits its associated image. (low confidence) — [source](https://raw.githubusercontent.com/mongodb/mongo/dacdbc3df2fbe579b03336a2f01fc9aedf406a41/src/mongo/db/s/session_catalog_migration_source.cpp) · [also](https://api.github.com/repos/mongodb/mongo/git/ref/tags/r7.0.22) · [also](https://api.github.com/repos/mongodb/mongo/git/tags/ef98696d6009abf1b6f73a935c9f7bb3fa3ea4c4) · [also](https://www.mongodb.com/docs/v7.0/release-notes/7.0/) - New writes enter an opTime queue separately from initial session history. The donor reads the queued oplog outside its queue mutex and asserts if it is absent. Ordinary retryable writes transfer directly; retryable internal transactions unroll filtered applyOps and enqueue previous applyOps links; non-retryable internal transactions are skipped; non-internal transaction prepare/commit history becomes a sentinel. Image conversion and identity down-conversion also apply to this path. (high confidence) — [source](https://raw.githubusercontent.com/mongodb/mongo/dacdbc3df2fbe579b03336a2f01fc9aedf406a41/src/mongo/db/s/session_catalog_migration_source.cpp) · [also](https://api.github.com/repos/mongodb/mongo/git/ref/tags/r7.0.22) · [also](https://api.github.com/repos/mongodb/mongo/git/tags/ef98696d6009abf1b6f73a935c9f7bb3fa3ea4c4) · [also](https://www.mongodb.com/docs/v7.0/release-notes/7.0/) - Recipient history replay writes local no-ops. An incoming non-no-op is preserved as the nested original operation; an already migrated no-op is not nested again. Image no-ops retain their image object, and owning-shard-change sentinels retain their special object. Other operations receive the session-migration tag, a local previous-write link, a newly allocated operation time and the from-migration marker. These statements describe history records, not reapplication of donor user-data mutations. (low confidence) — [source](https://raw.githubusercontent.com/mongodb/mongo/dacdbc3df2fbe579b03336a2f01fc9aedf406a41/src/mongo/db/s/session_catalog_migration_destination.cpp) · [also](https://api.github.com/repos/mongodb/mongo/git/ref/tags/r7.0.22) · [also](https://api.github.com/repos/mongodb/mongo/git/tags/ef98696d6009abf1b6f73a935c9f7bb3fa3ea4c4) · [also](https://www.mongodb.com/docs/v7.0/release-notes/7.0/) - For history entries it replays, the recipient reconstructs image links using the preceding locally inserted image operation time and requires matching session and transaction identities. It converts retry-image markers to the classic pre-image or post-image link and clears the marker. It rejects a second image while the previous local result is an image, an unexpected classic image link without a preceding image, or a replayed operation following an image without the required link. The forged-pre-image fixture asserts that the outer migrated record has a pre-image link, has no retry-image marker, and points to an image with the original object. (high confidence) — [source](https://raw.githubusercontent.com/mongodb/mongo/dacdbc3df2fbe579b03336a2f01fc9aedf406a41/src/mongo/db/s/session_catalog_migration_destination.cpp) · [also](https://raw.githubusercontent.com/mongodb/mongo/dacdbc3df2fbe579b03336a2f01fc9aedf406a41/src/mongo/db/s/session_catalog_migration_destination_test.cpp) · [also](https://api.github.com/repos/mongodb/mongo/git/ref/tags/r7.0.22) · [also](https://api.github.com/repos/mongodb/mongo/git/tags/ef98696d6009abf1b6f73a935c9f7bb3fa3ea4c4) · [also](https://www.mongodb.com/docs/v7.0/release-notes/7.0/) - The recipient checks out the session, begins or continues its transaction and checks the first statement id. Already executed statements and incomplete local history return the prior result without patching history. An incomplete-history sentinel is also skipped if the guarded operation throws. TransactionTooOld is caught by the outer loop and skipped, preserving newer transaction history. (high confidence) — [source](https://raw.githubusercontent.com/mongodb/mongo/dacdbc3df2fbe579b03336a2f01fc9aedf406a41/src/mongo/db/s/session_catalog_migration_destination.cpp) · [also](https://raw.githubusercontent.com/mongodb/mongo/dacdbc3df2fbe579b03336a2f01fc9aedf406a41/src/mongo/db/s/session_catalog_migration_destination_test.cpp) · [also](https://api.github.com/repos/mongodb/mongo/git/ref/tags/r7.0.22) · [also](https://api.github.com/repos/mongodb/mongo/git/tags/ef98696d6009abf1b6f73a935c9f7bb3fa3ea4c4) · [also](https://www.mongodb.com/docs/v7.0/release-notes/7.0/) - The donor cloner constructs its session-history source only in replica-set mode. It initializes and primes session transfer in startClone. Before asking the recipient to commit, it signals onCommitCloneStarted. After recipient success, remaining session history produces SessionTransferIncomplete; cancellation signals cleanup. (low confidence) — [source](https://raw.githubusercontent.com/mongodb/mongo/dacdbc3df2fbe579b03336a2f01fc9aedf406a41/src/mongo/db/s/migration_chunk_cloner_source.cpp) · [also](https://api.github.com/repos/mongodb/mongo/git/ref/tags/r7.0.22) · [also](https://api.github.com/repos/mongodb/mongo/git/tags/ef98696d6009abf1b6f73a935c9f7bb3fa3ea4c4) · [also](https://www.mongodb.com/docs/v7.0/release-notes/7.0/) - The recipient migrated-entry counter measures processed incoming records, including records that may be skipped before local logging. Its header explicitly says that processed entries need not equal committed entries. The older-transaction fixture asserts a processed-entry count even though the newer local history is retained. This counter must not be treated as a count of committed transferred records. (high confidence) — [source](https://raw.githubusercontent.com/mongodb/mongo/dacdbc3df2fbe579b03336a2f01fc9aedf406a41/src/mongo/db/s/session_catalog_migration_destination.cpp) · [also](https://raw.githubusercontent.com/mongodb/mongo/dacdbc3df2fbe579b03336a2f01fc9aedf406a41/src/mongo/db/s/session_catalog_migration_destination.h) · [also](https://raw.githubusercontent.com/mongodb/mongo/dacdbc3df2fbe579b03336a2f01fc9aedf406a41/src/mongo/db/s/session_catalog_migration_destination_test.cpp) · [also](https://api.github.com/repos/mongodb/mongo/git/ref/tags/r7.0.22) · [also](https://api.github.com/repos/mongodb/mongo/git/tags/ef98696d6009abf1b6f73a935c9f7bb3fa3ea4c4) · [also](https://www.mongodb.com/docs/v7.0/release-notes/7.0/)