Repository navigation
docs(spec): state list order as one rule - #474
Merged
Merged
Conversation
…e orders getVersions() reads newest first and getJournal() oldest first, and nothing in the spec said this was a choice. State it as one rule: a paged history read starts at the end its reader needs first. Version history is browsed back from the present for a recent restore point; the journal is tailed and replayed, which only a forward cursor can do. Everything else about the two reads shares one shape. Also covers parseVersionsParams() with tests mirroring parseJournalParams(). Closes #472. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XRRrTNc31HrcBZo1FnWDPd
|
Generalize the rule from history reads to every list: a list starts at the end its reader needs first, and a paged list's cursor walks away from it. It now sits in data-model.md § List order beside the table, which gives each row its reason, including listTypeGrants(), which inherits the unsorted query() default. Versioning and Journal each keep a one-line reason for their own read, and the duplicated "one shape" prose is gone. parseVersionsParams() tests now mirror parseJournalParams(): repeated params, malformed values, and zero, which the parser accepts and Stack refuses. Also corrects a journal test name that claimed assertValidJournalQuery allows limit 0. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XRRrTNc31HrcBZo1FnWDPd
cuibonobo
changed the title
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.
Summary
Closes #472.
getVersions()reads newest first andgetJournal()oldest first, and the spec never said this was deliberate. This adds one rule that covers every list, not just those two: a list starts at the end its reader needs first, and a paged list's cursor walks away from that end.The rule sits beside the order table in
data-model.md, and each row now gives its reason:query()with no sort reads newest first, the order a feed-style listing reads in. With a sort, the caller names the end itself.getVersions()reads newest first, because a restore point is almost always a recent one.getJournal()reads oldest first, because a log is tailed and replayed, and a backward cursor can't catch up.getAttachmentRecords()reads oldest first, sorecords[0]is the record that establishes themimeType.listTypeGrants()reads newest first because it is aquery()with no sort and inherits that default.Tests:
parseVersionsParams()now gets the same cases asparseJournalParams(). The zero case pins the existing split, where the parser checks the format andStackchecks the range. Also fixes a journal test name that saidassertValidJournalQueryallowslimit: 0.Spec
No behavior change. Documents existing behavior:
docs/spec/data-model.md § List order(the rule and the table, moved to the end of § Sorting and pagination)versioning.md § Version historyandjournal.md § Reading iteach give a one-line reason for their own read and link to the table.wire-format.md § Versionslinks to it too.Verification
pnpm run format:check,check:refs,lint,test,build,typecheck: all pass locally.Notes for reviewers
We considered aligning both history reads on oldest first with
afterVersionand decided against it. Nothing tails version history, and the common case (the last few restore points) would have needed arithmetic onrecord.version.The wire parser accepts
beforeVersion=0andStackrefuses it with the same 400. Making the parser enforce the range would make it the only parser that does, so that's left as is. No changeset: docs and tests only.🤖 Generated with Claude Code
https://claude.ai/code/session_01XRRrTNc31HrcBZo1FnWDPd