Add SCUM operations workflow OpenSpec
This commit is contained in:
npc0-hue
+63
@@ -0,0 +1,63 @@
|
||||
## 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
|
||||
@@ -0,0 +1,67 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: SCUM user management surface
|
||||
The system SHALL provide a SCUM user management surface backed by local projections from login logs and SCUM.db observations.
|
||||
|
||||
#### Scenario: Player list renders real records
|
||||
- **WHEN** an operator opens SCUM user management
|
||||
- **THEN** the page lists real player records with source, identity, character name, profile ID, Steam/user ID when known, squad, balances, fame, coordinates, online/session status evidence, and last observation freshness
|
||||
|
||||
#### Scenario: Player edit opens typed workflow
|
||||
- **WHEN** an operator edits fame, currency, gift eligibility, or declared player state fields
|
||||
- **THEN** the page creates a typed operation workflow for review/approval instead of editing projected values directly
|
||||
|
||||
### Requirement: Squad and flag management surface
|
||||
The system SHALL provide squad and flag management backed by real `squad`, `squad_member`, `user_profile`, `base_element`, and related SCUM observations where available.
|
||||
|
||||
#### Scenario: Squad page shows roster and territory
|
||||
- **WHEN** an operator opens squad management
|
||||
- **THEN** the page shows squads, members, ranks, leader, linked flags, member/player projection freshness, and unknown fields without fabricated owners or coordinates
|
||||
|
||||
#### Scenario: Flag page shows stale ownership
|
||||
- **WHEN** a flag observation is stale or owner data cannot be verified
|
||||
- **THEN** the page marks the flag stale or unknown and offers a refresh workflow rather than inventing owner data
|
||||
|
||||
### Requirement: Realtime map surface
|
||||
The system SHALL provide a realtime SCUM map surface where players, vehicles, flags, squads, and selected risk overlays use platform-local projections and freshness state.
|
||||
|
||||
#### Scenario: Map renders current projections
|
||||
- **WHEN** map data is fresh enough for display
|
||||
- **THEN** the page overlays players, vehicles, flags, squad territory, last-observed timestamps, and source confidence from local projections
|
||||
|
||||
#### Scenario: Map data is stale
|
||||
- **WHEN** the map has stale or missing projections
|
||||
- **THEN** the page shows stale status and refresh workflow controls without using sample points, fake routes, or placeholder coordinates
|
||||
|
||||
### Requirement: Gift management surface
|
||||
The system SHALL provide gift catalog, schedule, eligibility, approval, delivery, notification, confirmation, and claim-state management using typed workflows.
|
||||
|
||||
#### Scenario: Scheduled gift becomes eligible
|
||||
- **WHEN** a daily, weekly, monthly, yearly, one-time, or multi-per-day gift rule becomes eligible for a player type or achievement condition
|
||||
- **THEN** platform creates a gift delivery workflow and marks the grant delivered only after typed run/companion result and confirmation succeed
|
||||
|
||||
#### Scenario: Delivery result unknown
|
||||
- **WHEN** delivery dispatch succeeds but confirmation is missing or ambiguous
|
||||
- **THEN** platform marks the grant unknown or pending-confirmation and prevents duplicate delivery until reconciliation completes
|
||||
|
||||
### Requirement: AI assistant remains for typed configuration and workflows
|
||||
The system SHALL keep the AI assistant as a first-party helper for plugin setup, config diffing, and operation drafts while routing all proposed effects through reviewable typed diffs or workflows.
|
||||
|
||||
#### Scenario: AI configures plugin settings
|
||||
- **WHEN** an operator asks AI to configure the SCUM plugin
|
||||
- **THEN** AI can propose changes only for plugin-declared config fields, platform validates the diff, and approved changes use the existing config approval/dispatch path
|
||||
|
||||
#### Scenario: AI suggests operation workflow
|
||||
- **WHEN** AI suggests a player correction, gift rule, map refresh, squad audit, or vehicle audit
|
||||
- **THEN** platform creates a draft workflow request that requires human review before execution
|
||||
|
||||
### Requirement: Raw product surfaces removed
|
||||
The system SHALL remove product-facing raw log, management terminal/RCON input, arbitrary config workbench, and generic operation history pages and dedicated APIs from the server detail experience.
|
||||
|
||||
#### Scenario: Server detail route list is built
|
||||
- **WHEN** platform_web builds server detail navigation and plugin workspace contracts
|
||||
- **THEN** it excludes raw logs, management terminal, arbitrary config editor, and generic operation-history views while preserving AI assistant, typed workflows, lifecycle status, internal log ingest, audit, and run channels
|
||||
|
||||
#### Scenario: Raw endpoint is requested
|
||||
- **WHEN** a browser calls a removed product-layer raw logs, terminal, arbitrary config, or operation-history API
|
||||
- **THEN** platform returns not found or the new typed workflow/status API without exposing raw terminal, raw SQL, raw host paths, or raw config editing capability
|
||||
+56
@@ -0,0 +1,56 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Authentic player identity creation
|
||||
The system SHALL create and update SCUM player identity records only from authentic SCUM login/logout log observations and verified SCUM.db facts reported by the bound run/agent for the current server instance.
|
||||
|
||||
#### Scenario: Login log creates player record
|
||||
- **WHEN** run ingests a plugin-declared SCUM `login_*.log` line for a server-bound Steam/user identifier and character name
|
||||
- **THEN** platform stores or updates the matching local game player, player session, source log metadata, observed time, and confidence without inventing missing profile fields
|
||||
|
||||
#### Scenario: Logout log updates session
|
||||
- **WHEN** run ingests a matching logout observation for a known player session
|
||||
- **THEN** platform closes or marks the local session with the observed logout time while preserving historical login evidence
|
||||
|
||||
### Requirement: Bound SCUM.db read observations
|
||||
The system SHALL obtain player, squad, vehicle, flag, position, economy, and observation facts from SCUM.db through server-bound run/agent jobs that execute plugin-declared read templates against the current service machine.
|
||||
|
||||
#### Scenario: Current service database is queried
|
||||
- **WHEN** a server instance has an active run binding with the declared SCUM SQLite read capability
|
||||
- **THEN** platform queues declared read observation jobs for that server instance, run executes them against the local SCUM.db, and platform receives typed rows without exposing host paths, DSNs, sockets, or SQL text to the browser
|
||||
|
||||
#### Scenario: Database unavailable
|
||||
- **WHEN** the bound run reports SCUM.db missing, locked, schema-incompatible, or unavailable
|
||||
- **THEN** platform records the observation failure and marks affected projections stale without replacing existing values with generated or placeholder data
|
||||
|
||||
### Requirement: Local projection surfaces
|
||||
The system SHALL persist local projections for players, squads, squad members, vehicles, flags, current positions, and data observations before any product surface reads them.
|
||||
|
||||
#### Scenario: Typed result updates projections
|
||||
- **WHEN** platform accepts a successful typed query result for a server/plugin/query binding
|
||||
- **THEN** it validates schema, checksum, row bounds, observed time, and server binding before upserting the corresponding projection records
|
||||
|
||||
#### Scenario: Page reads projection only
|
||||
- **WHEN** platform_web or a plugin page renders SCUM users, squads, vehicles, flags, or map positions
|
||||
- **THEN** it reads platform-local projections and freshness metadata rather than directly querying run, SCUM.db, or sample data
|
||||
|
||||
### Requirement: Freshness and conflict handling
|
||||
The system SHALL keep observation sequence, checksum, observedAt, receivedAt, and fresh/stale state for every projected SCUM data category.
|
||||
|
||||
#### Scenario: Older observation arrives after newer one
|
||||
- **WHEN** platform receives an observation whose sequence or observedAt is older than the current projection for the same source key
|
||||
- **THEN** platform rejects it for projection while keeping an audit-safe observation record
|
||||
|
||||
#### Scenario: Query failure after successful projection
|
||||
- **WHEN** a later read observation fails after a prior successful projection exists
|
||||
- **THEN** platform keeps the last-known-good projection, records the failure, and exposes stale status to the UI
|
||||
|
||||
### Requirement: Unknown fields stay unknown
|
||||
The system SHALL represent missing or unverifiable SCUM fields as unknown, absent, or stale instead of deriving fake values from unrelated tables or timestamps.
|
||||
|
||||
#### Scenario: Steam ID missing from SCUM.db row
|
||||
- **WHEN** a SCUM.db player row has a user_profile_id but no verified user_id/Steam identifier
|
||||
- **THEN** platform stores the profile identifier separately and marks the external player identifier unknown rather than treating user_profile_id as Steam ID
|
||||
|
||||
#### Scenario: last_save_time is present
|
||||
- **WHEN** a prisoner row includes `last_save_time`
|
||||
- **THEN** platform may use it as data freshness evidence but SHALL NOT use it alone as online-state proof
|
||||
+68
@@ -0,0 +1,68 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Sequential workflow definitions
|
||||
The system SHALL define SCUM workflows as ordered typed steps with dependencies, inputs, permissions, safety gates, execution transport, confirmation, retry policy, and blocking states.
|
||||
|
||||
#### Scenario: Workflow starts with dependencies
|
||||
- **WHEN** a workflow instance is created for a server instance
|
||||
- **THEN** platform evaluates dependency steps and dispatches only the first runnable step whose prerequisites are satisfied
|
||||
|
||||
#### Scenario: Step depends on projection freshness
|
||||
- **WHEN** a step requires fresh player, squad, vehicle, flag, or position projections
|
||||
- **THEN** platform runs or waits for the required observation workflow before dispatching the dependent write or UI-facing step
|
||||
|
||||
### Requirement: One-by-one execution per server
|
||||
The system SHALL execute SCUM workflow steps one by one per server instance when steps mutate game state, while allowing safe read observation steps to run with bounded concurrency.
|
||||
|
||||
#### Scenario: Two write workflows are queued
|
||||
- **WHEN** two player mutation or gift-delivery workflows target the same server instance
|
||||
- **THEN** platform dispatches the next state-changing step only after the prior state-changing step reaches confirmed, failed, blocked, cancelled, or unknown terminal state
|
||||
|
||||
#### Scenario: Read observation workflows are queued
|
||||
- **WHEN** multiple read observation steps target players, squads, vehicles, and flags
|
||||
- **THEN** platform may batch or parallelize them within declared row, timeout, and concurrency limits without violating run channel priority
|
||||
|
||||
### Requirement: Integrated SCUM workflow library
|
||||
The system SHALL provide first-party workflow templates for common SCUM operations that combine real data reads, typed writes, and product-state updates.
|
||||
|
||||
#### Scenario: Player profile refresh workflow
|
||||
- **WHEN** an operator refreshes a player profile
|
||||
- **THEN** platform runs login evidence sync, player SCUM.db lookup, economy lookup, squad membership lookup, current position lookup, and projection update as one tracked workflow
|
||||
|
||||
#### Scenario: Player correction workflow
|
||||
- **WHEN** an operator approves a player correction
|
||||
- **THEN** platform runs safety check, before-value read, RCON or DB mutation, confirmation read, projection update, and audit completion in order
|
||||
|
||||
#### Scenario: Gift delivery workflow
|
||||
- **WHEN** a gift grant becomes eligible by schedule, player type, achievement, or manual approval
|
||||
- **THEN** platform runs eligibility check, inventory/reward operation, player notification, confirmation read/result, and grant-state transition in order
|
||||
|
||||
#### Scenario: Territory risk workflow
|
||||
- **WHEN** an operator opens squad or flag governance
|
||||
- **THEN** platform can run squad roster refresh, flag ownership refresh, member-position overlay, stale-owner detection, and risk-signal projection without direct browser database access
|
||||
|
||||
#### Scenario: Vehicle inventory workflow
|
||||
- **WHEN** an operator requests vehicle inventory/map refresh
|
||||
- **THEN** platform runs vehicle query, coordinate projection, owner/nearby squad enrichment where available, stale vehicle marking, and map overlay update
|
||||
|
||||
#### Scenario: AI configuration workflow
|
||||
- **WHEN** an operator asks AI to configure or tune the SCUM plugin
|
||||
- **THEN** platform gathers allowed plugin config fields, generates a reviewable diff, validates the diff, dispatches approved writes through existing config approval, and reports completion
|
||||
|
||||
### Requirement: Workflow status and audit evidence
|
||||
The system SHALL expose workflow status, current step, blocker reason, retry count, confirmation status, stale data references, and audit references through safe product APIs.
|
||||
|
||||
#### Scenario: Workflow blocks on missing run
|
||||
- **WHEN** a workflow step requires bound run execution but no current run session can claim the capability
|
||||
- **THEN** platform marks the workflow blocked with a safe reason and does not leak machine paths, tokens, sockets, or protected payload text
|
||||
|
||||
#### Scenario: Workflow completes
|
||||
- **WHEN** all required steps reach terminal success and confirmations pass
|
||||
- **THEN** platform marks the workflow confirmed, links audit evidence, and updates the relevant player, squad, vehicle, flag, gift, or configuration projection
|
||||
|
||||
### Requirement: Retry without duplicating game effects
|
||||
The system SHALL apply idempotency keys, fencing tokens, and confirmation reads so retries do not duplicate gifts, duplicate currency updates, or overwrite newer player state.
|
||||
|
||||
#### Scenario: Run loses connection after command dispatch
|
||||
- **WHEN** run disconnects after a state-changing command may have executed
|
||||
- **THEN** platform performs a confirmation read before deciding whether to retry, mark unknown, or mark confirmed
|
||||
Reference in New Issue
Block a user