Skip to content

✨ feat!: the persistence eQuantic Space needs, on every engine - #13

Merged
edgarmesquita merged 105 commits into
masterfrom
feat/space-persistence-parity
Nov 14, 2026
Merged

edgarmesquita merged 105 commits into
masterfrom
feat/space-persistence-parity

Conversation

@edgarmesquita

@edgarmesquita edgarmesquita commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

Closes #12

eQuantic Space is moving its api off Prisma onto this library (eQuantic/equantic-space#701)... a spike against its tables and a count of every Prisma call it makes showed what the library could not express yet. This PR adds all of it, on every engine, each one through its own mechanism. The plan, requirements and scenarios are in the store: https://github.com/eQuantic/equantic-specs/tree/main/openspec/changes/core-space-persistence-parity

What a developer gets, on PostgreSQL, SQL Server, MySQL, MariaDB, MongoDB, Cosmos DB and Cassandra:

  • Column mapping. [EnumType] (or Enum<TEnum>()) stores an enum as its labels, compared and ordered by member value as in C#. JsonDocument, JsonElement and JsonNode members store any JSON, where before they were dropped without a word. [StoreGenerated] (or Generated(...)) leaves a member to the store: a sequence or its clock, read back on insert and never written by an update.
  • Upserts. UpsertAsync on the key or any unique key, atomic, returning the stored row, with a conflict filter for partial indexes. InsertManyAsync(..., skipDuplicates: true).
  • Write outcomes. DuplicateKeyException on every write path. Set-based writes count matched rows and take conditions on any member. UpdateAndGetAsync returns what it wrote. ModifyAsync(entity, members) writes only those members.
  • Query predicates. Filters across relations (Any, All, a reference's members, a missing reference) in reads and set-based writes, case-insensitive text, and an array's Contains under C# 14.
  • Named locks. AcquireLockAsync(name), through the store's own lock or a lease that never outlives its holder.
  • Read shapes. Filtered and ordered includes, relation counts in projections, nulls first or last, Skip and Take without a count, distinct values.
  • Model evolution. Snapshots record labels and store-generated members, and a migration never converts numbers to labels on its own... it writes the step to do by hand instead.
  • Analyzer. EQD012 to EQD014 flag what no engine can store.

Where an engine gives a weaker guarantee or a different cost, the provider guide says so, as the transactions guide already does.

Five reviews, one per area, found about 45 defects before this was opened, and four rounds of the secondary review on this PR found 29 more (the reviews below say which, and why each dismissed one is not a defect). Each fix came with a test that failed on the code before it. Two of them would have hurt the most: a lease that could have two holders when a renewal hung, and upserts that inserted a duplicate (an unset ObjectId on MongoDB, a generated key on PostgreSQL).

This is 7.0.0, because some existing calls change behaviour:

  • A taken key at commit or in a bulk load is now DuplicateKeyException, with the driver's exception as its InnerException. A catch on the driver's own exception no longer sees it.
  • MongoDB UpdateManyAsync returns the matched count, not the modified one.
  • MongoDB and Cosmos DB DeleteManyAsync honour soft delete, as the lifecycle guide always said.
  • A MySQL bulk load with a taken key fails as a whole, where it used to skip the row.
  • Cosmos DB writes refused by the ETag are ConcurrencyConflictException.
  • A MongoDB counter advances outside the open transaction, so a rollback leaves a gap in the numbers (as PostgreSQL's sequences do).
  • On Cassandra, an include or a relation read that names no partition needs .AllowFiltering(), as every other unscoped read already did.
  • Cassandra stores a plain enum as its number, where it used to refuse it.
  • The shipped dependencies carry no known advisory: MySqlConnector 2.6.2, System.Security.Cryptography.Pkcs 10.0.15, Microsoft.Azure.Cosmos 3.58.0.

One thing is left as it was on purpose. A compound negation like !(A && B) keeps SQL's three-valued logic, as before this PR.

Every suite ran against live containers on this branch, with nothing skipped: Core 294, Analyzers 17, PostgreSQL 177, SQL Server 90, MySQL and MariaDB 173, MongoDB 251, Cosmos DB 152, Cassandra 197.

BREAKING CHANGE: a taken key is DuplicateKeyException on every write path, MongoDB UpdateManyAsync returns the matched count, MongoDB and Cosmos DB DeleteManyAsync honour soft delete, a MySQL bulk load with a taken key fails as a whole, Cosmos DB ETag refusals are ConcurrencyConflictException, a MongoDB counter no longer rolls back with a transaction, and a Cassandra include or relation read with no partition needs .AllowFiltering().

…ers on every relational dialect

[EnumType] and Enum<TEnum>() store an enum as its labels: a PostgreSQL enum type, a MySQL/MariaDB ENUM(...) column, or SQL Server text held to the labels by a CHECK. JsonDocument, JsonElement and JsonNode members map to jsonb, JSON, or text checked as JSON. [StoreGenerated] and Generated(...) leave a member to the store (a sequence or its clock, or a SQL default), read it back on insert (RETURNING, OUTPUT INSERTED, or the row read by its key on MySQL) and never write it on update.
…t emulator

The vnext-latest emulator image now answers typed queries in a binary encoding that Microsoft.Azure.Cosmos 3.46.0 cannot read ("Unknown JsonNodeType"): 21 of the suite's 56 tests failed on it before any change here. The test project runs on 3.58.0; the provider still builds against 3.46.0.
…ers on MongoDB, Cosmos DB and Cassandra

[EnumType] and Enum<TEnum>() store an enum as its labels: a BSON string (the member's serializer, so the LINQ pipeline and a set-based write's filter and $set compare labels), a JSON string (a type-level converter the SDK's LINQ translation asks for constants), or a Cassandra text column bound as the label everywhere. Any other enum keeps its number; on Cassandra that is now its integral CQL type instead of a refusal.

JSON members are embedded as BSON and as JSON in the document, and held as JSON text on Cassandra.

[StoreGenerated] and Generated(...) leave a member to the store: an atomic counter ($inc on _sequences, Patch Increment on the _sequences container, a lightweight-transaction compare-and-set on equantic_sequences) and the server's clock (hello's localTime and GetCurrentDateTime() once per commit, toTimestamp(now()) in the Cassandra INSERT read back by the key). Updates keep them: a pipeline $replaceWith on MongoDB, a read and an If-Match replace on Cosmos DB, an INSERT or SET that leaves them out on Cassandra.
3.46.0 cannot read the binary query answers of the current vNext emulator. The suite ran on 3.58.0 while the package shipped 3.46.0; now what is tested is what ships.
…lational dialect

IUpsertRepository, IReturningUpdateRepository and IPartialModifyRepository are new capability interfaces every repository implements and DI resolves (open generics and the per-entity AOT path). DuplicateKeyException sits beside ConcurrencyConflictException.

UpsertAsync inserts or updates one row atomically, on the key or on members the store holds unique, with an optional update expression and conflict filter, and returns the row as stored: INSERT ... ON CONFLICT ... DO UPDATE ... RETURNING on PostgreSQL, MERGE ... WITH (HOLDLOCK) ... OUTPUT INSERTED on SQL Server, and on MySQL and MariaDB a locking read in a transaction, then the insert or the update, run again when a concurrent insert of the target wins. The insert takes the store's values for store-generated columns and the insert's stamps; the update never writes them and stamps UpdatedAt.

InsertManyAsync(items, skipDuplicates) inserts a batch in one transaction: ON CONFLICT DO NOTHING on PostgreSQL, a TRY...CATCH per row on SQL Server, and on MySQL and MariaDB one insert per row discarding only error 1062, because MySqlConnector reports found rows, under which ON DUPLICATE KEY UPDATE counts a skipped row as one written.

A taken key is DuplicateKeyException at commit, in a bulk load (MySQL's LOAD DATA LOCAL turned it into a warning; the load now runs in a transaction and fails), in a set-based update, an upsert and InsertManyAsync, naming the constraint or index. UpdateAndGetAsync returns the rows an update wrote (RETURNING, OUTPUT INSERTED, or a locking read in a transaction). ModifyAsync(entity, members) stages an update of the named columns only. The MySQL data source always reports found rows, so UpdateManyAsync counts the rows it matched.
UpsertAsync updates the target with findOneAndUpdate (returning the document after it) and, when nothing matches, inserts the entity with an upsert of $setOnInsert; when that upsert finds the target after all, or loses to a concurrent insert with E11000, the update runs again. With a unique index on the target ten concurrent upserts leave one document. The insert takes the counters' numbers and the server's clock and the insert's stamps; the update never writes store-generated members and stamps UpdatedAt.

InsertManyAsync(items, skipDuplicates) is an unordered insertMany discarding only E11000 (ordered without skipping, failing with DuplicateKeyException). E11000 becomes DuplicateKeyException at commit, in set-based updates, upserts, InsertManyAsync and returning updates, naming the index. UpdateAndGetAsync runs findOneAndUpdate per matching document, filtered on its id and the filter. ModifyAsync(entity, members) stages a $set of the named members.

The repository's set-based writes now go through MongoSet, like every other provider's: UpdateManyAsync counts the documents it matched (it counted the ones it modified, so a compare-and-set that wrote the same value read as a lost race), DeleteManyAsync on a soft-delete entity stamps DeletedAt (the repository deleted the documents), and UpdateManyAsync stamps UpdatedAt.
…es on Cosmos DB

UpsertAsync reads the target (by its id, or by a query inside the entity's partition) and then replaces it (or patches it with the update expression) under the _etag it read, or creates the entity; a lost race (412, 409) reads the target again. A container's unique key holds a target other than the id unique within a partition, and ten concurrent upserts of it leave one item. The create takes the counters' numbers and the server's clock; the replace keeps the stored key, creation stamps and store-generated values, and stamps UpdatedAt.

InsertManyAsync creates every entity concurrently, discarding only 409 when skipping duplicates. A 409 becomes DuplicateKeyException at commit (and a transactional batch with one), in InsertManyAsync, set-based updates and upserts. ModifyAsync(entity, members) stages a patch of the named members, guarded by the entity's _etag when it carries one.

UpdateManyAsync patched every item a query had matched with no condition: each item is now patched under the filter (PatchItemRequestOptions.FilterPredicate), so an item that stopped matching is left alone and the count is the patches applied — a compare-and-set. DeleteManyAsync deletes each item under the _etag of a read that still finds it matching (it deleted whatever the query had found), and soft-deletes a soft-delete entity as the other providers do. UpdateAndGetAsync returns the items the patches left. Set-based updates stamp UpdatedAt, as on every other provider.
…ut a total and distinct values on every engine

Include(x => x.Steps, s => s.Where(...).OrderByDescending(...).Take(3)) loads exactly those related entities per parent: a ROW_NUMBER() OVER (PARTITION BY fk) follow-up query on the relational dialects, a $lookup pipeline on MongoDB, and a second IN query over the related container or table on Cosmos DB and Cassandra, which now load includes instead of refusing them (PER PARTITION LIMIT where the clustering order serves the shape).

A relation count in a projection (x.Versions.Count(v => v.DeletedAt == null)) is counted by the store without loading the related entities: a correlated COUNT(*) subquery, a $lookup with $count, a grouped count query on Cosmos DB, and COUNT(*) GROUP BY the partition key on Cassandra (client-side behind AllowClientEvaluation where CQL cannot filter).

OrderBy(x => x.Position, NullsOrder.First) places nulls natively on PostgreSQL, by an is-null expression on SQL Server, MySQL and MariaDB, by an is-null flag on MongoDB, by splitting the read on Cosmos DB, and by a client-side sort behind AllowClientEvaluation on Cassandra. Skip/Take on QueryOptions page the plain reads with no count, and reads over every row refuse them. IDistinctReadRepository.GetDistinctAsync returns the distinct values of one or several members.
…es on Cassandra

UpsertAsync is a lightweight transaction: INSERT ... IF NOT EXISTS, and when the primary key is taken, an UPDATE ... IF EXISTS of the row it answered with (IF each value computed from the row still holds what was read, for x.N + 1 or the version). Cassandra holds nothing unique but the primary key, so an upsert on other members is refused with NotSupportedException, and a conflict filter the stored row does not match is a DuplicateKeyException. InsertManyAsync runs INSERT ... IF NOT EXISTS per row and counts the ones applied; without skipping, a stored primary key fails the call with DuplicateKeyException (a plain insert overwrites by definition, so these are Cassandra's refusals). ModifyAsync(entity, members) stages an UPDATE of the named columns.

UpdateManyAsync and DeleteManyAsync accepted only the primary key: conditions on other members now become the lightweight transaction's IF, per row the key finds (the partition key has to be in the filter), counting the writes Cassandra applied — a compare-and-set. An increment of a plain column, which CQL has no in-place form for and which was refused, is computed from the row read and written under IF column = value read. UpdateAndGetAsync runs every update that way and returns the rows as written. A lightweight transaction that times out under contention is settled with a serial read: a write of values set outright is written again when it did not apply, and one of a value computed from the row reaches the caller as a TimeoutException, since Cassandra cannot say whether it applied. Set-based updates stamp UpdatedAt and a soft-delete entity's DeleteManyAsync stamps DeletedAt, as on the other providers.
A new guide, Upserts and write outcomes, gives each engine's mechanism and guarantee for UpsertAsync, InsertManyAsync skipping duplicates, DuplicateKeyException, UpdateAndGetAsync and the member-scoped ModifyAsync. Commits and transactions says what a set-based write counts and when it applies (matched rows, each only while it still matches the filter, a lightweight transaction's IF on Cassandra); Optimistic concurrency shows the compare-and-set without a token and tells DuplicateKeyException from a concurrency conflict; each provider guide gains its line, and the contracts list the three capability interfaces.

MongoDB aborts a transaction on any write error, so InsertManyAsync skipping duplicates inside one now fails with DuplicateKeyException instead of counting the batch as inserted, and an upsert there does not retry into the aborted transaction. The AOT registration test resolves the capabilities from the per-entity path.
# Conflicts:
#	docs/guides/providers/sqlserver.md
#	tests/eQuantic.Core.Data.MySql.Tests/MariaDbTests.cs
An update of more than ten paths (a member-scoped Modify, a set-based update,
UpdateAndGetAsync, an upsert's update) was refused, ten being the paths Cosmos DB
takes in one patch. It now patches the item several times in one transactional
batch of its partition: the first patch carries the condition (the filter as
FilterPredicate, or the _etag), the batch's isolation keeps other writers out
until the last patch has applied, and a refusal leaves the item untouched. A
staged Modify inside an explicit transaction adds its patches to that batch.
InsertManyAsync(items, skipDuplicates: true) inside an explicit transaction failed
with DuplicateKeyException: MongoDB aborts a transaction on any write error, so the
duplicate-key errors an unordered insert discards outside one cannot be discarded
inside it. The batch is now checked first, inside the session: its _ids and the
values of every unique index listIndexes reports (sparse, partial and collated
indexes read as the server holds them) are looked up among the stored documents,
and the documents whose keys are taken, or repeat an earlier one of the batch, are
left out before anything is written. A concurrent writer taking a key in between
surfaces as MongoDB's transient write conflict, which the docs state.
… a lease

ILockingUnitOfWork.AcquireLockAsync(name, timeout) holds a named lock until its handle is disposed or, inside an explicit transaction, until the transaction commits or rolls back. Every unit of work implements it and the DI extensions register it, on the AOT registration paths too; no existing interface gained a member.

PostgreSQL takes pg_try_advisory_xact_lock inside a transaction and pg_try_advisory_lock on a pinned session outside one, on a bigint key that is the first eight bytes of the name's SHA-256, polled so a wait never aborts the transaction. SQL Server takes sp_getapplock owned by the transaction or by a pinned session, waiting on the server in slices and checking its result codes. MySQL and MariaDB take GET_LOCK, released by the engine right after the transaction ends since no transaction releases it; MySQL rounds its wait to whole seconds and compares lock names ignoring case, so upper-case and long names are keyed by their digest. MongoDB, Cosmos DB and Cassandra hold a lease written outside the transaction: a conditional findOneAndUpdate upsert on $$NOW with a TTL index, a create-or-409 with an ETag-guarded takeover once _ts plus the lease is past the server clock, and INSERT IF NOT EXISTS USING TTL with owner-conditioned renewals and deletes. Leases are renewed every third of NamedLockOptions.LeaseDuration (30 s by default), a dead holder's lease expires, and a lease that cannot be renewed signals the handle's Lost token.

A timeout throws TimeoutException, a cancellation throws OperationCanceledException and leaves no lock behind, and re-acquiring a held name is counted rather than locked twice.
MySqlConnector 2.4.0 -> 2.6.2 (GHSA-473q-m89c-ghf8). SqlClient 6.0.2 brings System.Security.Cryptography.Pkcs 9.0.4 (GHSA-846f-f764-76mx, GHSA-2fmv-rv2c-59x7); the SQL Server provider now references 10.0.15 directly. dotnet list package --vulnerable reports none for a shipped project.
…s Contains on the relational engines and MongoDB

A filter can cross the relations a model declares: x.Items.Any(...), !Any,
All, a reference's members (and a reference's reference), and a missing
reference (x.Container == null: no related row). RelationPredicates finds
these tests and hands each engine what it runs: on PostgreSQL, SQL Server,
MySQL and MariaDB a correlated EXISTS (the related entity's global filter
included), in reads, counts, set-based updates, deletes and UpdateAndGetAsync;
on MongoDB the related keys read first (one distinct per test, in the open
transaction's session) and an $in/$nin over them. A test that mixes the
related row with the entity's own members is refused with the reason.

Text matched without regard to case (string.Equals and Equals/Contains/
StartsWith/EndsWith with OrdinalIgnoreCase, and the same over ToLower()/
ToUpper()) becomes a TextFilter: lower() on both sides with the dialect's
wildcards escaped ('[' too on SQL Server), or an escaped case-insensitive
regular expression on MongoDB; a folded test whose value holds a letter of
the other case matches nothing, as in C#.

An array's Contains, which C# 14 binds to MemoryExtensions over a span, is
normalized to Enumerable.Contains before an expression reaches a driver or
the client-side residual.
…s Contains on Cosmos DB and Cassandra

A relation crosses containers on Cosmos DB and tables on Cassandra, which
neither can join: each test across one resolves first, reading the related
keys (SELECT DISTINCT VALUE over the related container; on Cassandra the
related rows under the read's own opt-ins, SELECT DISTINCT when the key is the
partition key), and the read, count or set-based write then takes an IN over
them (NOT IN, client-side on Cassandra, for a negated test). A set-based
write's patch condition on Cosmos DB holds the resolved keys; where the store
cannot evaluate the filter as a patch condition, each item is patched under the
_etag of a read that still matched. On Cassandra a write whose resolved keys
address the partition runs as any keyed write, and an update restricted to the
partition alone now updates the rows it finds by their full key.

Text without regard to case renders as STRINGEQUALS/CONTAINS/STARTSWITH/
ENDSWITH with their case-insensitive flag on Cosmos DB (string.Equals rewritten
to the instance form the SDK reads), and on Cassandra as a LIKE on a SASI index
declared case-insensitive (SearchIndex(..., caseInsensitive: true), or
[SearchIndex(CaseInsensitive = true)]), the gated client-side residual
otherwise. An array's Contains is normalized before the SDK sees it, and a
Cassandra IN on a column outside the primary key, which CQL refuses, runs
client-side.
…elation writes across partitions

On PostgreSQL a case-insensitive Contains, StartsWith or EndsWith renders as
ILIKE, which the trigram index a declared search index creates serves; the
other dialects keep LOWER() on both sides. On Cassandra the rows a conditional
write finds are read at SERIAL when the key restriction names one partition and
at the session's consistency when it names several (Cassandra takes a serial
read of one partition at a time), so a relation that resolves to several
partitions updates them all. MongoDB caches its navigation lookups and its plan
notes name the key read for what it is: an aggregation grouping on the key.
A querying guide for filters across relations (Any, All, a reference's members,
a missing reference) and text without regard to case, with each engine's
mechanism, cost and guarantee; a row in the pushdown table, a line in each
provider guide, and the set-based writes in the transactions guide. The Cosmos
DB patch paragraph moves below the table it had split.
…e engine created

MariaDB's catalogue reports an integer column with a display width the DDL never wrote (int(11), bigint(20)), so every integer column, a sequence-defaulted store-generated one and an enum stored as its number included, read as a type that differs on a schema the engine had just created. The width changes nothing stored and is dropped; tinyint(1) keeps its own, as this dialect writes a boolean with it. A MariaDB test now holds a schema with labels in an ENUM, JSON as LONGTEXT, a sequence's default and the clock's to no findings.
…ted members, and migrations hand both back

A snapshot recorded an enum's CLR type, so switching it between its numbers and its labels compared as no change on the relational stores, MongoDB and Cosmos DB, while every stored value became unreadable; on Cassandra it read as int to text, and the generated ConvertField would have written 1 as "1", never as its label. A member becoming store-generated, changing what the store assigns, or ceasing to be was no change anywhere.

FieldSnapshot now spells an enum stored as its labels labels:<enum full name> (labels:<enum>[] for an array or list of one), and carries Generated: sequence, clock, default <sql>, or null. Every provider's snapshot source fills both from what it actually writes: the dialect's native enums and RelationalColumn's store generation, the MongoDB member serializer and MongoModeling.StoreGenerated, the Cosmos DB model's label enums and [EnumType], Cassandra's text column of an enum and its generated columns. ModelSnapshotWriter writes Generated only where there is one, so an unchanged model writes the file it wrote before, and a snapshot committed before this compiles and compares clean.

ModelDiffer reports a label switch as a ConvertField and a generation change as the new ModelChangeKind.ChangeGeneration. MigrationWriter generates neither: each becomes a #error that says what the step must do on that store (an enum type and ALTER ... USING on PostgreSQL, through text on MySQL and MariaDB, nvarchar and its CHECK on SQL Server, every document on MongoDB and Cosmos DB, a new column on Cassandra; an identity, sequence object or AUTO_INCREMENT starting above the largest stored value, or the provider's counter set to it; the clock or SQL default and NOT NULL). eqdata migrations add counts the decisions from the written file.

The drift check already compared a label enum's column by the dialect's type; tests now hold PostgreSQL, MySQL and a new SQL Server drift fixture to reporting a column still holding numbers, and SQL Server and Cassandra to silence on a schema the engine created with both declarations.
…he written table

A set-based UPDATE or DELETE whose filter crosses a relation back to the written
table (a node filtered by its children) was refused by the store, error 1093.
On a dialect whose writes cannot read their own table (SqlDialect.
WritesReadTheirOwnTable, false on MySQL and MariaDB) the matching keys are now
read first, inside the operation's transaction (the open one, or its own), with
SELECT ... FOR UPDATE, and the statement writes by those keys with the filter's
other conjuncts still applied; UpdateAndGetAsync's update applies them too.
PostgreSQL and SQL Server keep the single statement. A self-referencing
scenario runs on every relational dialect, inside a transaction too.
A set-based write with a negated relation (!x.Items.Any(...), x.Container ==
null) was refused: a lightweight transaction's IF has no NOT IN. The write now
reads the rows the rest of its filter finds under the written table's
partition, leaves out those whose key the related read returned, and writes
each other row by its full key in a lightweight transaction holding the
filter's other conditions and every column the negated test read at the value
read (IF EXISTS when there is nothing else to hold); a row that changed is read
again and decided again. UpdateManyAsync, DeleteManyAsync and
UpdateAndGetAsync all take it.

The relation fixture lets the server stamp its writes: it writes the same rows
with plain statements and with lightweight transactions in quick succession,
which Cassandra orders by the client's and the coordinator's clocks, and the
test host and the container's VM keep different ones. The provider guide
states the rule.
…ation matrix lists the new vocabulary

EQD012: [StoreGenerated] on a member no store generates in that kind. EQD013: [StoreGenerated] on the key or the concurrency token. EQD014: an [EnumType] enum with an empty or repeated label. EQD011 now covers an empty [EnumType] name. The matrix gains [EnumType], [StoreGenerated], SearchIndex.CaseInsensitive and the JSON members, engine by engine.
Cassandra sets a cell's expiry to the write's time in whole seconds, truncated, plus the TTL, and the cell is live while the time in seconds is below it (ExpirationDateOverflowHandling.computeLocalExpirationTime, FBUtilities.nowInSeconds, ExpiringLivenessInfo.isLive). A lease written late in a second with its duration as the TTL expired almost a second early, so another holder could take the lock before the lease its holder was promised had run out: the dead-holder test saw a 2 s lease taken over after 1.2 s, about half the time. The TTL is now the duration rounded up to whole seconds plus that second.

Cosmos DB already measured a lease from the second after its _ts, and MongoDB compares milliseconds on the server's clock; neither expires early. The MongoDB fixture now waits for its replica set to elect a primary before the run: a write sent earlier was refused (not primary) or retried after the election, which a test timing its first write read as an early expiry. The dead-holder test passed 10 runs in a row on each lease engine. The locks guide states the bound: never before LeaseDuration, up to a second and a fraction after on Cosmos DB and Cassandra.
The release job exchanges its GitHub OIDC token for a one-hour nuget.org key (NuGet/login, under the policy bound to this repository, release.yml and the nuget environment), as core-payment does. No long-lived key is read: NUGET_KEY now comes from the login step, and release-verify.sh points at the policy and the NUGET_USER secret when it gets none.
…llers stopped waiting is created again on the next use

@edgarmesquita edgarmesquita left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Secondary review, round 2 (Antigravity, gemini-4-argon-medium and gemini-3.8-flash-medium), because Copilot could not be requested on this repository.

Round 1 sent each area whole and Antigravity cut the prompts at about 190 KB, so it read roughly half of each area (and Cosmos DB and Cassandra not at all). This round ran in ten chunks of at most 150 KB of diff each, so every changed source file was read.

33 findings: 11 fixed, 22 dismissed, each dismissal with its evidence. Four dismissals are backed by tests added for them (9e1c508, 24b4fa8, 0f768d8, abfded7).

These sit outside the diff's hunks:

  • MongoUnitOfWork.cs:239 [high]: A [StoredAs] concurrency token filtered by its CLR name was claimed. Not a defect: A_token_stored_under_another_name_guards_every_replace_and_delete (0f768d8) shows replace and delete match the stored field and a stale write conflicts.

var entities = items as IReadOnlyList<TEntity> ?? items.ToList();
if (entities.Count == 0)
{
return 0;

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[high] InsertManyAsync started every create at once (201 in flight in the test).

Fixed in e85d70a: at most 32 at once, with an exact count (test Inserting_many_keeps_a_bounded_number_of_requests_in_flight_and_counts_every_create).

// columns from the entity: the stamp's assignment takes their place).
foreach (var stamp in EntityLifecycle.UpdateStamps(typeof(TEntity), _unitOfWork.Conventions, _unitOfWork.Services))
{
if (_configuration.ColumnFor(stamp.Name) is not { } column

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[high] An upsert's update left a NULL concurrency token at NULL (NULL + 1).

Fixed in 20e3da1, on PostgreSQL, SQL Server, MySQL and MariaDB (test An_upsert_advances_a_token_the_row_holds_unset).

{
// Deleted only if it is still this unit of work's, so the fresh attempt (another owner) is not kept
// waiting by a lease of its own. A cancelled wait leaves the release to finish on its own (it never throws).
await ReleaseQuietlyAsync(lost.Native, name).WaitAsync(cancellationToken).ConfigureAwait(false);

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[high] An entry was added and held in two separate locked steps, and the race's loser read the entry after an await (KeyNotFoundException).

Fixed in c206a65 (test Two_flows_that_take_one_name_at_once_share_it_and_the_first_to_let_go_leaves_it_held).

}

foreach (var stamp in EntityLifecycle.UpdateStamps(typeof(TEntity), _unitOfWork.Conventions, _unitOfWork.Services))
{

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[high] A stale lostCreate or an empty target was claimed.

Not a defect: MemberSelection.Members refuses new { }, so the target is never empty, and lostCreate is rethrown only when the re-read finds no target.


// The conflict filter names a partial unique index's predicate, which PostgreSQL matches when it plans the
// statement: written with its values in place, it still matches once the driver has prepared the statement and the
// store plans it once for any value — bound as parameters, it matched nothing after a few executions.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[high] An unqualified conflict filter in MERGE was claimed.

Not a defect: the MERGE source columns are [__eq_onN] (SqlServerDialect.cs:155), so unqualified columns bind to the target, and RenderInlined gets no relations (a relation test is refused). UpsertWithConflictFilter runs it on SQL Server.

var array = Array.CreateInstance(member.Type, satisfying.Count);
for (var index = 0; index < satisfying.Count; index++)
{
array.SetValue(satisfying[index], index);

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[medium] A nullable enum array that throws was claimed.

Not a defect: EnumOrderTests runs x.Escalation, a Priority?.

private static object? Added(object? current, CollectionAddAssignment add)
{
var items = Items(current);
var incoming = add.Unique ? add.Items.Where(item => !items.Contains(item)).Distinct().ToList() : add.Items.ToList();

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[medium] Exotic numeric types were claimed.

Not a defect: UpdateInterpreter.IsNumericMember (line 216) admits only primitive numerics.


// Every wait of the renewal loop ends with _stop, a renewal still in flight included: this never waits on it.
await _renewal.ConfigureAwait(false);
_stop.Dispose();

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[medium] A double dispose was claimed.

Not a defect: release runs once per lock (the set removes the entry under its gate first), and the Lost token handed out must stay usable.

/// <summary>
/// Declares a member whose value the store assigns on insert, as <see cref="Modeling.StoreGeneratedAttribute" />
/// does: the next number of an atomic counter for an integral member (<c>findOneAndUpdate</c> with <c>$inc</c> on
/// the <c>_sequences</c> collection, inside the open transaction), the server's clock for a date (read once per

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[low] The comment said the counter advances inside the open transaction.

Fixed in 4e51231 (the comment now says it advances outside it).

/// <summary>
/// Named locks on MySQL and MariaDB: <c>GET_LOCK(name, seconds)</c>, a lock the <b>session</b> holds, which no
/// transaction releases. Outside a transaction it is taken on a pinned connection and released by
/// <c>RELEASE_LOCK</c> when the handle is disposed; inside one it is taken on the transaction's connection and

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[low] A contradiction in the doc comment was claimed.

Not a defect: the library calls RELEASE_LOCK after commit or rollback, since ReleasedWithTransaction is false, which is what the comment says.

… numbers exactly, as the index does, past 15 digits and 2^53
…ay keeps the JOIN the SDK writes before its WHERE
…refused by name instead of failing in a dictionary
…t, and a match against null is refused by name
… on every engine, and MongoDB's compares labels by value
…ne instead of declaring the entity's own member of that name

@edgarmesquita edgarmesquita left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Secondary review, round 3 (Antigravity, gemini-4-argon-medium), because Copilot could not be requested on this repository. As in round 2, it ran in chunks of at most 150 KB of diff, ten for the sources and one for the release workflow, so every changed file was read.

23 findings: 12 fixed, 6 dismissed with their evidence, 5 repeating claims round 2 already settled. This is the last full round. Since it led to fixes, one more round will review those fixes alone.

These sit outside the diff's hunks:

  • MongoModel.cs:256 [medium]: A serializer registration silently ignored was claimed. Not a defect: TryRegisterSerializer throws on a different serializer, proven by An_enum_already_stored_as_its_number_cannot_be_declared_labels_afterwards.

protected override Expression VisitMember(MemberExpression node)
{
// x.Versions.Count (List<T>, ICollection<T>, IReadOnlyCollection<T>) and x.Versions.Length (arrays).
if (node.Member.Name is "Count" or "Length"

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[high] An array's Length compiles to an ArrayLength node, so x.Versions.Length was never counted.

Fixed in b042e05 (test The_length_of_an_array_relation_is_a_count).


if (visited is { Object: null, Method.Name: nameof(string.Equals), Arguments.Count: 3 })
{
var (member, value) = Reads(visited.Arguments[0]) ? (visited.Arguments[0], visited.Arguments[1]) : (visited.Arguments[1], visited.Arguments[0]);

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[high] A text equality with no member threw NullReferenceException, and with a null value or two members it returned wrong rows, its negation inverted.

Fixed in fd18de6 (test A_text_equality_meets_a_null_as_the_engines_read_it).

/// </summary>
private string WhereClause(Expression<Func<TEntity, bool>> filter)
{
var text = _queryable.Where(filter).ToQueryDefinition().QueryText;

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[medium] The SDK writes JOIN … AS v0 WHERE v0 for an embedded-array test, and the patch condition dropped the JOIN, so every such set-based write failed with 400.

Fixed in 39206dc (test A_set_based_write_whose_filter_reads_an_embedded_array_writes_the_items_it_matches).


private IQueryable<TEntity> TargetQuery(TEntity entity, IReadOnlyList<string> on,
Expression<Func<TEntity, bool>>? conflictFilter, PartitionKey partitionKey)
{

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[medium] A relation in an upsert's conflict filter was read as an embedded member, so the upsert inserted a second row.

Fixed in 3b27dbb: a relation in a conflict filter is refused on all six engines (test An_upsert_s_conflict_filter_that_crosses_a_relation_is_refused). Skipping the global filter is documented (multi-tenancy.md:51).

}

inserting = entity.ToBsonDocument(typeof(TEntity));
if (on is null)

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[medium] The conflict filter skipped MongoPredicates, so a label-enum ordered comparison compared label text and a relation inserted a duplicate.

Fixed in 3b27dbb (test An_upsert_s_conflict_filter_means_what_it_means_in_any_filter). The _id part repeats round 2 (abfded7), and the global-filter part is documented (multi-tenancy.md:51).

@@ -260,7 +334,21 @@ private ReplaceOneModel<TEntity> VersionedReplace<TEntity>(TEntity item, bool up

var filter = Builders<TEntity>.Filter.And(IdFilter(item),
Builders<TEntity>.Filter.Eq(new StringFieldDefinition<TEntity, long>(token.Name), current));

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[medium] VersionedReplace filtering by the CLR name was claimed again.

Repeat of round 2: A_token_stored_under_another_name_guards_every_replace_and_delete (0f768d8).

}, cancellationToken).ConfigureAwait(false);
}

private string CountSql(RelationCount count, int index, string parentTable, List<object?> parameters)

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[medium] A relation count ignoring the related global filter, and nested relations, were claimed.

Repeat of round 2 for the global filter. A nested relation is refused by SqlFilterRenderer ("has no mapped member").

IncludeShape shape, CancellationToken cancellationToken)
{
var dialect = unitOfWork.Dialect;
var filter = shape.Filter is null ? null : FilterInterpreter.Interpret(shape.Filter);

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[medium] An include ignoring the related global filter was claimed again.

Repeat of round 2: the global filter is not applied by any engine, and a relation inside an include filter is refused.

/// <summary>Whether a comparison is lifted: the compiler typed one of its sides nullable.</summary>
private static bool Lifted(BinaryNode binary) => Nullable(binary.Left) || Nullable(binary.Right);

private static bool Nullable(ExpressionNode node) => node switch

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[medium] A missed nullable lift was claimed again.

Repeat of round 2: A_negated_comparison_with_a_captured_nullable_value_keeps_the_rows_whose_member_is_null (9e1c508).

/// A LOGGED BATCH cannot carry a lightweight transaction alongside other partitions' writes — Cassandra
/// restricts conditional batches to a single partition. The combination refuses instead of degrading.
/// </summary>
private void GuardConditionalInTransaction<TEntity>(CassandraEntityConfiguration configuration)

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[low] A duplicated guard was claimed to diverge.

Not a defect: the two guards behave the same.

…the relational engines too

x.Name.ToLower() == null (and !=, ToUpper, the invariant forms, null on
either side) is now the member's IS NULL / IS NOT NULL on PostgreSQL, SQL
Server, MySQL and MariaDB, and x.Name.ToLower().Equals(null) holds for no
row, as MongoDB, Cosmos DB, Cassandra and the residual already read them.
The relational engines refused both forms, so the same expression answered
on one engine and failed on another.

A live test asserts the forms on all seven engines, rows with a null and a
non-null member, and predicates.md says the rule holds on every store.
…lations counts with them on every engine

A projection's x.Steps.Count(s => s.Logs.Any()) or Count(s => s.Runner.Name
== v) was answered differently by each engine: the relational engines
refused it with "'ShapeStep' has no mapped member 'Logs'", MongoDB and Cosmos
DB read the relation as an embedded member and answered a wrong count without
a word, and Cassandra failed in the driver on a column that does not exist.

The count's filter now resolves its relations as a filter's are: a
correlated EXISTS inside the count's subquery on the relational engines, the
related keys read first and an $in / IN over them on MongoDB (a $lookup
inside the count's past the bound), Cosmos DB and Cassandra (under the read's
opt-ins).

Cassandra's planner no longer pushes down an IN on a clustering column whose
preceding clustering column is unrestricted, which CQL refuses with or
without ALLOW FILTERING: such a conjunct (keys.Contains(x.Id) on a table
clustered by another column first) runs client-side behind the opt-in.

A live test counts collection, negated, reference, null and combined tests
on all seven engines, and projections.md states the rule.

@edgarmesquita edgarmesquita left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Secondary review, round 4 (Antigravity, gemini-4-argon-medium), because Copilot could not be requested on this repository. Round 3 led to fixes, so this round reviewed those fixes alone: the diff from b70982d (the commit round 3 read) to this one, which also carries the three loose ends closed after it (a folded text compared with null on the relational engines, a relation inside a relation count's filter on every engine, and a Cosmos DB suite run six times in a row to check it is not flaky).

2 findings: 0 fixed, 2 dismissed, each with its evidence below. The review closes with this round.

case (true, true):
// Two members: C# holds two nulls equal and a null unequal to any text, where STRINGEQUALS answers
// undefined. Written so that it is never undefined, it reads the same under any negation.
if (equals.Object is not null)

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[medium] x.A.Equals(x.B, StringComparison.OrdinalIgnoreCase) between two members is sent as STRINGEQUALS, which is undefined when one side is null.

Not a defect here. Alone it excludes the row, as C#'s false does, and negated directly it keeps the row (the null guard), as C#'s true does. Only inside a compound negation such as !(x.A.Equals(x.B, …) && x.Flag) does the undefined drop the row, and that is the rule this PR keeps on purpose for every engine: a compound negation follows the store's three-valued logic (stated in the PR body and in docs/guides/querying/predicates.md).

return unreachable;

// "column IN (" / "column = ?" as a whole name: "id" is not the end of "runnerid".
static bool Restricts(string clause, string column, string relation) =>

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[medium] The check that finds an unreachable IN matches column = ? and column IN ( but not a quoted identifier such as "col" = ?.

Not a defect: the Cassandra renderer never quotes a column name (nothing in src/eQuantic.Core.Data.Cassandra writes an identifier in quotes, and columns are snake_case), so a clause this check reads never holds "col". The lookbehind's " only keeps it from matching inside a longer name.

@edgarmesquita
edgarmesquita merged commit aa5830c into master Nov 14, 2026
10 checks passed
@github-actions

Copy link
Copy Markdown

🎉 This PR is included in version 7.0.0 🎉

The release is available on:

Your semantic-release bot 📦🚀

@edgarmesquita
edgarmesquita deleted the feat/space-persistence-parity branch November 14, 2026 22:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

The persistence eQuantic Space needs, on every engine

2 participants