amaurycoudr/chess-project
2
0
Fork 0
Code Issues 12 Pull requests 2 Projects Releases Packages 1 Activity Actions 2

Claim a Guest on the wire, and write its later Games to the Account #385

New issue
Closed
opened 2026-10-11 16:27:27 +00:00 by root · 14 comments
root commented 2026-10-11 16:27:27 +00:00 (Migrated from gitlab.core-project.space)
Copy link

Imported from GitHub amaurycoudr/chess-project#385, opened by @amaurycoudr on 2026-10-11 16:27 UTC.

Parent

#365

What to build

A signed-in Player can claim the Guest their browser holds, through the API alone. The claim links the Guest to their Account for good and moves every Game the Guest owns to the Account (ADR 0035). "My games" as the Account then lists them on any signed-in browser. A Game decided later for a Seat the claimed Guest still holds is written as the Account. A claimed Guest keeps its Seats but takes no new one. Deleting the Account deletes the Guests it claimed, and the Account export lists them.

  • Schema, one migration on top of the Guest history and Accounts v1 schemas:
    • the Guest record gains the claiming Account and the claim date, set together or not at all and never cleared;
    • the Account reference cascades on delete.
  • Contract: a new guest router.
    • guest.get reads the caller's Guest as none, unclaimed with its count of Games (zero for a Guest with no record), claimed-by-you or claimed-by-other. It is a read, so it needs no Origin.
    • guest.claim needs a Session and answers how many Games moved. It refuses with GUEST_NOT_FOUND (404) without a Guest header and GUEST_ALREADY_CLAIMED (409) when another Account holds the claim. Both go in the refusal status table.
    • The Guest comes from the RPC context, never an input (ADR 0034).
  • The claim, in the games feature module, in one transaction:
    1. upsert the Guest record by hash and lock it;
    2. refuse a claim by another Account;
    3. answer zero moved for a repeat by the same Account;
    4. otherwise set the link and rewrite White and Black ownership, keeping at most one owner per Color.
    • Claiming a Guest that owns no Games is allowed, and links it.
  • A Game decided later: when a Game is written, a claimed Guest on either Color is written as that Color's Account owner. The write reads the claim under the same row lock the claim takes, so a race cannot leave a Game on a claimed Guest. The Room is unchanged.
  • Taking Seats:
    • without a Session, a claimed Guest's header counts as no header on create and take, so a fresh Guest is minted;
    • one exception: a take that hands back a Seat the claimed Guest already holds;
    • a header with no Guest record is an ordinary Guest, never re-minted;
    • the lookup happens in the service, never in the RPC context;
    • every other procedure still accepts a claimed Guest's header as proof of its Seats.
  • Export: the Account export gains the Guests it claimed, each with its claim date only, never the hash.
  • Self-games are rewritten like any other Game. Their shape in the listing, the Game read and the export belongs to #386: this ticket does not widen the Color shapes.

Seam: The RPC wire

Acceptance criteria

  • guest.get answers each of its four values, including unclaimed with zero for a header with no record, and claimed-by-other for a claimed Guest read with a different Account's Session or with none.
  • A claim moves every Game the Guest owns, as White and as Black, to the Account, leaves each opponent's side untouched, and answers the count; game.list as the Account then lists them from another signed-in client.
  • A claim without a Session is refused as unauthenticated; without a Guest header it is GUEST_NOT_FOUND.
  • A claim of a Guest claimed by another Account is GUEST_ALREADY_CLAIMED and moves nothing; a repeat by the same Account succeeds with zero moved.
  • Two Accounts claiming one Guest at once: exactly one wins.
  • A claim of a Guest with no record creates and links the record, and a Game it decides afterwards goes to the Account.
  • A Game decided after the claim for a Seat the claimed Guest holds is written as the Account, both with and without a Session on the deciding Move.
  • A claim racing a Game write for that Guest leaves the Game on the Account.
  • A self-game, from two claimed Guests and from a Guest against its own Account, ends with both Colors owned by the Account.
  • Without a Session, create and take with a claimed Guest's header mint a fresh Guest. A take that hands back a Seat the claimed Guest holds does not. A header with no record mints nothing. With a Session, create and take act as the Account.
  • Deleting the Account deletes its claimed Guests. Their header then reads unclaimed with zero, and their Games stay readable by link with no owner on that side.
  • The Account export lists each claimed Guest with its claim date and no hash.
> _Imported from GitHub [amaurycoudr/chess-project#385](https://github.com/amaurycoudr/chess-project/issues/385), opened by [@amaurycoudr](https://github.com/amaurycoudr) on 2026-10-11 16:27 UTC._ <!-- github-issue:385 --> --- ## Parent #365 ## What to build A signed-in **Player** can claim the **Guest** their browser holds, through the API alone. The claim links the **Guest** to their **Account** for good and moves every **Game** the **Guest** owns to the **Account** (ADR 0035). "My games" as the **Account** then lists them on any signed-in browser. A **Game** decided later for a **Seat** the claimed **Guest** still holds is written as the **Account**. A claimed **Guest** keeps its **Seats** but takes no new one. Deleting the **Account** deletes the **Guests** it claimed, and the **Account** export lists them. - **Schema**, one migration on top of the Guest history and Accounts v1 schemas: - the **Guest** record gains the claiming **Account** and the claim date, set together or not at all and never cleared; - the **Account** reference cascades on delete. - **Contract**: a new `guest` router. - `guest.get` reads the caller's **Guest** as `none`, `unclaimed` with its count of **Games** (zero for a **Guest** with no record), `claimed-by-you` or `claimed-by-other`. It is a read, so it needs no Origin. - `guest.claim` needs a **Session** and answers how many **Games** moved. It refuses with `GUEST_NOT_FOUND` (404) without a **Guest** header and `GUEST_ALREADY_CLAIMED` (409) when another **Account** holds the claim. Both go in the refusal status table. - The **Guest** comes from the RPC context, never an input (ADR 0034). - **The claim**, in the games feature module, in one transaction: 1. upsert the **Guest** record by hash and lock it; 2. refuse a claim by another **Account**; 3. answer zero moved for a repeat by the same **Account**; 4. otherwise set the link and rewrite White and Black ownership, keeping at most one owner per **Color**. - Claiming a **Guest** that owns no **Games** is allowed, and links it. - **A Game decided later**: when a **Game** is written, a claimed **Guest** on either **Color** is written as that **Color**'s **Account** owner. The write reads the claim under the same row lock the claim takes, so a race cannot leave a **Game** on a claimed **Guest**. The **Room** is unchanged. - **Taking Seats**: - without a **Session**, a claimed **Guest**'s header counts as no header on create and take, so a fresh **Guest** is minted; - one exception: a take that hands back a **Seat** the claimed **Guest** already holds; - a header with no **Guest** record is an ordinary **Guest**, never re-minted; - the lookup happens in the service, never in the RPC context; - every other procedure still accepts a claimed **Guest**'s header as proof of its **Seats**. - **Export**: the **Account** export gains the **Guests** it claimed, each with its claim date only, never the hash. - Self-games are rewritten like any other **Game**. Their shape in the listing, the **Game** read and the export belongs to #386: this ticket does not widen the **Color** shapes. Seam: The RPC wire ## Acceptance criteria - [ ] `guest.get` answers each of its four values, including `unclaimed` with zero for a header with no record, and `claimed-by-other` for a claimed **Guest** read with a different **Account**'s **Session** or with none. - [ ] A claim moves every **Game** the **Guest** owns, as White and as Black, to the **Account**, leaves each opponent's side untouched, and answers the count; `game.list` as the **Account** then lists them from another signed-in client. - [ ] A claim without a **Session** is refused as unauthenticated; without a **Guest** header it is `GUEST_NOT_FOUND`. - [ ] A claim of a **Guest** claimed by another **Account** is `GUEST_ALREADY_CLAIMED` and moves nothing; a repeat by the same **Account** succeeds with zero moved. - [ ] Two **Accounts** claiming one **Guest** at once: exactly one wins. - [ ] A claim of a **Guest** with no record creates and links the record, and a **Game** it decides afterwards goes to the **Account**. - [ ] A **Game** decided after the claim for a **Seat** the claimed **Guest** holds is written as the **Account**, both with and without a **Session** on the deciding **Move**. - [ ] A claim racing a **Game** write for that **Guest** leaves the **Game** on the **Account**. - [ ] A self-game, from two claimed **Guests** and from a **Guest** against its own **Account**, ends with both **Colors** owned by the **Account**. - [ ] Without a **Session**, create and take with a claimed **Guest**'s header mint a fresh **Guest**. A take that hands back a **Seat** the claimed **Guest** holds does not. A header with no record mints nothing. With a **Session**, create and take act as the **Account**. - [ ] Deleting the **Account** deletes its claimed **Guests**. Their header then reads `unclaimed` with zero, and their **Games** stay readable by link with no owner on that side. - [ ] The **Account** export lists each claimed **Guest** with its claim date and no hash.
root commented 2026-10-11 16:27:27 +00:00 (Migrated from gitlab.core-project.space)
Copy link

GitHub issue relations, imported as "related" links (GitLab CE has no sub-issues or blocking links).

> _GitHub issue relations, imported as "related" links (GitLab CE has no sub-issues or blocking links)._ <!-- github-relations --> - Parent (sub-issue of): #365 - Blocked by: #384, #383, #381 - Blocking: #387, #386
root commented 2026-10-13 08:39:50 +00:00 (Migrated from gitlab.core-project.space)
Copy link

mentioned in issue #386

mentioned in issue #386
root commented 2026-10-13 08:39:51 +00:00 (Migrated from gitlab.core-project.space)
Copy link

mentioned in issue #387

mentioned in issue #387
root commented 2026-10-13 08:41:22 +00:00 (Migrated from gitlab.core-project.space)
Copy link

mentioned in issue #365

mentioned in issue #365
root commented 2026-10-13 08:41:28 +00:00 (Migrated from gitlab.core-project.space)
Copy link

mentioned in issue #381

mentioned in issue #381
root commented 2026-10-13 08:41:28 +00:00 (Migrated from gitlab.core-project.space)
Copy link

mentioned in issue #383

mentioned in issue #383
root commented 2026-10-13 08:41:29 +00:00 (Migrated from gitlab.core-project.space)
Copy link

mentioned in issue #384

mentioned in issue #384
root commented 2026-10-13 08:42:30 +00:00 (Migrated from gitlab.core-project.space)
Copy link

marked this issue as related to #365

marked this issue as related to #365
root commented 2026-10-13 08:42:39 +00:00 (Migrated from gitlab.core-project.space)
Copy link

marked this issue as related to #381

marked this issue as related to #381
root commented 2026-10-13 08:42:41 +00:00 (Migrated from gitlab.core-project.space)
Copy link

marked this issue as related to #383

marked this issue as related to #383
root commented 2026-10-13 08:42:41 +00:00 (Migrated from gitlab.core-project.space)
Copy link

marked this issue as related to #384

marked this issue as related to #384
root commented 2026-10-13 08:42:41 +00:00 (Migrated from gitlab.core-project.space)
Copy link

marked this issue as related to #387

marked this issue as related to #387
root commented 2026-10-13 08:42:42 +00:00 (Migrated from gitlab.core-project.space)
Copy link

marked this issue as related to #386

marked this issue as related to #386
root commented 2026-10-14 16:34:11 +00:00 (Migrated from gitlab.core-project.space)
Copy link

mentioned in merge request !529

mentioned in merge request !529
root (Migrated from gitlab.core-project.space) closed this issue 2026-10-15 08:20:24 +00:00
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
docs/training-platform-pivot
ci/499-remove-gitlab-ci
fix/front-browser-pages
docs/contributing-forgejo-ci
fix/storybook-ghsa-f2ph-cmg5-wxc8
prototype/dead-end-page
prototype/puzzles-ui-redesign
prototype/399-front-screens
ci/front-test-one-job
feat/370-drizzle-gateway
pr-screenshots
feat/369-postgres-per-stack
claude/pawn-promotion-capture-score-46fffb
claude/github-workflow-improvements-30cf86
docs/352-adr-claim-guest
docs/351-adr-seat-identity
claude/retro-last-10-conversations-9af723
docs/accounts-adrs
claude/lighthouse-pt-4b5a78
docs/350-adr-sessions
feat/game-status-326
research/postgres-on-vps
research/email-provider
prototype/offer-overlay
ci/339-pr-screenshots
prototype/game-status
ci/317-faster-pipeline
spec/303-vps-hosting
claude/paste-invite-link-room-code
docs/309-adr-vps-hosting
fix/311-client-route-fallback
claude/back-navigation-feature-2166ea
claude/resource-contract
claude/api-nest-orpc
claude/adr-nest-orpc
claude/e2e-tests-new-features-1ce2a1
claude/la-spec-273-fd55ac
claude/matt-pocock-skills-integration-444ba9
chore/adopt-the-cognitive-load-coding-rules-270
feat/choose-the-promotion-piece-in-a-popover-instead-of-auto-queening-267
feat/animate-piece-moves-on-the-board-264
feat/show-drag-state-on-the-board-263
feat/move-a-piece-by-dragging-and-dropping-it-261
feat/blocking-modal-when-the-room-has-closed-246
feat/truthful-opponent-presence-lost-connection-left-new-opponent-248
feat/horizontal-game-and-room-action-bars-with-a-confirmed-leave-247
feat/room-status-block-with-a-fixed-height-and-seat-relative-wording-245
docs/amend-adr-0016-a-vacated-seat-replaces-the-60-second-left-timer-244
feat/lint-against-hard-coded-copy-in-the-front-front-no-literal-copy-252
feat/translate-the-front-with-a-language-provider-english-french-242
docs/adr-front-i18n-paraglide
docs/stacked-prs
fix/render-build-fails-on-corepack-enable-record-the-hosting-adr-240
front/8-lint-error
front/7-local-home-align
front/6-comment-purge
front/5-cache-policy
front/3-dissolve-room-actions
front/4-tests-through-view
front/2-room-restructure
front/1-test-harness
feat/deploy-to-render-free-tier-with-a-preview-per-pr-233
harness/6-coding-standards
harness/5-adrs
harness/4-mechanical-rules
harness/3-drop-sandcastle
harness/2-skill-forks
harness/1-adr-index
claude/e2e-test-sub-agents-f8d06b
claude/e2e-hook-performance-072aa8
e2e-restart
e2e-spectator
e2e-draw-offer
e2e-resign-and-reload
e2e-mate-two-browsers
orchestrate-issue-168-implementation
implement-issue-169-and-pr
orpc-ws-room-feature
home-page-issues
comment-audit-and-rules
local/4-local-rail
local/3-local-board
local/2-design-prep
local/1-engine-accessors
prototype/home-page
prototype/game-screen-layout
worktree-front
chore/worktree-env-and-ports
feat/slice-1-3a-front-store-ws-effect-connection-status-screen-136
fix/143-release-seat-on-disconnect
claude/sandcastle-runner-contract
feat/slice-1-2a-apps-api-skeleton-hono-ws-echo-origin-allowlist-132
feat/slice-1-1-chess-contracts-package-context-md-cleanup-128
refactor/reorganise-src-into-layered-folders-per-adr-0008-123
refactor/refactor-engine-reorganise-src-into-layered-folders-per-adr-0008-123
refactor/introduce-the-piecereader-read-port-118
refactor/move-isattacked-to-attacks-ts-with-board-only-signature-111
feat/slice-b1-zobrist-key-computation-for-positions-99
refactor/slice-a-re-back-squareset-with-split-32-representation-97
sandcastle/sequential-reviewer/1779180017269
feat/san-formatter-core-encoding-moves-captures-en-passant-promotion-castling-92
sandcastle/sequential-reviewer/1779111400188
refactor/engine-pr-10-1-migrate-stalemate-into-a-draw-status-variant-86
sandcastle/sequential-reviewer/1779099667568
feat/engine-pr-9-1-castling-rights-tracking-updatecastlingrights-applymove-wiring-80
refactor/extract-piece-attacks-registry-and-rewire-isattacked-movegen-77
sandcastle/sequential-reviewer/1779027444485
backup/pre-axis-a-rewrite
Labels
Clear labels   
bug
Something isn't working

  
documentation
Improvements or additions to documentation

  
duplicate
This issue or pull request already exists

  
enhancement
New feature or request

  
good first issue
Good for newcomers

  
help wanted
Extra attention is needed

  
invalid
This doesn't seem right

  
question
Further information is requested

  
spec
Parent spec written by to-spec

  
wayfinder:grilling

   
wayfinder:map

   
wayfinder:prototype

   
wayfinder:research

   
wayfinder:task

   
wontfix
This will not be worked on

No labels
bug
documentation
duplicate
enhancement
good first issue
help wanted
invalid
question
spec
wayfinder:grilling
wayfinder:map
wayfinder:prototype
wayfinder:research
wayfinder:task
wontfix
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Blocks
#386 Show a self-game once, with both sides as You
amaurycoudr/chess-project
#387 Offer the claim on "My games", and forget a claimed Guest on sign-out
amaurycoudr/chess-project
Depends on
#381 Rate limits on sign-up, sign-in and reset requests, with when to try again
amaurycoudr/chess-project
#383 Account page: Username, email and join date, an export, and deletion by password
amaurycoudr/chess-project
#384 Names by Username in the Room, "My games" and the Game page; switching devices mid-Game end to end
amaurycoudr/chess-project
Reference
amaurycoudr/chess-project#385
No description provided.