Repository navigation
docs: update READMEs for apply package - #18
Merged
Merged
Conversation
The top-level README described the module as two packages. The apply package is now a first-class part of the module and needs to be surfaced there: added to the package list in About, added to the Documentation section, and given a Getting Started example showing how to wire up a TupleClient and call Execute end-to-end. The apply package README had two stale sections after recent bug fixes. The Validate Check 2 description now correctly states that only patch filter scopes count as coverage — delete filter scopes are excluded because a delete filter cannot write a tuple. The Conflict Detection section gains a third scenario documenting the overlapping-patch conflict: two operations sharing the same filter scope each desiring a different subset of stored tuples, where satisfied desires would otherwise be invisibly deleted.
There was a problem hiding this comment.
🟡 Changes recommended
The examples can apply partial results, omit required write ordering, and conflict with documented prefix-filter semantics.
4 open findings
What changed in this PR
Updates documentation to present apply as a first-class package and explain its reconciliation behavior.
Changes:
- Adds
applyusage and references to the root README. - Documents conflict detection and patch-filter validation updates.
| File | Description |
|---|---|
README.md |
Adds package overview and store-writing example. |
apply/README.md |
Updates validation and conflict documentation. |
🧠 Review effort: Balanced
Give feedback about Copilot approvals in this survey to enter a drawing for a $150 gift card.
Fix four issues in the README examples and apply/README.md: - The Writing to a store example continued to Execute after Evaluate returned an error; a failed evaluation returns a partial result that can write incomplete state, and a nil result causes Execute to panic. Add an explicit return after the error. - The WriteTuples stub gave no hint about the delete-before-write ordering requirement; condition changes fail with TupleConditionConflictError when deletes and writes are batched together. Add a comment calling this out. - Validate Check 2 used object: "org:" as a filter example with object: "org:acme" desired, presenting a valid type-filter match as a scope mismatch. Replace with object: "org:1" / object: "org:2", an unambiguous genuine mismatch. - The conflict detection ordering description said it iterates combined in slice order, which is only the second stage. Satisfied-claim conflicts are checked first. Document the two-stage order.
sergiught
approved these changes
Oct 8, 2026
Merged
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.
Description
The top-level README described the module as two packages. The apply package is now a first-class part of the module and needs to be surfaced there: added to the package list in About, added to the Documentation section, and given a Getting Started example showing how to wire up a TupleClient and call Execute end-to-end.
The apply package README had two stale sections after recent bug fixes. The Validate Check 2 description now correctly states that only patch filter scopes count as coverage, delete filter scopes are excluded because a delete filter cannot write a tuple. The Conflict Detection section gains a third scenario documenting the overlapping-patch conflict: two operations sharing the same filter scope each desiring a different subset of stored tuples, where satisfied desires would otherwise be invisibly deleted.
References
Review Checklist
main