browser/openspec/changes/replace-scum-projections-with-real-data-management/specs/scum-controlled-writes/spec.md

ADDED Requirements

Requirement: Effective-user permission enforcement

Every SCUM state-changing request SHALL be authorized against the current user's effective target-server permission at UI presentation, request creation, review/confirmation, and dispatch, with the backend as the authoritative enforcement point.

Scenario: Read-only operator opens a writable surface

• WHEN a user has server.game-client.read but lacks the required write permission
• THEN data remains readable, write controls are hidden or disabled with a textual reason, and a direct API attempt is forbidden

Scenario: Economy command is requested

• WHEN a user edits Fame, cash, or gold
• THEN Platform requires server.game-client.command and target-server access before accepting the named-field request

Scenario: Gift delivery is requested

• WHEN a user sends a declared gift package to a server-local player
• THEN Platform requires server.game-client.command, target-server access, and the gift capability's eligibility/idempotency checks before dispatch

Scenario: Database/XML attribute edit is requested

• WHEN a user edits a maintenance-level character attribute or preset
• THEN Platform requires server.game-client.maintenance, target-server access, a synchronous explicit danger confirmation, and the declared safety gates before dispatch; it SHALL NOT create a separate platform-admin approval domain or approval queue

Scenario: Plugin page receives permissions

• WHEN Platform Web constructs the plugin page host context
• THEN it supplies the current session's effective permissions rather than treating manifest-declared permissions or callback presence as proof of authority

Requirement: Manual and AI write-path parity

Manual forms and AI/Agent-originated SCUM changes SHALL create the same named-field draft and SHALL use the same allowlist, validation, effective-user authorization, review, dispatch, and confirmation service.

Scenario: AI suggests an allowed player change

• WHEN a user with the required write permission asks AI to change a declared player field
• THEN AI produces a reviewable target/player/field/current/proposed diff and no execution occurs until the user explicitly confirms it

Scenario: AI requester lacks write permission

• WHEN AI can generate or display a suggestion for a user who lacks the field's write permission
• THEN the apply action remains unavailable and an API attempt is forbidden; AI receives no component-principal bypass

Scenario: AI invents a field or protected payload

• WHEN an AI response contains an undeclared field, raw SQL, raw XML, raw RCON, path, credential, or arbitrary command
• THEN Platform rejects the draft and stores no executable protected payload from it

Requirement: Plugin-owned immutable write assets

The SCUM plugin SHALL own versioned typed command templates and guarded mutation declarations, and every executable write asset SHALL be digest-referenced by the plugin manifest and generated Run package.

Scenario: Declared write is dispatched

• WHEN Platform dispatches a confirmed named-field command or mutation draft
• THEN Run executes only the packaged asset whose plugin ID/version, adapter/schema version, action key, server binding, and digest all match the reviewed draft

Scenario: Write asset identity changed

• WHEN an action key, adapter version, packaged asset, or digest no longer matches the reviewed draft
• THEN Platform or Run rejects the write before any game command or database mutation executes

Requirement: Plugin-owned command execution

SCUM writes with a verified game command SHALL use plugin-owned typed command templates, and Platform and Run SHALL NOT hardcode SCUM command strings.

Scenario: Fame or currency is changed

• WHEN the compatible plugin adapter declares a supported Fame, normal-currency, or gold command
• THEN Platform dispatches its template key and validated parameters through the generic Run/RCON transport and performs the declared confirmation read

Scenario: Command template is not compatible

• WHEN the current plugin/game adapter cannot verify the command and confirmation contract
• THEN the write capability is disabled and SHALL NOT fall back to direct SQLite mutation or Platform-built command text

Requirement: Named and preserving XML attribute mutation

Character attribute writes SHALL target version-scoped named attributes or existing skill nodes in the profile XML source verified by the active current-service adapter and SHALL preserve all untargeted XML content.

Scenario: One allowed attribute changes

• WHEN Run reads a valid current XML document and applies an authorized and explicitly confirmed named-field change
• THEN only the targeted allowlisted attribute/node changes and unknown attributes, nodes, ordering-sensitive extensions, and all other values remain semantically intact

Scenario: Unknown field or missing skill is requested

• WHEN a requested attribute/skill is absent from the version adapter or the XML lacks the targeted existing skill node
• THEN Run rejects the mutation and SHALL NOT invent a node, default an Attribute value, or rewrite the document from an incomplete struct

Scenario: XML is malformed

• WHEN the current adapter-confirmed profile XML payload cannot be parsed by the preserving patcher
• THEN no database write occurs and Platform receives a bounded safe failure

Requirement: 855 is an explicit preset, not a database field

The system SHALL NOT declare or execute 855 as a table column or generic integer field; it MAY expose 855 only after an operator-confirmed preset maps it to explicit version-scoped named character attributes and values.

Scenario: Preset meaning is not confirmed

• WHEN the plugin adapter has no reviewed mapping for the 855 label
• THEN the preset is absent/disabled and no fieldKey=855, prisoner.value, or 0..100000 mutation can be created

Scenario: Confirmed preset is reviewed

• WHEN a compatible adapter declares the preset and an authorized user selects it
• THEN the review shows every named attribute's current and proposed value rather than a single opaque 855 value

Requirement: Guarded single-row database mutation

Every database/XML mutation SHALL require a current compatible probe, target identity, expected before values/checksum, reason, idempotency key, genuine same-server backup evidence, required offline/maintenance evidence, a single-row bound, and read-after-write confirmation.

Scenario: Safety evidence is missing or fabricated

• WHEN the player's online state is unknown/unsafe, maintenance is unverified, the backup reference is absent/not restorable/not for the same database instance, or a timestamp-shaped placeholder is supplied
• THEN Platform rejects dispatch and no mutation job is created

Scenario: Current value changed

• WHEN the row identity, current value, XML digest, or schema fingerprint no longer matches the reviewed before state
• THEN Run aborts the transaction as a conflict without applying the requested value

Scenario: Affected row count is not one

• WHEN a mutation would affect zero or more than one row
• THEN Run rolls back and reports failure

Scenario: Readback does not confirm the target values

• WHEN execution may have occurred but the confirmation read is missing or mismatched
• THEN Platform SHALL NOT report success and SHALL require confirmation before any explicit retry

Scenario: Attribute save completes

• WHEN the single-row mutation and readback confirm every named target value and new digest
• THEN Platform records the safe result and updates local verified details without exposing the raw XML

Requirement: No implicit destructive activation

Saving character attributes SHALL NOT implicitly kill, respawn, kick, or otherwise disrupt the player.

Scenario: Game requires respawn for new values

• WHEN current-service verification shows a respawn/death action is necessary for activation
• THEN that action is a separate explicitly named destructive command with its own permission and fresh user confirmation and is not automatically chained to attribute save