browser/openspec/changes/integrate-real-scum-ops-workflows/design.md

Context

The repository already has pieces of the SCUM integration: log ingest and game player projections, game client bridge commands and snapshots, protected SQL/RCON/program request dispatch, source RCON input fencing, AI config diffs, gift catalogs, player state patches, remote adapter declarations, and plugin manifest validation. The current product surface still exposes broad logs/terminal/config/history concepts and several SCUM pages are placeholder-like or depend on old snapshots instead of the current server's real SCUM.db and login logs.

The reference scum_robot and scum_run projects show the operational direction: the executor beside the game server can read SCUM.db, parse SCUM logs, query users/vehicles/flags/groups, and issue RCON commands for fame/currency. This change adapts that idea to this platform's boundaries: Platform owns intent, validation, audit, workflow records, and local projections; plugins own game-specific declarations; run/agent owns local machine execution and observed facts. The browser never receives raw SQL, host paths, DSNs, credentials, run sockets, or raw protected request text.

Goals / Non-Goals

Goals:

• Replace fake or placeholder SCUM data with real projections from login logs and the bound run/agent's SCUM.db observations.
• Add richer integrated operations: player profile refresh, player correction, fame/currency edits, attribute/stat mutation such as 855, gift delivery, vehicle inventory, squad/flag governance, realtime map overlays, AI config/draft assistance, and reconciliation.
• Introduce a sequential workflow layer so multi-step SCUM operations execute predictably with dependencies, approval, safety gates, confirmation reads, idempotency, and audit evidence.
• Keep internal logs, run channels, audit, source RCON, protected request fencing, lifecycle, and AI config approval intact while removing raw product-facing panels and APIs that invite unsafe manual operations.
• Keep implementation ownership split across platform/, platform_web/, and plugins/; implementation work for the independent run repository must remain outside this repository.

Non-Goals:

• Do not re-add a run/ source tree to this repository.
• Do not expose arbitrary SQL/RCON/terminal/config editing in browser APIs or plugin pages.
• Do not create billing, hosting sales, cloud provider workflows, or marketplace behavior unrelated to first-party game server management.
• Do not treat last_save_time as online-state proof by itself.
• Do not special-case SCUM lifecycle behavior in platform or run services; game-specific declarations stay in the SCUM plugin.

Decisions

1. Split reads, writes, and workflows

Realtime lists and maps use read observations. State-changing operations use typed operation declarations. Multi-step outcomes use workflows that compose observations and operations.

Alternative considered: keep a single protected.sql/database.request escape hatch. That is too broad for recurring product features and makes it impossible to validate field-level safety, permissions, and confirmation in the UI.

2. Query the current service through bound run/agent

SCUM.db is the real source for many facts, but only the run/agent next to the current service should read it. Platform will queue server-bound observation jobs using plugin-declared templates and persist typed results into local projections. Product pages read only projections.

Alternative considered: platform directly connects to SCUM.db through a configured path or socket. That violates run/platform ownership and leaks machine-specific execution details into control-plane code.

3. Prefer RCON for game-supported writes

Fame and currency updates follow the reference behavior using game commands such as #SetCurrencyBalance and #SetFamePoints. Database mutation is reserved for fields without a supported command path, such as declared player state/stat fields when the plugin marks them DB-only.

Alternative considered: update all editable fields directly in SCUM.db. That increases corruption risk and bypasses the game server's own command semantics where they exist.

4. Add typed mutation templates instead of browser SQL

The SCUM plugin will declare operation templates that include operation type, schema refs, transport, target, approval level, safety rules, before-value guards, affected-row bounds, and confirmation query keys. Platform validates requests against those declarations before creating run jobs.

Alternative considered: let admins type SQL into a protected request panel. That remains useful only as an emergency platform-admin tool, not as the backing mechanism for product workflows.

5. Store projections and workflow records locally

Platform needs local domain records for players, squads, members, vehicles, flags, current positions, observations, workflow instances, workflow steps, operation requests, and confirmations. These records power UI, API responses, stale-state visibility, idempotency, and audit.

Alternative considered: have every page dispatch live run queries. That couples UI responsiveness to run connectivity, duplicates query logic, and creates stale-data ambiguity.

6. Remove raw product surfaces, not core plumbing

The server detail experience should drop raw logs, terminal/RCON input, raw config workbench, and generic operation history. Internal log ingest, run log channels, audit records, source RCON execution, config diff approval, and lifecycle evidence remain available to services and typed workflow status.

Alternative considered: hide the panels but leave old APIs as-is. That keeps unsafe product paths alive and makes plugin/UI contracts harder to reason about.

Workflow Library

The implementation should create these first-party workflow templates and execute them in this order as they become available:

1. scum.bootstrap-real-data: verify run binding, declare SCUM.db/log sources, run schema probes, create observation cursors, and initialize stale projection records.
2. scum.player-refresh: parse login evidence, query SCUM.db player/economy/squad/position facts, upsert player projection, and update freshness.
3. scum.world-refresh: query squads, squad members, vehicles, flags, current positions, and observation checksums, then refresh map overlays.
4. scum.player-correction: validate player/offline state, approve typed edit, execute RCON or DB mutation, confirm by readback, and update projection.
5. scum.gift-delivery: evaluate schedule/eligibility, execute reward/notification, confirm result, and transition grant state.
6. scum.territory-audit: refresh squad/flag/member data, detect stale owner/member/flag inconsistencies, and create reviewable risk signals.
7. scum.vehicle-audit: refresh vehicle inventory, classify vehicle names, mark stale/missing observations, and update map inventory.
8. scum.ai-assist: collect allowed fields, generate reviewable config diff or workflow draft, validate, approve, dispatch, and confirm.
9. scum.product-cleanup: remove raw product panels/APIs and route users to typed workflow/status surfaces.

Each workflow step records serverInstanceId, workflowId, stepKey, source, capability, observedAt, receivedAt, sequence, checksum, attempt, status, safeSummary, and audit references where applicable.

Risks / Trade-offs

• [Risk] SCUM.db schema varies across game versions. → Mitigation: add version/schema probes, per-query result schemas, unknown-field handling, and plugin versioned templates.
• [Risk] SQLite reads can lock or lag during active server writes. → Mitigation: use bounded read-only execution, short timeouts, retry/backoff, and stale-state display instead of blocking product pages.
• [Risk] DB mutations can corrupt player state. → Mitigation: prefer RCON, require offline/maintenance safety windows, before-value guards, max affected rows, backup/snapshot evidence, and read-after-write confirmation.
• [Risk] Workflow retries can duplicate gifts or currency changes. → Mitigation: use idempotency keys, grant state locks, confirmation-before-retry, and unknown terminal states when execution cannot be proven.
• [Risk] Removing raw panels may hide useful diagnostics. → Mitigation: keep internal logs/audit/run evidence and expose safe workflow status summaries rather than raw terminal/log/config tools.
• [Risk] Run support lands in a separate repository. → Mitigation: define platform/plugin contracts here and track run-side implementation as an external dependency without adding run source here.

Migration Plan

1. Add platform domain/repository/API contracts for observations, projections, controlled operations, workflow instances, workflow steps, and confirmations.
2. Extend SCUM plugin manifest and validator schemas for read observation templates and typed operation templates.
3. Implement platform projection services for login logs and SCUM.db typed results, then wire job completion to projection updates.
4. Implement workflow queue and first workflow templates behind server/plugin permissions.
5. Replace SCUM plugin pages with projection-backed user, squad, vehicle, flag, map, gift, AI, and workflow views.
6. Remove raw product panels and APIs after new typed workflow/status views are available.
7. Coordinate run repository changes for local SCUM.db read templates and controlled operation execution; verify browser repo contracts with stubbed or mocked run results until the external run change lands.

Rollback keeps projections and workflow records but disables dispatch of new workflow steps through feature/config gates. Raw internal logs, audit, and lifecycle services remain untouched.

Open Questions

• Exact SCUM.db field mapping for player attribute/stat field 855 must be confirmed against real server schema before declaring a production mutation template.
• Whether DB-only player state mutations require full server stop or player-offline maintenance window depends on field category and must be recorded per operation template.
• Vehicle type naming should prefer plugin/static mapping or platform-maintained trade-good mapping; this can start as unknown/fallback to entity class until verified.
• Gift item delivery transport must be finalized per reward type: companion command, RCON command, or DB mutation with confirmation.