feat: Add preserveSequence flag for upserts

[premtsd-code]

• Add preserveSequence property to Database class
• Add getPreserveSequence(), setPreserveSequence(), withPreserveSequence() methods
• Conditionally remove $sequence in upsertDocuments based on flag
• Add setPreserveSequence() to Mirror class for consistency
• Add testPreserveSequenceUpsert test in DocumentTests.php

Notes

• For SQL adapters (schemaful), invalid $sequence values are validated and throw a StructureException
• For MongoDB and other schemaless adapters, $sequence type validation is delegated to the database itself rather than being enforced at the application level

[coderabbitai]

📝 Walkthrough

Walkthrough

The changes introduce a new preserveSequence feature flag to the Database class that controls whether document sequence attributes are preserved during upsert operations. New public API methods expose this flag via getters, setters, and a context manager. Conditional logic in upsertDocumentsWithIncrease removes the sequence attribute when the flag is disabled. Mirror class delegation and end-to-end tests are also added.

Changes

Cohort / File(s)	Summary
Database sequence preservation feature src/Database/Database.php	Added protected property preserveSequence (default false). Introduced public methods: getPreserveSequence(), setPreserveSequence(), and withPreserveSequence() context manager. Modified upsertDocumentsWithIncrease() to conditionally remove $sequence attribute based on flag state, mirroring existing preserveDates pattern.
Mirror delegation src/Database/Mirror.php	Added setPreserveSequence() method that delegates through the mirror flow and assigns the property, following the existing setPreserveDates pattern.
E2E test coverage tests/e2e/Adapter/Scopes/DocumentTests.php	Added testPreserveSequenceUpsert() test method covering adapter support detection, default behavior, flag enabling, context manager usage, and cleanup. Note: Method appears duplicated in the file.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• Pass old to update on next, rename to upsert #685: Renamed the same upsert method this PR modifies (createOrUpdateDocumentsWithIncrease → upsertDocumentsWithIncrease), affecting the flow where sequence preservation logic is placed.
• Add createOrUpdateDocuments method and filter hooks for document upserts #663: Extends Mirror/Database upsert surface with similar delegation patterns for upsert-related behavior.
• Refactor getSequences #618: Modifies document-sequence handling in upsert flows by populating sequences, complementing this PR's preservation control logic.

Suggested reviewers

• abnegate

Poem

🐰 Sequences now dance at the keeper's will,
Preserved or released, whatever the thrill,
With flags and with methods both simple and neat,
The database's sequence preservation's complete!
Mirror reflects what the core declares true,
Context managers wrapping it all, tried and true. ✨

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 6.67% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately and concisely describes the main change: introducing a preserveSequence flag for upsert operations, which is the primary feature across all modified files.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@tests/e2e/Adapter/Scopes/GeneralTests.php`:
- Around line 305-314: The test currently only guards using
getSupportForUpserts(), but then calls createAttribute() which will fail on
schemaless adapters; update the guard to also check the adapter's attribute
support (e.g., call getAdapter()->getSupportForAttributes() or equivalent) and
if attributes aren't supported call $this->expectNotToPerformAssertions() and
return before invoking createAttribute(); ensure the new check is placed before
createAttribute() and references the existing getSupportForUpserts(),
createCollection(), and createAttribute() symbols so the test skips for adapters
that support upserts but not attributes.

[coderabbitai]

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In `@tests/e2e/Adapter/Scopes/DocumentTests.php`:
- Around line 1218-1237: The test uses an invalid literal sequence 999 which can
fail UUID7 adapters; change the upsert payload in the ignored-branch to supply a
valid sequence value (e.g., reuse $originalSeq1 or $originalSeq2) instead of 999
so validation passes even though setPreserveSequence(false) should ignore it;
update the Document creation passed to Database::upsertDocuments (the new
Document([... '$sequence' => ...])) to use the captured
$originalSeq1/$originalSeq2 while keeping the rest of the assertions intact.
- Around line 1225-1290: The test mutates the shared preserveSequence flag via
Database::setPreserveSequence() and leaves it false, risking cross-test state
bleed; modify the test to capture the prior state by calling $previous =
$database->getPreserveSequence() before changing it, wrap the operations that
change the flag (setPreserveSequence, withPreserveSequence, upsertDocuments,
deleteCollection) in a try/finally, and in the finally restore the original
value via $database->setPreserveSequence($previous) so the flag is always reset
even on assertion failures.