Skip to content

docs(rfc): bounded-time restore for large sessions (#35875) - #35916

Merged
KiroCrewCaptain merged 2 commits into
mainfrom
docs/35875-large-session-bounded-restore
Nov 12, 2026
Merged

KiroCrewCaptain merged 2 commits into
mainfrom
docs/35875-large-session-bounded-restore

Conversation

@chenmingwei23

@chenmingwei23 chenmingwei23 commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Record an agreed plan that makes a large session accept a message within 5 s of a gateway restart, with a 200 MB transcript and 100+ open tabs.

Part B of #35875. This RFC measures where restore time still goes on current main and proposes a bounded-cost path. Docs only; it changes no code.

Why it matters

A large, long-lived session (the busiest conductor or the session a person works in all day) is slow to become usable after every restart, and a message sent in that window is refused or left pending. Users with small sessions see no change: every proposed path applies only above a 16 MB threshold or is pure performance with identical outputs.

Reviewer note: if accepted, the later implementation changes default behaviour for users with large sessions: a tab over 16 MB opens with its newest window and pages older rows in on scroll, and the restore builds the focused and visible tabs first. These are listed in the RFC's "Behaviour changes" section.

Not a goal

What changed (motivation → approach → change)

Key numbers on main 029b6db029 (130 tabs, 204 MB transcript): ready at 8.0 s warm and 14.1 s cold page cache; the biggest tab's full read is 1.2 s warm and 3.1 s cold. Synthetic 136 MB crew-log unit: 18 cold slot folds take 91 s, because each fold walks the unit separately; with a stale savepoint, 47 s on main and 42 s with #35840.

Backwards compatibility

Compatible: docs only, nothing that works today changes.

Removes nothing: the diff adds one document and one index row.

Tests

Docs only. scripts/docs-lint.sh: all documentation checks passed.

Proof: not provable -- docs or config only

Manual verification

N/A -- docs only; the measurements were taken on a scratch copy of a data home and are recorded in the RFC.

Related Issues

Refs #35875

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

Contribution License Agreement

Contributions are accepted under the project's Apache-2.0 license; see the Licensing section of CONTRIBUTING.md.

Design for part B of #35875, with measurements on main: a tail window for
eager tabs over 16 MB, focus-first restore order, one crew-log walk for all
of a slot's folds, and a CI fixture at the threshold. Changes no code.
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 12, 2026
@github-actions

github-actions Bot commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision a9350743c1e1b835b097704de717a51d9e0a557a touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

github-actions Bot commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ⏭️ skipped

Revision a9350743c1e1b835b097704de717a51d9e0a557a ships no reviewable capability (docs, tests or generated files only), so there is nothing to inventory. Does not block merge.

@github-actions

github-actions Bot commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

This PR only adds a draft RFC and changes no code; the open choices go to reviewers under its "Decisions requested" section.

Notes

  • In §1.2, the dashboard persists "the tab focused at last shutdown" to open_slots.json. Focus belongs to each client, though, and several dashboard clients or people can share one gateway, so one saved key can't be right for all of them. The RFC should say which client's focus wins, or rely on the connect-time re-prioritisation alone.
  • §3.1 says opening with a 500-row window is the only visible change. Before §1.1 lands, list every place that reads a tab's in-memory window and expects the full history, such as in-tab search, summary, export and the continued-turn context.

[DESIGN-REVIEWED] a935074

Description read

[DESCRIPTION-READ] a0f35738f6596db17d02d647b72941f3ccf8413e02a22a0720acf89a93d08eb6

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 12, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] a935074

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

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

@github-actions

github-actions Bot commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] a935074

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

@chenmingwei23
chenmingwei23 marked this pull request as ready for review November 12, 2026 17:33
@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

Code change approver recommendation: A person should decide

Why: the decider raised 2 possible problems and estimates a 62% chance that this change introduces a defect; a person should check them.

This PR adds a docs-only draft RFC. Its central sizing claim is wrong. §1.1 asks for approval of a 16 MB threshold because the worst case fits 'inside the 5 s target', but by the document's own numbers it comes to 5.4 to 5.9 s, because the restore reads tabs one after another. The verified main-side reading in the index row, and the bound built on it, also miss that main does a full read for every tab whose window cannot wait (non-person, crew, loop-driven, empty tail), not just the newest 8. I confirmed both points in restore_drivers.py. Both should be corrected before the RFC is used to ask for decisions.

Things to check (possible problems the decider raised; at this confidence many turn out to be fine):

  • The worst-case sum is wrong: 3.4 + 2 = 5.4 s, or 5.9 s counted from the cold restore start. Both miss the 5 s Goal. Section 5 decision 1 asks the maintainer to accept the 16 MB threshold on this bound. As written, §1.1 alone does not reach the stated goal. The goal holds only together with §1.2's fo (docs/request-for-change/rfc-large-session-bounded-restore.md, medium)
  • On main the full read is not capped at 8 tabs. Linked-channel, app, remote, cron/workflow, crew-member, crew-bound and loop-driven tabs, tabs with an untorn local turn or deferred notes, and tabs with an empty tail all take the full read whatever their position. So three statements understate what r (docs/request-for-change/README.md, medium)

An automated recommendation, not a review: a maintainer still decides. It approves on its own only when the estimated chance of a defect is at most 12% and the change has at most 400 changed lines. Decider v3c (217fe607) · commit 8fb111919b · 174 changed lines. If this recommendation is wrong, reply here: replies are how the approver is evaluated.

Sections 1.1 and 1.2 are behaviour changes gated on review of this document;
section 1.3 (pure performance) and 1.4 (tests) land as separate pull requests.
Restate which tabs main reads in full (the newest 8 plus every tab whose
window cannot wait), apply the tail window to that whole set, and correct the
5 s budget: it holds only with the focus-first order of section 1.2.
@chenmingwei23
chenmingwei23 force-pushed the docs/35875-large-session-bounded-restore branch from 8fb1119 to a935074 Compare November 12, 2026 17:56
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Re: Opus 5.5 Review (#35916 (comment))

Both findings are fixed in a935074.

  1. rfc 1.1 arithmetic (fixed in a935074). The sum was wrong: 8 tabs x 0.25 s = 2 s, and 3.9 s cold restore start + 2 s = 5.9 s, over the 5 s target. Lowering the threshold does not fix it, because the fully read set has no fixed size (finding 2); even 8 tabs would need about 9 MB. Section 1.1 now says the 5 s target holds only together with section 1.2's focus-first order: the focused tab is built first, at about 3.9 s + 0.25 s = 4.2 s cold at the threshold, whatever the size of the rest of the set.

  2. What main fully reads (fixed in a935074). Verified in restore_drivers.py: _may_restore_as_row is false for the newest EAGER_WINDOW_RESTORES tabs, for a loop-driven tab and for every tab when the loop store cannot be read; _prefetch_open_slot_inputs then takes the full read for a tab whose window cannot wait (_window_can_wait: non-person origin, linked session, app, remote slot, untorn local turn, deferred notes), a crew member's tab (_member_restore_identity), a crew-bound tab (crew_bound_on_disk) and a tab whose tail is empty. The README row, the Summary and section 1.1 now name that set, and the tail window applies to every tab in it, so each one costs at most 0.25 s cold at the threshold instead of growing with its history. On the measured host the set was 8 of 130 tabs.

@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 12, 2026
@KiroCrewCaptain
KiroCrewCaptain enabled auto-merge (squash) November 12, 2026 20:01

@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.

This PR adds docs only: the bounded-restore RFC and one index row in docs/request-for-change/README.md. It changes no code and no blocking repository rule covers these paths. The review checked the restore symbols and line references the RFC cites against main, and they exist as described. The earlier arithmetic and full-read-set findings are fixed on this head. Every review lane on this head passed or was skipped for a stated reason, and PR Readiness is green.
Done well: measured and unverified claims are kept apart, the synthetic crew-log units are labelled as synthetic, and the 5 s bound is restated openly so it rests on the focus-first order and not on the threshold alone.
The design is signed off under the standing maintainer sign-off for changes by team members.
Optional:

  • Main already keeps a 500-row window (_WINDOW_ROWS in slot_builders.py) and has a page-index tail reader (slot_window_tail.read_window_tail, used by _PendingWindow.read) with scroll paging. §1.1 could shrink to routing the eager open-tab read through that reader. That would drop the 16 MB threshold, the new marker and behaviour change 1 in §3.
  • The 5 s argument counts only the build of the focused tab. Turn admission also waits on memory preparation (up to MEMORY_ADMISSION_WAIT_SECONDS, and 9.4 s in the RFC's own table). Say whether that is in scope, or who owns it.
  • The in-flight work section lists #35840, #34887 and #35869 as open, but all three are now merged. The fresh-savepoint row is also credited to #34882, which does not touch the measured slot-memo path.

@KiroCrewCaptain
KiroCrewCaptain merged commit 20afff1 into main Nov 12, 2026
159 of 165 checks passed
@KiroCrewCaptain
KiroCrewCaptain deleted the docs/35875-large-session-bounded-restore branch November 12, 2026 20:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

readiness: passed Eligible automated validation passed for the current revision

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants