Repository navigation
docs: keep read deadlines per read, not a transport default - #31150
Conversation
The header of website/src/lib/withDeadline.ts promised that a transport-level default deadline would land on the API client and that the per-read budgets would then be retired. Its own scope rule rules that out: a default would reach the consumers that render the raw "deadline exceeded" message, and the long-poll endpoints and the streaming reader must stay unbounded. The opt-in per-read path it waited for is already on the shared transport (withJournaledDeadline), and the file reads share two budgets, each sized to its cost. State that design in the header instead of a pending retirement, point at where the file reads' budgets are declared, and reword the three test comments that still spoke of a coming transport bound. No code or assertion changes. Closes #11420
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing to check. The PR only changes comments and one test title, and what it now says matches the tree: [DESIGN-REVIEWED] e9167e7 Description read[DESCRIPTION-READ] 4ac1078b1796ddcc89e775437a7458dc0f915358b6b7dbde708a3dc9990d5a10 That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
UX Review (Opus 5.5) — ✅ PASSUX-level review of UX-Verdict: PASS Nothing to check. The diff only rewrites code comments and one test [UX-REVIEWED] e9167e7 Description read[DESCRIPTION-READ] e2d445f4d216be07b0e26f800065c908453dc1ee11ce7efc70a408c0eda97e17 That sha256 names everything this verdict read: the PR description, plus the 3 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
First Principles Review (Opus 5.5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS The change only edits comments and one test title. It openly drops the planned transport-wide deadline and the retirement tracked in #11420, and gives its reasons. Notes
What this change shipsInventory (4 items) — 3 justifiedIntent: stop contributors from waiting for, or building, a transport-wide default deadline that the module's own scope rule forbids. This is a FIX (documentation drift).
[FIRST-PRINCIPLES-REVIEWED] e9167e7 Description read[DESCRIPTION-READ] 67f6e28665be319a8227d4aab348a74dc011b6d908f07359834a3557c4255407 That sha256 names the PR description this verdict read. Recompute it with |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
KiroCrewCaptain
left a comment
There was a problem hiding this comment.
Approved by Crew Captain for the on-call: checks green, PR Readiness passed, review lanes clean on this head.
Problem / Motivation
Goal: The deadline helper's header describes the read-deadline design the dashboard actually ships, so nobody waits on, or builds, a transport-wide default deadline that its own rule rules out.
The header of
website/src/lib/withDeadline.tssays a general deadline will land on the shared API client and that the per-read budgets will then be retired, and #11420 tracks that. This PR declines that plan and says why in the header. The opt-in per-read path the note waited for is already on the shared transport (withJournaledDeadline), every file read in the API client goes through it, and the file reads share two budgets that differ on purpose (15 s, sized for the tree walks, and 10 s for one-directory listings). One default cannot keep both, and a default contradicts the header's own scope rule.Why it matters
The header is the one place that tells a contributor when a read may carry a deadline. While it promises a coming default, the next change either waits for work that will not happen or adds a blanket bound that would show the untranslated
deadline exceededtext in every locale on the panels that render the server's message, and would cut off the long-poll endpoints and the streaming reader.Not a goal
useBrowseDirshook and itsonDatacontract that the issue mentions are no longer in the tree, so that half of the issue is moot.What changed (motivation → approach → change)
The header promised a transport default and a retirement that its first paragraph forbids: a deadline belongs only on a read whose screen names a timeout in its own words, and the long-poll and streaming reads must stay unbounded.
So the header states the design as it is: a read opts into a bound through
withDeadlineor the transport'swithJournaledDeadline, with its budget justified where it is declared; the file reads' budgets are inapi/client/files.ts. The rule that every bound rejects with aTimeoutError-namedErrorstays. Three test comments inwithDeadline.test.tsandApiClient.coverage.methods.test.tsxthat still spoke of a coming transport bound now speak of any bound, with their assertions untouched. This settles the deferral that #7068's Design Review recorded (spans2ff3733455a7andee95ee2241c5). Only comments and onedescribetitle change; no code does.Backwards compatibility
Compatible: comments and one test title change; no code, value, or behaviour changes.
Removes nothing: the edit rewrites comments and takes no path, record, key or function away.
Tests
No assertion added or changed. One
describetitle inwebsite/src/test/withDeadline.test.tsnow readsthe rejection shape every bound must satisfy, matching the header's rule. Each surface's effective deadline stays pinned bywithDeadline.test.ts(one row per bounded file read with its budget) andApiClient.coverage.methods.test.tsx.Determinism: those two files passed three runs in shuffled order (
--sequence.shuffle, seeds 7919, 15838, 23757; 865 tests each), and the six suites that usewithDeadlinepass together (1,017 tests).Manual verification
N/A — comment-only change;
tsc -p tsconfig.app.json, eslint on the three files, the i18n check and the repository's semgrep rules on the diff pass.Screenshots / video
Why no screenshot: the diff only rewrites code comments and a test title, so nothing on screen changes.
Related Issues
Closes #11420
Sibling sweep
N/A — a docs change, not a fix or revert. The stale wording was swept with
git grep -n -i -E "replacement transport|transport default|transport-level bound|whatever ships next" -- website src docs test; the three test comments it found are changed here, and the other hits are unrelated instance-transport settings.Pattern harvest
N/A — a docs change, not a fix or revert.
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)