halkyon-days/serverpod-offline-sync
Watch
1
0
Fork
You've already forked serverpod-offline-sync
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

test: Harden DST authored-state checks and workloads (#123)

Browse source
This commit is contained in:
Marcelo Mendonça Soares 2026-09-17 10:39:07 -03:00 • committed by GitHub
commit ad3e1a49e4
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 10312 additions and 458 deletions
Download patch file Download diff file Expand all files Collapse all files

42
docs/unique-constraint-invariants.md
View file

@ -20,6 +20,20 @@ This is the `flag` policy. It is intentionally simple:
This policy is the only unique-conflict policy in space for the current
implementation.
## Local writes
Local inserts, updates, upserts, and restores obey the database's unique
constraints. Two records cannot claim the same occupied value or non-null
composite tuple in one local write. The database enforces this against stored
rows and other rows in the batch; no additional domain reads are needed to
pre-check uniqueness. A rejected write rolls back its domain changes and sync
metadata together. Ordinary `ignoreConflicts` and upsert predicates still apply.
Claims accepted independently on disconnected replicas can still conflict when
merged. The policy below preserves those accepted claims and chooses their
visible values. Passing an unchanged displayed alternative through a full-row
save preserves the underlying claim and follows the normal field-touch rules.
## Current Policy: Flag
Candidate construction, hidden-row release, canonical attempted-value lookup,
@ -64,6 +78,34 @@ non-null constraint, the FK constraint, or the unique constraint itself.
The rewritten value is a materialized data value, not a synced conflict class.
The core CRDT protocol does not need to expose unique conflict objects to users.
### Reserved generated values
Authored values in unique text columns must not end in
`__conflict__<UUID>`, `__hidden__<UUID>`, or `__park__<UUID>`, where the UUID uses
the hexadecimal `8-4-4-4-12` shape. The marker is lowercase; hexadecimal letters
can use either case. These names belong exclusively to projection, including
hidden-row release and temporary writes. Non-unique text is unrestricted.
Non-nullable unique UUID columns that are not foreign keys reserve UUID version
8 for generated alternatives (`xxxxxxxx-xxxx-8xxx-xxxx-xxxxxxxxxxxx`). Conflict,
hidden-row, and temporary parking values use the same deterministic hash inputs
as before, with the version marker set to 8. Authored version-8 values in these
columns are rejected; ordinary UUID versions, including 4, 5, and 7, remain
supported. Primary keys, foreign keys, nullable UUID columns, and non-unique UUID
columns do not use synthetic UUID release and are not subject to this rule.
Local writes and incoming sync facts enforce this rule with
`OfflineSyncReservedValueException`. Rejected transactions do not advance
authored data or sync progress. A full-row update/upsert can echo its own
unchanged materialized alternative: it keeps the original authored claim and
uses the normal field-touch semantics. Explicitly authoring an alternative on
another record is rejected, including exchanges of displayed alternatives.
This keeps the existing deterministic text suffix construction. The resolver does
not search currently occupied values for a free alternative. The original claim
is what gets exported, so ordinary conflict projection and bootstrap remain
valid under the input rule.
## Why Flag Is The Current Default
The `flag` policy avoids the hard second-order effects caused by hiding or