browser/openspec/changes/add-scum-player-state-patch/design.md

Context

The prior scum-game-player-intelligence change owns server-local player identity, sessions, risk signals, and access control. The existing game-client bridge supplies declared commands, approval states, leases, audit references, and result fencing, but it does not itself constrain individual game-state fields or maintain a readable player-change history.

Goals / Non-Goals

Goals:

• Permit only catalogued SCUM skills and character attributes for an explicitly declared server game version.
• Verify player/server ownership, current state version, companion availability, declared maintenance/online safety state, and platform-admin approval before dispatch.
• Record before/after value, reason, requester, approver, bridge command result, and read-after-write confirmation as an immutable patch audit.
• Prevent unknown versions, fields, out-of-range values, stale versions, unsafe execution windows, and unknown/failed execution from being represented as applied.

Non-Goals:

• SQL or database access, raw JSON/INI write APIs, host paths, direct Run/game connections, OCR/input automation, player identity/risk-signal edits, bans, gifts, or map trails.

Decisions

1. Catalog at the platform boundary. SCUMPlayerStateCatalog maps a declared server game version to a small list of field keys and numeric ranges. No caller or plugin payload can introduce fields dynamically. The initial exact version is 0.9.700.90357 and supports skills.running and attributes.strength in range 0–10.

2. Use a dedicated typed bridge operation. The manifest declares only game-state.patch, with a schema requiring target player ID, game version, expected state version, safety-window token, reason, and a list of catalogued changes. The result carries a bounded per-field outcome and an immediate confirmed state version; it contains no raw storage/database material.

3. Two-stage platform-admin approval. A server-authorized requester creates a durable patch record in pending-approval. A platform admin approves it after revalidating authorization, catalog, snapshot version, and safety window. Approval queues the bridge command and remains auditable; a requester who is also platform admin still creates then approves the explicit record.

4. Snapshot/state fencing and confirmation. A current player.state snapshot is the source of before values and its stateVersion is copied into the requested patch. The companion must reject mismatches, apply only declared fields in a verified maintenance/offline safety window, then read state back before returning success. Platform marks a record confirmed only when each returned value exactly equals its requested value and the returned state version advances. Failed and unknown results stay readable terminal audit states.

5. Ownership is revalidated at every transition. Player record lookup checks server ownership before viewing, creating, approving, or reading a patch. The bridge command is scoped to the same server plugin and profile; the generic queue cannot be used as an alternate raw patch entry point because the dedicated service owns field/snapshot validation and records the audit before dispatch.

Risks / Trade-offs

• [Companion has no exact version/state snapshot] → Disable the form and return a readable unsupported/unknown-version result.
• [State changes between snapshot and execution] → The expected state version causes the companion to reject; record the conflict without claiming application.
• [Companion times out or result is missing] → Keep the record execution-unknown; do not infer a write, and require a later confirmation read.
• [Maintenance state becomes unsafe] → Approval and companion both reject dispatch; no write is attempted.

Migration Plan

1. Add model-first patch records, memory/file/MySQL repositories, and immutable transition helpers.
2. Deploy the manifest schemas and companion version declaration; no version is implicitly supported.
3. Deploy the API and console. Existing player profiles retain all read-only intelligence behavior.
4. Roll back by disabling the command declaration and form; historical audit records remain readable.