browser/openspec/changes/integrate-real-scum-ops-workflows/specs/scum-controlled-operations/spec.md

ADDED Requirements

Requirement: Typed SCUM operation catalog

The system SHALL expose SCUM write capabilities only as typed operation declarations with schemas, permissions, approval level, execution transport, safety rules, and confirmation rules.

Scenario: Manual player attribute edit

• WHEN an operator requests a player attribute/stat edit such as field 855
• THEN platform creates a typed operation request containing player identity, field key, before value, after value, reason, requester, safety window, and idempotency key rather than accepting raw SQL from the browser

Scenario: Operation declaration missing

• WHEN a plugin page, platform service, or AI assistant requests an operation type not declared by the SCUM plugin manifest and platform validator
• THEN platform rejects the request before any run job or protected request is created

Requirement: Prefer game commands over database writes

The system SHALL route SCUM write operations through game-supported commands such as RCON whenever a safe command exists, and SHALL use database mutation only for fields without a declared command path.

Scenario: Fame and currency update

• WHEN a user requests player fame, normal currency, or gold changes
• THEN platform dispatches typed RCON operations using declared command templates and confirmation reads rather than issuing direct SCUM.db update statements

Scenario: No game command exists

• WHEN a requested field is declared as database-only by the plugin operation catalog
• THEN platform dispatches a bounded DB mutation job with the declared template, parameter schema, row limit, before-value guard, and confirmation query

Requirement: Approval and permission gates

The system SHALL require role permission, operation approval, and lease-fenced run execution for all state-changing SCUM operations.

Scenario: Operator requests platform-admin operation

• WHEN an operator without platform-admin role requests a platform-admin SCUM mutation
• THEN platform stores no executable payload and returns a forbidden result

Scenario: Approved operation is claimed by run

• WHEN an approved operation creates a run job
• THEN run receives the executable request only through a current lease and fencing token, and platform stores only redacted or typed audit-safe payloads

Requirement: Safety windows for database mutation

The system SHALL require database mutations to pass configured safety checks such as player offline, maintenance verified, current-value match, bounded affected rows, and backup/snapshot evidence.

Scenario: Player is online

• WHEN a database-only player state mutation is requested while the latest verified projection shows the player online or safety state unknown
• THEN platform blocks dispatch and records the request as waiting for an offline/maintenance safety window

Scenario: Current value changed

• WHEN run attempts a DB mutation and the current DB value no longer matches the approved before value
• THEN run reports a stale-write failure and platform keeps the operation unconfirmed

Requirement: Read-after-write confirmation

The system SHALL mark SCUM write operations successful only after run reports execution success and platform accepts a typed confirmation observation proving the requested values now exist.

Scenario: Command queued but not confirmed

• WHEN RCON or DB mutation dispatch succeeds but confirmation read is missing or mismatched
• THEN platform marks the operation pending-confirmation, failed-confirmation, or unknown instead of successful

Scenario: Confirmation succeeds

• WHEN the confirmation read returns the expected typed values, row identity, checksum, and observedAt
• THEN platform marks the operation confirmed, updates local projections, and records audit evidence

Requirement: AI produces reviewable operations only

The system SHALL allow AI assistant output to create reviewable typed configuration diffs or typed SCUM operation drafts, but SHALL NOT allow AI to execute RCON, SQL, or file writes directly.

Scenario: AI suggests a player correction

• WHEN AI suggests changing a player attribute, fame, currency, gift eligibility, or plugin configuration value
• THEN platform presents a typed diff or operation draft for human review and approval before any run-side execution can occur