docs(walkthrough): add §5.2 comparing none / warn / exclusive policies#25
Merged
Conversation
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
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.
Purpose
Give operators an explicit decision table for
--policy(none,warn,exclusive) so downstream projects do not invent their own avoidance guidance. Theassign updatePR (#24) surfaced a recurring failure mode: a downstreamAGENTS.mdsteered workers away fromexclusiveon race grounds, but the race in question was closed by v0.1.2'sBEGIN IMMEDIATEtransaction. Without a kernel-side comparison, each consumer reverse-engineers policy semantics from SPEC §15 and §28 separately, and stale guidance persists across consumer repos.Summary of changes
docs/walkthrough.md§5.2 "Choosing a conflict policy" with a per-policy table covering overlap detection, outcome, lock sentinel, and an operator-facing "when to use" column.internal/domain/domain.goResolveAndInsertIntent) and a pointer to thetests/integration/concurrent_test.gosuite that keeps the guarantee honest under-race.AGENTS.mdstill avoidsexclusiveon race grounds: verify the installedagent-ledger --versionis at least v0.1.2 and update local guidance.<ledger-dir>/locks/<path-hash>.locksentinel is advisory (DB row is authoritative per SPEC §28) and is housekeeping for the verifier, not a public API.Changes to review
docs/walkthrough.md§5.2: confirm the table's "when to use" column matches how you actually want operators to choose between the three policies.