docs(adr): 0006-simulation-semantics#94
Merged
Merged
Conversation
Closes #64. `verisimdb_simulation_branches` + `_deltas` tables exist but the semantics were undocumented. Without that, `simulate branch`, `simulate merge`, `simulate diff` would diverge across implementations. ADR-0006 pins: - **Branch creation**: `main` is implicit, new branches off any parent, frozen at branch-creation time (no auto-pickup of parent changes; rebase is OQ-1). - **Delta isolation**: snapshot isolation. Reads in branch see parent at branch start + own deltas. No sibling-branch leakage. - **Merge policy**: manual by default; `--strategy last-writer-wins` and `--strategy abandon-on-conflict` are opt-ins. **No CRDTs** — the data model is application-defined SQL rows, not CRDT primitives; faking CRDT semantics over arbitrary SQL is unsound. - **Conflict reporting**: structured `MergeConflict` per conflicting `(entity_id, table_name)` with branch_value, target_value, `target_provenance` (hash from provenance log, enabling audit of who last touched the target). - **Target-DB integration**: branch creation is sidecar-only; merge against `main` wraps in a target-DB transaction; merges are atomic (SAVEPOINT on sidecar, transaction on target). - **Lifecycle**: `active → merged | abandoned`; storage-layer CHECK from V-L2-J1 already enforces this. Three open questions called out for follow-up ADRs (rebase, cross-branch references, merge-as-provenance). Cross-references ADR-0004, V-L2-J1 (#43, merged), V-L2-P1 (#50), and the existing simulation DDL + CLI surface. Doc-only. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Per V-L1-F1: simulation tables exist but had no documented semantics. ADR-0006 pins:
mainimplicit; new branches frozen at branch-creation time (rebase = OQ-1).--strategy last-writer-winsand--strategy abandon-on-conflictopt-ins. No CRDTs — faking CRDT semantics over arbitrary SQL is unsound.MergeConflictrows withtarget_provenance(hash from provenance log) so the user can audit who last touched the target value.mainwraps in a target-DB transaction; SAVEPOINT on sidecar makes merges atomic.active → merged | abandoned; V-L2-J1 enum CHECK already enforces.Three open questions called out (rebase, cross-branch refs, merge-as-provenance).
Closes
Test plan
docs/decisions/0006-simulation-semantics.adocwith all five sections (branch / delta / merge / conflict / transactions) + lifecycleverisimiser simulate …CLI workDoc-only.