43 lines
4.1 KiB
Markdown
43 lines
4.1 KiB
Markdown
## 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.
|