xonecas.io
60255
Zn

Zoea-Nova / files

Zoea-Nova / documentation / architecture / MYSIS_ACCOUNT_MANAGEMENT.md

6.2 KB
1# Mysis Account Management
2
3**Version:** 3.0  
4**Date:** 2026-02-09  
5**Status:** Truth Document
6
7---
8
9## Problem Statement
10
11Myses need game accounts to play SpaceMolt. Each mysis gets one account permanently assigned to eliminate timing races and enable reliable re-login. We need this account management to avoid polluting the server with more test accounts.
12
13**Constraint:** No changes to gameplay whatsoever. Myses must be able to call any game API freely.
14
15---
16
17## Truth Table
18
19| Mysis Action | Mysis State | Pool State | System Behavior | Mysis Sees |
20|--------------|-------------|------------|-----------------|------------|
21| Calls `register(username, empire)` | No assigned account | Pool has available accounts | Proxy assigns pool account permanently, mimics MCP response with pool account details | `{result: {password, player_id}, session: {id, player_id, ...}}` (thinks it registered) |
22| Calls `register(username, empire)` | No assigned account | Pool is empty | Proxy passes to game server, captures response, stores new account, assigns permanently | `{result: {password, player_id}, session: {...}}` (actually registered) |
23| Calls `register(username, empire)` | Has assigned account | Any | Proxy returns error pointing to `login()` with assigned credentials | Error response |
24| Calls `login(username, password)` | Has assigned account | Any | Proxy substitutes assigned account credentials, passes to game server | `{result: {player, ship, system, poi, ...}, session: {...}}` (logged into assigned account) |
25| Calls `logout()` | Any | Any | Proxy passes to game server (account remains assigned) | Success |
26| Lists tools | Any | Any | N/A - `zoea_claim_account` removed entirely | Only game tools visible |
27
28---
29
30## Behavior Rules
31
321. **Permanent assignment:** Once a mysis gets an account (via register), that account is permanently bound to `mysis_id` (stored in `assigned_to` field)
332. **First register - pool has accounts:** Proxy assigns pool account permanently, mimics game server `registered` response with pool account's password and player_id (never forwards to game server)
343. **First register - pool empty:** Proxy forwards register request to game server, captures response (password and player_id), stores new account in pool, assigns permanently to mysis
354. **Subsequent register:** When mysis with assigned account calls `register()`, proxy returns error: "Already have account. Use login(username, password)."
365. **Login substitution:** All `login()` calls from mysis with assigned account are silently substituted with assigned account credentials before passing to game server
376. **Account persistence:** Logout does NOT release account assignment - mysis keeps same account forever
387. **Account release:** Accounts return to pool ONLY when mysis is deleted/destroyed (assigned_to cleared)
398. **Internal claiming:** Account assignment is handled internally by proxy - no `zoea_claim_account` tool exists
40
41---
42
43## State Transitions
44
45```
46FIRST REGISTER - POOL HAS ACCOUNTS:
47Mysis: register(username, empire) → Proxy: assign_account(pool) → Proxy: mimic_MCP_response({result: {password, player_id}, session: {...}}) → Mysis: REGISTERED
48(Proxy never forwards to game server; mimics full MCP response structure with pool account credentials; account permanently bound to mysis_id)
49
50FIRST REGISTER - POOL EMPTY:
51Mysis: register(username, empire) → Game/MCP: {result: {password, player_id}, session: {...}} → Proxy: capture_response + store_account + assign_to_mysis → Mysis: REGISTERED
52(Request forwarded to game server; new account created; response captured; account stored in pool and permanently bound to mysis_id)
53
54SUBSEQUENT REGISTER:
55Mysis: register() → Proxy: error_response → Mysis: ERROR
56(Proxy returns MCP error: "Already have account. Use login(username, password).")
57
58LOGIN WITH ASSIGNED ACCOUNT:
59Mysis: login(any_user, any_pass) → Proxy: substitute(assigned_credentials) → Game/MCP: {result: {player, ship, system, poi, ...}, session: {...}} → Mysis: LOGGED_IN
60(Always logs into assigned account regardless of provided credentials; full game state returned)
61
62LOGOUT:
63Mysis: logout() → Game/MCP: success → Mysis: LOGGED_OUT
64(Account remains assigned to mysis_id for future login)
65
66MYSIS DELETION:
67Commander: delete_mysis() → Store: clear assigned_to → Pool gains available account
68```
69
70---
71
72## Verification
73
74| Scenario | Expected Outcome |
75|----------|------------------|
76| Pool has 3 accounts, new mysis calls register | Proxy mimics full MCP response with pool account's password/player_id/session (no game server call), account permanently assigned to mysis_id, pool has 2 available accounts |
77| Pool empty, new mysis calls register | Request forwarded to game server, MCP response captured (password/player_id/session), new account stored in pool and permanently assigned to mysis_id |
78| Mysis with assigned account calls register again | Mysis receives MCP error: "Already have account. Use login(username, password)." |
79| Mysis with assigned account calls login(wrong_user, wrong_pass) | Proxy substitutes assigned credentials, mysis gets full MCP response with `{result: {player, ship, system, poi, ...}, session: {...}}` for assigned account |
80| Mysis with assigned account calls logout | Mysis logged out, account remains assigned to mysis_id (can login again later) |
81| Mysis is deleted | Account's assigned_to cleared, account returns to available pool |
82| `make db-reset-accounts` run | All mysis assignments cleared (assigned_to = NULL), accounts return to pool, account details preserved |
83| Mysis lists tools | Only game tools visible (no `zoea_claim_account` - tool removed) |
84
85---
86
87## Implementation Files
88
89- `internal/mcp/proxy.go` - Register interception, permanent assignment, login credential substitution, tool filtering
90- `internal/constants/constants.go` - System prompt (no auth instructions)
91- `internal/store/accounts.go` - Account pool management with `assigned_to` field
92- `Makefile` - `db-reset-accounts` target must clear `assigned_to` while preserving account details
93
94---
95
96## Out of Scope
97
98- Review of other `zoea_*` tools (note: `zoea_claim_account` was removed entirely)
99- Account sharing between myses (one account = one mysis permanently)
100- Manual account reassignment (only via mysis deletion)