Skip to content

docs: keep read deadlines per read, not a transport default - #31150

Merged
bolichen97 merged 1 commit into
mainfrom
fix/11420-deadline-scope-header
Nov 6, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
fix/11420-deadline-scope-header

Conversation

@bolichen97

Copy link
Copy Markdown
Contributor

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.ts says 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 exceeded text 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

  • Not changing any deadline value or which reads are bounded: the 15 s and 10 s budgets and every call site stay as they are.
  • Not moving the budgets into the transport. With no default to fall back to, that only relocates the same two numbers.
  • Not reworking the folder pickers' data flow. The useBrowseDirs hook and its onData contract 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 withDeadline or the transport's withJournaledDeadline, with its budget justified where it is declared; the file reads' budgets are in api/client/files.ts. The rule that every bound rejects with a TimeoutError-named Error stays. Three test comments in withDeadline.test.ts and ApiClient.coverage.methods.test.tsx that 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 (spans 2ff3733455a7 and ee95ee2241c5). Only comments and one describe title 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 describe title in website/src/test/withDeadline.test.ts now reads the rejection shape every bound must satisfy, matching the header's rule. Each surface's effective deadline stays pinned by withDeadline.test.ts (one row per bounded file read with its budget) and ApiClient.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 use withDeadline pass 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

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

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
@bolichen97
bolichen97 requested review from a team and KiroCrewCaptain as code owners November 6, 2026 06:40
@bolichen97
bolichen97 requested a review from Zedmor November 6, 2026 06:40
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 6, 2026
@bolichen97
bolichen97 enabled auto-merge (squash) November 6, 2026 06:43
@github-actions

github-actions Bot commented Nov 6, 2026

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of e9167e760ea8f3874a56f0920961a515c3b7fffb — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing to check. The PR only changes comments and one test title, and what it now says matches the tree: withJournaledDeadline is on the transport, and the 15 s and 10 s budgets are declared in api/client/files.ts.

[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 .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 6, 2026

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ✅ PASS

UX-level review of e9167e760ea8f3874a56f0920961a515c3b7fffb — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

UX-Verdict: PASS

Nothing to check. The diff only rewrites code comments and one test describe title, so no user-visible control, string or state changes and no screenshot is needed.

[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 .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 6, 2026

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of e9167e760ea8f3874a56f0920961a515c3b7fffb — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

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

  • Item 2 — undeclared: the description never mentions that the header loses the sentence "Scope is stated as the CONSTANT set, not as a share of the client's fetch('/api/... sites". That sentence was a rule about how scope is stated. The new header's "budget justified where it is declared" replaces it, so nothing is lost.

What this change ships

Inventory (4 items) — 3 justified

Intent: 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).

  1. The withDeadline.ts header now says a deadline is opted into per read, never set as a transport default, and points to api/client/files.ts for the budgets (withJournaledDeadline call sites confirmed there) — justified
  2. The header's "Scope is stated as the CONSTANT set" rule is gone — undeclared
  3. The test comments in ApiClient.coverage.methods.test.tsx and withDeadline.test.ts now say "any bound" instead of "replacement transport" — justified
  4. The describe title is renamed to "the rejection shape every bound must satisfy" — justified

[FIRST-PRINCIPLES-REVIEWED] e9167e7

Description read

[DESCRIPTION-READ] 67f6e28665be319a8227d4aab348a74dc011b6d908f07359834a3557c4255407

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Nov 6, 2026

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed e9167e760ea8f3874a56f0920961a515c3b7fffb — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] e9167e7

Verdict parsed from the review's SHA-scoped output markers for commit e9167e760ea8f3874a56f0920961a515c3b7fffb.

False positive or not applicable? A repository writer can comment:
/ai-review override fable e9167e760ea8f3874a56f0920961a515c3b7fffb false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Nov 6, 2026

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of e9167e760ea8f3874a56f0920961a515c3b7fffb and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] e9167e7

False positive or not applicable? A repository writer can comment:
/ai-review override gpt e9167e760ea8f3874a56f0920961a515c3b7fffb false-positive: <reason, 20 to 500 characters>

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Nov 6, 2026

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved by Crew Captain for the on-call: checks green, PR Readiness passed, review lanes clean on this head.

@bolichen97
bolichen97 merged commit 1fead45 into main Nov 6, 2026
97 checks passed
@bolichen97
bolichen97 deleted the fix/11420-deadline-scope-header branch November 6, 2026 08:15
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 6, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Transport-default deadline: retire the four per-surface file-read constants from #7068

2 participants