From 6892b206ab6bad70f989e42320d418391b2a32d2 Mon Sep 17 00:00:00 2001 From: Nils Lehnen <30603423+iderex@users.noreply.github.com> Date: Fri, 18 Sep 2026 16:16:51 +0200 Subject: [PATCH] Decide what next up is in terms of the page and the item, and give the module it 0039 refused next up rather than deciding it, on one fact about the register: the route was in no capability of the record that fixed the server surface. It wrote the condition that would end the refusal into its own last section, and 0272 met that condition on 2026-09-01 by superseding 0010 with a table carrying `next-up` at `GET /Shows/NextUp`. Nothing answered what 0039 said was then owed, and the refusal stood for more than two weeks after the fact it rested on. 0385 carries the statement: next up is a paged library read answering with the page and the one item type 0039 fixes, a fifth member of the set rather than a fourth answer shape. 0272 took the readings that decide it - the envelope is the one `GET /Items` and `GET /UserItems/Resume` already answer with, and both paging parameters and the total flag are on the route on both supported lines - so this record says as a decision what that one concluded inside a section about a table. 0039 gains the pointer 0001 permits to a later record going further on a case it names, and nothing else in it moves. `src/server/library.rs` gave the refusal's reason in its own prose and now gives what next up is. `LibraryRead` holds it as the fifth read, answering with a page asked for by an offset and a count, and the two tests over that enumeration cover it. The module also says, as `tests/fake_server/surface.rs` already does, that a comment naming 0010 is pointing at where a reading lives rather than at the record in force. What this prevents is whoever writes the first next-up read meeting a module saying the capability does not exist, and settling a question two records deferred inside a change about something else, with a green gate to show for it. Closes #385 Signed-off-by: Nils Lehnen <30603423+iderex@users.noreply.github.com> --- ...e-page-the-item-and-what-next-up-is-not.md | 8 +- ...up-is-in-terms-of-the-page-and-the-item.md | 162 ++++++++++++++++++ docs/decisions/README.md | 1 + src/server/library.rs | 56 ++++-- 4 files changed, 211 insertions(+), 16 deletions(-) create mode 100644 docs/decisions/0385-what-next-up-is-in-terms-of-the-page-and-the-item.md diff --git a/docs/decisions/0039-the-page-the-item-and-what-next-up-is-not.md b/docs/decisions/0039-the-page-the-item-and-what-next-up-is-not.md index e5d9a86..18bed53 100644 --- a/docs/decisions/0039-the-page-the-item-and-what-next-up-is-not.md +++ b/docs/decisions/0039-the-page-the-item-and-what-next-up-is-not.md @@ -224,7 +224,13 @@ which 0010 names in its own words as how a surface grows by accident. So next up is one of two things and neither is this record's: either 0010 is superseded by one whose table carries `GET /Shows/NextUp`, with the argument for -it made there, or #39's scope loses next up and says so. This record states which +it made there, or #39's scope loses next up and says so. + +0272 took the first of those on 2026-09-01 and 0385 goes further on this case +with the statement the last section of this record says is owed: next up is a +paged library read answering with the page and the one item type fixed above. +The reasoning, the readings it rests on and what it costs are in that record. +Nothing else in this one moves. This record states which of #39's conditions that reaches: none of them. The three conditions are a test per call against a recorded fixture, paging proven across a boundary, and one item type across the calls, and each is about the calls that exist rather than about diff --git a/docs/decisions/0385-what-next-up-is-in-terms-of-the-page-and-the-item.md b/docs/decisions/0385-what-next-up-is-in-terms-of-the-page-and-the-item.md new file mode 100644 index 0000000..e998385 --- /dev/null +++ b/docs/decisions/0385-what-next-up-is-in-terms-of-the-page-and-the-item.md @@ -0,0 +1,162 @@ +# 0385. What next up is, in terms of the page and the item + +Date: 2026-09-18 + +Status: accepted. Supersedes nothing. Superseded by nothing. + +Issue: #385 + +## The decision + +Next up is a paged library read answering with the page and the one item type +[0039](0039-the-page-the-item-and-what-next-up-is-not.md) fixes, read from +`GET /Shows/NextUp` under the `next-up` capability +[0272](0272-the-route-next-up-is-read-from.md)'s table carries, so it is a fifth +member of the set of library reads and not a fourth answer shape. + +## What 0039 left owed, and why it could not answer it + +[0039](0039-the-page-the-item-and-what-next-up-is-not.md) refused next up rather +than deciding it, on one fact about the register: the route was in no capability +of the record that fixed the server surface, and a path added in the record that +describes the reads rather than in the record that fixes them is how a surface +grows by accident. It named the two shapes an answer could take and said the +answer would come from outside it, and it wrote the condition down in advance: + + git show origin/main:docs/decisions/0039-the-page-the-item-and-what-next-up-is-not.md \ + | grep -n -A3 '^0010 is superseded by a record whose capability table' + 300:0010 is superseded by a record whose capability table carries a next-up path. This + 301-record's last section is then answered from outside it, and what is owed is a + 302-statement of what next up is in terms of the page and the item, which is the half + 303-this record deliberately does not write. + +[0272](0272-the-route-next-up-is-read-from.md) supersedes +[0010](0010-the-server-surface-and-what-an-absence-does.md) and its table carries +the row, so the fact the refusal rested on stopped holding on 2026-09-01: + + git show origin/main:docs/decisions/0010-the-server-surface-and-what-an-absence-does.md | sed -n '5p' + Status: accepted. Supersedes nothing. Superseded by 0272. + git show origin/main:docs/decisions/0272-the-route-next-up-is-read-from.md | grep -n 'The seventeenth is' + 19:The seventeenth is `next-up`, read from `GET /Shows/NextUp`. + +## Why the answer is the ordinary one + +[0272](0272-the-route-next-up-is-read-from.md) took the readings that decide this +and its own text states the conclusion, so what is left here is to say it as a +decision rather than as a paragraph inside a record about a table. The envelope +is the one two of the three existing paged reads already answer with: + + git show origin/main:docs/decisions/0272-the-route-next-up-is-read-from.md | sed -n '138,141p' + `QueryResult` - the same one `GET /Items` and `GET /UserItems/Resume` + answer with - so the core's promise that a client written against one read can + display the result of another survives this row untouched, because nothing new is + being mapped. + +and both paging parameters and the total flag are on the route on both supported +lines, which that record measured rather than assumed: + + git show origin/main:docs/decisions/0272-the-route-next-up-is-read-from.md | sed -n '153,156p' + so this is a paged library read like the other three, and + [0039](0039-the-page-the-item-and-what-next-up-is-not.md)'s offset, its total that + may be a page length, and its rule that the core always asks for the total apply + to it with nothing added. + +So every property [0039](0039-the-page-the-item-and-what-next-up-is-not.md) +decides reaches this read with nothing added: the offset and the count it is +asked for by, the three numbers its answer carries and the fourth derived from +them, the total the core never turns off, and the one item type. Nothing about +next up is special, and saying so is the whole of the statement that record left +owed. + +## Which of #39's conditions this reaches, and it is none of them + +[0039](0039-the-page-the-item-and-what-next-up-is-not.md) already answers this +for its own refusal and the answer does not move when the refusal is lifted. +#39's three conditions are a test per call against a recorded fixture, paging +proven across a boundary, and one item type across the calls, and each is about +the calls that exist rather than about how many there are. A fifth member of the +set adds no condition, and it does not discharge one either. + +## What derives from this in the crate + +`src/server/library.rs` holds the reads as an enumeration and states which of +them accepts a page request. Next up joins it, answering with a page asked for by +an offset and a count, which is the third such read beside items and resume. + +The module also gave the refusal's reason in its own prose - next up is in none +of 0010's capabilities - and that sentence rested on the fact this record +replaces. It says what next up is instead, and where it names 0010 for where a +reading was taken it says that is what it is pointing at, which is the sentence +`tests/fake_server/surface.rs` already carries for the same reason. + +## Why this is written down before the code + +The refusal is the thing that outlives its reason. It was written into a record +that stays in force, and into a module a reader opens to find out what the +library reads are, and both of them go on giving a fact about +[0010](0010-the-server-surface-and-what-an-absence-does.md) as the reason more +than two weeks after +[0272](0272-the-route-next-up-is-read-from.md) changed it. Whoever writes the +first next-up read meets a module saying the capability does not exist, and the +two ways out at that moment are the two +[0037](0037-the-mapping-point.md) and +[0272](0272-the-route-next-up-is-read-from.md) each refuse by name: reach a path +the surface record does not carry, or add the path in the module rather than in +the record. + +The order this tree works in is the specific thing at risk. The scope decision on +#39 is that the surface record decides and the feature issue builds to it. The +surface record has decided, so a reader who finds the module and the record +disagreeing has to settle the question by landing a diff, which is what +[0001](0001-decision-records.md) and +[0039](0039-the-page-the-item-and-what-next-up-is-not.md) both stand against. + +Nothing has gone wrong in the code yet, and that is the reason this is cheap now +and not later. No request is made anywhere in this tree: + + git grep -c 'std::net\|TcpStream' origin/main -- src/ ; echo "exit=$?" + exit=1 + +## Alternatives, and what each cost + +**#39's scope loses next up and says so.** +[0039](0039-the-page-the-item-and-what-next-up-is-not.md) names this as the other +half of its own disjunction, and it was available until +[0272](0272-the-route-next-up-is-read-from.md) landed. It costs the first +screen's second shelf, which that record's own table calls next up in so many +words, and it costs it in a record about a page shape rather than in one about +what the core shows. Its whole argument was that the capability did not exist, +and the capability exists. + +**A record of its own shape for next up: a fourth answer type beside the page, +the whole answer and the one item.** It costs a client the promise that a client +written against one read can display the result of another, which +[0272](0272-the-route-next-up-is-read-from.md) measured is not needed: the +envelope is the one two other reads already answer with, so a second shape would +be a distinction this core invented rather than one the server makes. + +**Leave it to the change that writes the first next-up read.** That is the state +this replaces, and it costs the order the tree works in: the first person to need +the read settles a question two records deferred, inside a change about something +else, with a green gate to show for it. The refusal has already survived its +reason by more than two weeks on exactly that basis. + +## What would reverse this + +[0272](0272-the-route-next-up-is-read-from.md) is superseded by a record whose +table does not carry `next-up`. The fact this rests on is then gone the way +[0039](0039-the-page-the-item-and-what-next-up-is-not.md)'s was, and the read +leaves the set in the record that takes the row out: + + git show origin/main:docs/decisions/0272-the-route-next-up-is-read-from.md | sed -n '5p' + +A supported server line answers `GET /Shows/NextUp` with an envelope that is not +`QueryResult`, or stops taking the two paging parameters on it. The +read is then a shape of its own rather than a fifth member of this set, and this +record is superseded by one that says which shape. +[0272](0272-the-route-next-up-is-read-from.md) carries the commands that measure +both, taken against the two supported lines. + +[0039](0039-the-page-the-item-and-what-next-up-is-not.md) is superseded on the +page or on the one item type. Everything here is that record's properties applied +to one more read, so a change to either is a change to this. diff --git a/docs/decisions/README.md b/docs/decisions/README.md index 0a0c971..6e3d2df 100644 --- a/docs/decisions/README.md +++ b/docs/decisions/README.md @@ -74,4 +74,5 @@ their wording, is under `## Decisions` in [CONTRIBUTING.md](../../CONTRIBUTING.m - [0303. The licence the core is offered under, and the dependency set that follows from it](0303-the-licence-the-core-is-offered-under.md) - [0313. A dated re-reading of a landed record](0313-a-dated-re-reading-of-a-landed-record.md) - [0351. The reversal condition 0291 counts this board with](0351-the-condition-that-counts-this-board.md) +- [0385. What next up is, in terms of the page and the item](0385-what-next-up-is-in-terms-of-the-page-and-the-item.md) - [0512. The triples the gate compiles once the provider's C build arrives](0512-the-triples-the-gate-compiles-once-the-providers-c-build-arrives.md) diff --git a/src/server/library.rs b/src/server/library.rs index cb6661e..ac2ceab 100644 --- a/src/server/library.rs +++ b/src/server/library.rs @@ -17,8 +17,8 @@ //! //! What is here is everything of 0039 that a list and a count settle: the two //! numbers a paged read is asked for by, the three numbers an answer carries, -//! the fourth derived from them, and which of 0010's library reads accepts a -//! page request at all. +//! the fourth derived from them, and which of the library reads the surface +//! record carries accepts a page request at all. //! //! WHAT IS NOT HERE IS A READ. The library makes no request, for the reason //! [`crate::server::transport`] gives about itself, so nothing here asks a @@ -47,12 +47,24 @@ //! the difference between two reads shows up as an absent field on one type //! rather than as a second type. //! -//! WHAT IS NOT HERE IS NEXT UP. 0039 refuses it rather than deciding it: the -//! route exists on both server lines and answers with the same type, and it is -//! in none of 0010's capabilities, so a core reaching it would be growing an -//! enumerated surface in the record that describes the reads rather than in the -//! record that fixes them. [`LibraryRead`] holds the reads 0010 carries and no -//! others. +//! NEXT UP IS HERE NOW, AND THIS PARAGRAPH GAVE THE REASON IT WAS NOT. It said +//! 0039 refuses next up rather than deciding it, because the route is in none of +//! 0010's capabilities and a core reaching it would be growing an enumerated +//! surface in the record that describes the reads rather than in the record that +//! fixes them. 0272 supersedes 0010 and its table carries `next-up`, so the fact +//! that refusal rested on stopped holding on 2026-09-01, and +//! `docs/decisions/0385-what-next-up-is-in-terms-of-the-page-and-the-item.md` +//! carries the statement 0039 says is owed: next up is a paged library read +//! answering with the page and the one item type 0039 fixes, asked for by an +//! offset and a count like items and resume. [`LibraryRead`] holds it as the +//! fifth read. +//! +//! WHERE A COMMENT BELOW SAYS WHAT 0010 RECORDED, IT IS POINTING AT WHERE THAT +//! READING LIVES rather than at the record in force, which is the sentence +//! `tests/fake_server/surface.rs` already carries for the same reason. 0272 says +//! the readings behind the rows it carries were not retaken, so a mention of +//! 0010 here names the record a reading was taken in and 0272 is the record that +//! fixes the surface today. //! //! # The trap this module is written against //! @@ -132,11 +144,12 @@ pub enum WhatTheReadAnswers { OneItem, } -/// The library reads 0010's capability table carries. +/// The library reads the capability table fixing the server surface carries. /// -/// These four and no others. A fifth entry here would be an enumerated surface -/// growing in the record that describes the reads, which is what 0039 refuses -/// next up on. +/// These five and no others. A sixth entry here would be an enumerated surface +/// growing in the record that describes the reads rather than in the one that +/// fixes them, which is the ground 0039 refused next up on and which 0385 +/// answers by adding the read here only after 0272's table carried the path. /// /// Thread safety, from 0009: a plain value, safe from any thread. #[derive(Debug, Clone, Copy, PartialEq, Eq)] @@ -149,6 +162,11 @@ pub enum LibraryRead { Resume, /// One item in full, from `item-detail`. ItemDetail, + /// The episode a series is continued at, from `next-up`. Paged. + /// + /// 0272's table carries the path and 0385 decides that it is this set's + /// fifth member rather than an answer shape of its own. + NextUp, } impl LibraryRead { @@ -157,7 +175,7 @@ impl LibraryRead { pub const fn answers(self) -> WhatTheReadAnswers { match self { Self::Views => WhatTheReadAnswers::OnePageHoldingEverything, - Self::Items | Self::Resume => WhatTheReadAnswers::APageAskedFor, + Self::Items | Self::Resume | Self::NextUp => WhatTheReadAnswers::APageAskedFor, Self::ItemDetail => WhatTheReadAnswers::OneItem, } } @@ -434,9 +452,9 @@ mod tests { assert_eq!(views.next_page_beginning_at(7), None); } - /// Which of 0010's four library reads takes an offset and a count. + /// Which of the five library reads takes an offset and a count. #[test] - fn the_two_paged_reads_are_the_two_the_server_pages() { + fn the_paged_reads_are_the_ones_the_server_pages() { assert_eq!( LibraryRead::Items.answers(), WhatTheReadAnswers::APageAskedFor @@ -453,6 +471,10 @@ mod tests { LibraryRead::ItemDetail.answers(), WhatTheReadAnswers::OneItem ); + assert_eq!( + LibraryRead::NextUp.answers(), + WhatTheReadAnswers::APageAskedFor + ); } /// A page request against a read that takes no paging parameters is refused @@ -477,6 +499,10 @@ mod tests { LibraryRead::Resume.ask_for(asked), WhatAskingForAPageDid::SendsIt(asked) ); + assert_eq!( + LibraryRead::NextUp.ask_for(asked), + WhatAskingForAPageDid::SendsIt(asked) + ); } /// The request carries both numbers back out unchanged.