R6: refactor + docs reconciliation + de-staging #37

Merged

developer merged 6 commits from feature/r6-refactor-destage into development 2026-06-10 16:03:18 +00:00

Conversation 0 Commits 6 Files Changed 161

+1415 -1346

developer commented 2026-06-10 15:35:46 +00:00

Owner

Copy Link

Copy Source

Pre-release phase R6 (PRERELEASE.md) — behaviour-preserving, in three separately-committed passes.

(a) De-staging

Removed Stage N / TODO-N / (RN) references from code, comments, service READMEs and the current-state docs (ARCHITECTURE / FUNCTIONAL+_ru / TESTING / UI_DESIGN), rewording narratives to present tense. PLAN / PRERELEASE / CLAUDE keep the stage history. Renamed the only stage-named identifiers (registerStage8→registerSocialOps, registerStage11→registerLinkOps) and split stage6_test.go by domain (→ email_test.go / account_test.go). De-staged the .fbs/.proto comments and regenerated (only the .proto-derived Go docstrings changed; flatc strips schema comments).

(b) Docs↔code reconciliation

Full review against the code; the one drift fixed — ARCHITECTURE §3 still said guest-reaping was "deferred (TODO-3)", but it is implemented, so the current behaviour is stated instead.

(c) Structural changes (owner-approved list)

• B — dropped the dead seat/action/score/total scalars from OpponentMovedEvent (no reader used them; regenerated FB Go + TS).
• A — extracted the nested FB builders shared by notify and the gateway transcode into a new scrabble/pkg/wire package (single definition of the wire layout; both sides map their source types to neutral structs). Field sets verified identical → behaviour-preserving (net +~145 LOC: an anti-drift win for the fiddly mechanics, not a line-count cut).
• C1+C2 — centralized the cross-file integration-test fixtures into backend/internal/inttest/helpers.go.

Excluded by interview: C3/C5 test merges; the h2cMaxConcurrentStreams sizing (an R7 tuning concern). No schema change → no contour DB wipe.

Verification (local, all green)

gofmt / go vet / go build across modules; full unit suites; the integration suite (-tags=integration, Postgres via testcontainers); pnpm check + test:unit + build + the bundle-size gate; Playwright e2e — 72 passed (chromium + webkit).

Pre-release phase **R6** (`PRERELEASE.md`) — behaviour-preserving, in three separately-committed passes. ### (a) De-staging Removed `Stage N` / `TODO-N` / `(RN)` references from code, comments, service READMEs and the current-state docs (ARCHITECTURE / FUNCTIONAL+`_ru` / TESTING / UI_DESIGN), rewording narratives to present tense. PLAN / PRERELEASE / CLAUDE keep the stage history. Renamed the only stage-named identifiers (`registerStage8`→`registerSocialOps`, `registerStage11`→`registerLinkOps`) and split `stage6_test.go` by domain (→ `email_test.go` / `account_test.go`). De-staged the `.fbs`/`.proto` comments and regenerated (only the `.proto`-derived Go docstrings changed; flatc strips schema comments). ### (b) Docs↔code reconciliation Full review against the code; the one drift fixed — ARCHITECTURE §3 still said guest-reaping was "deferred (TODO-3)", but it is implemented, so the current behaviour is stated instead. ### (c) Structural changes (owner-approved list) - **B** — dropped the dead `seat/action/score/total` scalars from `OpponentMovedEvent` (no reader used them; regenerated FB Go + TS). - **A** — extracted the nested FB builders shared by `notify` and the gateway `transcode` into a new `scrabble/pkg/wire` package (single definition of the wire layout; both sides map their source types to neutral structs). Field sets verified identical → behaviour-preserving (net +~145 LOC: an anti-drift win for the fiddly mechanics, not a line-count cut). - **C1+C2** — centralized the cross-file integration-test fixtures into `backend/internal/inttest/helpers.go`. Excluded by interview: C3/C5 test merges; the `h2cMaxConcurrentStreams` sizing (an R7 tuning concern). No schema change → no contour DB wipe. ### Verification (local, all green) `gofmt` / `go vet` / `go build` across modules; full unit suites; the **integration suite** (`-tags=integration`, Postgres via testcontainers); `pnpm check` + `test:unit` + `build` + the bundle-size gate; **Playwright e2e** — 72 passed (chromium + webkit).

developer added 6 commits 2026-06-10 15:35:46 +00:00

R6(a): de-stage code, docs, READMEs; split stage6_test ... 8881214213

Mechanical, behaviour-preserving removal of Stage N / TODO-N / phase (RN)
references from comments, doc-comments, service READMEs, the current-state docs
(ARCHITECTURE, FUNCTIONAL+_ru, TESTING, UI_DESIGN), config-file comments, and the
.fbs/.proto schema comments. PLAN.md / PRERELEASE.md / CLAUDE.md keep the stage
history.

- Rename the only stage-named identifiers: registerStage8 -> registerSocialOps,
  registerStage11 -> registerLinkOps (gateway transcode).
- Split stage6_test.go: TestEmailLoginFlow -> email_test.go,
  TestGuestAutoMatchLeavesNoStats (+ provisionGuest) -> account_test.go.
- Regenerated proto bindings (push.pb.go, telegram_grpc.pb.go) from the de-staged
  .proto comments; FB Go/TS bindings unchanged (flatc strips schema comments).

go build/vet/gofmt clean across modules; integration typecheck and pnpm check green.

R6(b): reconcile docs with code — restore guest-reaper mention ... c31ac7088c

Pass (a) removed a stale "(reaping abandoned guest rows is deferred — TODO-3)"
note from ARCHITECTURE §3, but guest reaping is implemented (the background
reaper, BACKEND_GUEST_REAP_INTERVAL / BACKEND_GUEST_RETENTION, covered by
inttest). State the current behaviour instead.

A full section-by-section review of ARCHITECTURE / FUNCTIONAL (+_ru) / TESTING /
UI_DESIGN against the code found no other drift — each R-phase baked its own docs,
and FUNCTIONAL/TESTING already describe the reaper correctly.

R6(c): drop dead opponent_moved scalars (seat/action/score/total) ... 1079878654

These pre-R4 summary scalars on OpponentMovedEvent were redundant with the
move/game delta and read by nobody — the UI codec and mock take only
move/game/bag_len, and the gateway forwards the push payload verbatim. Removed
from scrabble.fbs, the notify emit (notify/events.go) and the round-trip test;
regenerated the FB Go + TS bindings. No prod data, so the wire-slot renumber is
free and there is no DB change.

R6(c): share the nested FB builders between notify and gateway transcode ... b47c47e969

Extract the FlatBuffers builders for the wire tables shared by the backend push
encoder and the gateway edge transcoder — GameView, MoveRecord, StateView,
AccountRef, Invitation and their nested rows — into a new scrabble/pkg/wire
package. Both callers keep their local builder signatures (no call sites move)
but now map their own source types (the backend's notify.* payloads and the
decoded engine.MoveRecord; the gateway's backendclient.* REST DTOs) to neutral
wire.* structs and delegate the construction to package wire, the single
definition of the nested-table layout.

Behaviour-preserving: the verified-identical field sets mean the wire bytes
decode the same, and the notify + transcode round-trip tests pass unchanged. The
fiddly Start/Add/End + reverse-prepend vector boilerplate now lives once; the two
encode files shrink while pkg/wire carries the shared logic.

R6(c): centralize shared integration-test fixtures in helpers.go ... c6e0dac940

Move the cross-file integration fixtures — the service constructors
(newGameService/newSocialService/newRobotService/newMatchmaker), the game-assembly
helpers (newMirror/newGameWithSeats/newDraftGame), account provisioning
(provisionAccount/provisionGuest) and the stats reader — out of the domain test
files (newGameService alone was used by 10 files) into a single
backend/internal/inttest/helpers.go. Helpers used by a single file stay local.

Pure relocation: the helper bodies are unchanged, no test logic changes; the
imports the moves left unused are pruned. go vet -tags=integration is clean.

R6: mark phase done in PRERELEASE.md + log refinements 40ccfb9514

owner approved these changes 2026-06-10 16:02:17 +00:00

developer merged commit 7210bed560 into development 2026-06-10 16:03:18 +00:00

developer deleted branch feature/r6-refactor-destage 2026-06-10 16:03:18 +00:00

Sign in to join this conversation.

Reviewers

No Reviewers

owner

Labels

No items

No Label

Milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

owner (Ilia) developer

No Assignees

2 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: developer/scrabble-game#37