Skip to content

docs(plans): re-baseline the server.ts split plan against 6,539 lines [skip-ci] - #553

Open
RonenMars wants to merge 1 commit into
mainfrom
docs/refresh-server-split-plan
Open

docs(plans): re-baseline the server.ts split plan against 6,539 lines [skip-ci]#553
RonenMars wants to merge 1 commit into
mainfrom
docs/refresh-server-split-plan

Conversation

@RonenMars

Copy link
Copy Markdown
Owner

Refs #494.
This does not do the split — it refreshes the plan that describes it, so the plan is executable when the gate opens.

Why

docs/plans/2026-07-12-server-ts-split.md was written against a 3,333-line src/server.ts.
The file is now 6,539 lines, so every line number in the plan was stale by roughly 3,200 lines and the document could not be followed as written.

What changed

Re-verified every cited range at c76c257 and added a re-baseline header naming that SHA, so the next reader can tell when it has drifted again.

Added the three subsystems that landed after the original draft and that it therefore never mentions: external live tails (3562–3753), resume/fork/startup-outcome (4553–5150), and session name plus live model/effort settings (6213–6345) — about 950 lines between them.

Added the two regions the original draft overlooked entirely, which together are the largest readability problem in the file: the 674-line constructor (14 inline callbacks plus a 170-line ApiDeps literal) and the 408-line listen().

Reordered the sequence from four PRs to eight, cheapest and most independent first, so the pattern and the verification loop are proven on a pure move of pure functions before anything entangled is touched.

Recorded the constraints that separate a mechanical move from a broken suite, all verified: 41 test files reference ../src/server, private fields must stay as instance properties (sessionStatusBus alone has 14 reach-ins), the named exports tests import must survive, ApiDeps must not change, and no build config changes are needed.

Corrected the end-state estimate from 1,100–1,300 lines to roughly 2,400, since the original figure was measured against the smaller file and would have read as a broken promise.

Restated the sequencing gate inside the plan rather than only in the issue, citing the 2026-08-01 rehearsal finding that one refactor against four editors recurs once per PR.

Verification

Docs-only, so no behaviour to test.

Every line number in the document was spot-checked against src/server.ts at c76c257 before writing — the constructor at 656, listen at 2056, handleGetConversation at 3919, the free functions at 6348, and 19 others.

Two numbers from the first draft were corrected after checking them directly: the src/api/ total is 1,952 lines rather than 1,829, and RESUME_DISCOVERY_TIMEOUT_MS is exported but not referenced by any test, so it was removed from the must-survive list.

git diff --stat shows one file changed, and the title carries [skip-ci] per the docs-only rule.

… [skip-ci]

The plan was written on 2026-07-12 against a 3,333-line src/server.ts and the file is now 6,539, so every line number in it was stale by roughly 3,200 lines.
Re-verified all ranges at c76c257 and added the three subsystems that appeared since: external live tails, resume/fork, and live model/effort settings.
Added the two regions the original draft overlooked — the 674-line constructor and the 408-line listen() — and reordered the sequence to eight PRs, cheapest and most independent first.
Recorded the constraints that make a move mechanical rather than suite-breaking: 41 test files reference ../src/server, private fields must stay as instance properties, and ApiDeps must not change.
Corrected the end-state estimate from 1,100-1,300 to roughly 2,400 lines, since the original figure was measured against the smaller file.
Restated the sequencing gate in the plan itself, citing the 2026-08-01 rehearsal finding that one refactor against four editors recurs once per PR.
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.

1 participant