refactor(scum): use runtime capability probes

2026-07-29 18:34:16 +08:00
parent 03339fb3e8
commit d7465bfd32
26 changed files with 530 additions and 533 deletions
@@ -1,45 +1,52 @@
 ## ADDED Requirements

-### Requirement: Companion dispatches only declared typed SCUM operations
-The SCUM Companion SHALL run a bounded authenticated command-dispatch loop and SHALL execute only command types declared by the installed SCUM plugin, validated against their payload schema, server binding, permission/approval result, and compatible SCUM capability/version. It SHALL return an idempotent typed result for every claimed command.
+### Requirement: Companion uses runtime capability isolation

-#### Scenario: Supported gift delivery command
- **WHEN** the Companion claims a valid, unexpired `reward.deliver` command for a server version with a registered delivery handler
- **THEN** it executes only that handler and completes the command with a typed delivered, failed, notification-failed, or unknown result
+The SCUM Companion SHALL dispatch only declared typed handlers bound to its
+authorized server. Handler availability SHALL come from runtime capability and
+schema probes, not a game, UE4SS, database, build, revision, or version gate.
+A probe or command failure SHALL affect only that handler invocation.

-#### Scenario: Unsupported or malformed command
- **WHEN** the Companion claims a command whose type, schema, capability, or version is not supported
- **THEN** it does not invoke SCUM, RCON, a database, OCR, or desktop automation and completes the command with an explicit unsupported or validation failure result
+#### Scenario: A runtime adapter is unavailable

-### Requirement: Vehicle spawn uses one fixed, version-bound template
-The SCUM Companion SHALL execute `vehicle.spawn` only when the installed plugin declares it, the bound server is approved, the Companion reports its handler available, and the pinned UE4SS 3.0.1 build/reference revision is present. The payload SHALL contain exactly one plugin-allowlisted vehicle code matching the declared identifier pattern. The adapter SHALL generate exactly `#spawnvehicle <vehicleCode>` internally and SHALL retain that text only in protected transport/audit data. It SHALL not accept or expose raw command text, additional arguments, targets, RCON credentials, sockets, shell/SQL text, host paths, or raw transport replies. It SHALL return a structured `succeeded`, `failed`, or `unknown` outcome and SHALL not automatically retry an unknown outcome.
+- **WHEN** a typed port or schema probe is unavailable
+- **THEN** the Companion returns a typed unavailable/failed/unknown result for
+  that command and does not disable an unrelated plugin feature

-#### Scenario: Approved, supported vehicle spawn
- **WHEN** an approved `vehicle.spawn` command carries a declared vehicle code for the pinned UE4SS adapter and the local authorized transport reports acceptance
- **THEN** the Companion sends only the internally generated fixed template, completes with a structured `succeeded` outcome, and omits the generated text from the command result
+### Requirement: Run data channels are bounded

-#### Scenario: Unsafe vehicle-spawn input or unavailable handler
- **WHEN** a vehicle-spawn payload has an unlisted code, extra field, command text, target, credential, or the Companion has not declared the compatible handler
- **THEN** the Companion performs no transport call and returns validation-failed or unsupported without exposing protected audit text
+Run SHALL send SCUM stdout/stderr records to the Companion through the durable
+log channel and SHALL provide database data only as typed allowlisted
+projections and fixed server-management operations. No plugin, web page, or
+AI request SHALL receive a path, DSN, credential, raw row, arbitrary SQL,
+shell, socket, or RCON command.

-### Requirement: Companion emits validated semantic SCUM events
-The SCUM Companion SHALL collect only declared allowed sources and upload contiguous semantic event batches through the platform's durable log channel. It SHALL validate required event fields before upload and SHALL not emit raw IP addresses, network fingerprints, host paths, credentials, database rows, screenshots, or arbitrary RCON command text. A version-bound typed UE4SS adapter MAY retain the exact generated command text in protected command audit data; it SHALL never expose that text as a general RCON command surface or semantic event payload.
+#### Scenario: Unknown console output

-#### Scenario: Valid login event
- **WHEN** a supported SCUM source produces a successful-login record containing the declared player identity and timestamp fields
- **THEN** the Companion uploads a validated `scum.login` semantic event and the plugin can create or update the local game-player profile
+- **WHEN** stdout or stderr does not match a declared semantic parser
+- **THEN** the Companion records a bounded diagnostic and uploads no semantic
+  event or raw line

-#### Scenario: Unknown source format
- **WHEN** a log or extension source does not match a supported parser version or lacks required fields
- **THEN** the Companion records a bounded diagnostic and does not fabricate a semantic login, position, vehicle, or security event
+### Requirement: Mutations prove safety

-### Requirement: Map event collection remains controlled
-The SCUM Companion SHALL emit `player.position`, `vehicle.position`, `player.vehicle.enter`, and `player.vehicle.leave` only from a verified legitimate server-side source declared by the plugin. The plugin SHALL apply its declared coordinate transform, sampling precision, and retention policy before exposing trajectory data.
+State patch adapters SHALL use field allowlists, a pre-read, safe-window
+verification, a bounded write, and read-after-write confirmation. Reward
+adapters SHALL freeze their typed grant and return delivered, failed, or
+unknown without automatically retrying unknown outcomes.

-#### Scenario: Position source is unavailable
- **WHEN** no supported server-side source can provide a validated player or vehicle position
- **THEN** the trajectory page reports collection unavailable and does not use OCR, screenshots, keyboard/mouse injection, client-screen reading, or inferred synthetic tracks
+#### Scenario: Confirmation cannot be established

-#### Scenario: Cross-server isolation
- **WHEN** events are emitted for two bound SCUM servers
- **THEN** the Companion tags each batch with its bound server identity and no trajectory, player, or vehicle data from one server is returned for the other
+- **WHEN** a typed write or post-write read cannot establish success
+- **THEN** the Companion returns `unknown` and does not repeat the operation
+
+### Requirement: Vehicle spawning remains fixed
+
+`vehicle.spawn` SHALL accept only a catalogued vehicle code and create exactly
+`#spawnvehicle <vehicleCode>` inside the Companion. Protected audit text SHALL
+not be present in command results or browser payloads.
+
+#### Scenario: Unsafe spawn input
+
+- **WHEN** input includes an unlisted code, an extra field, command text, SQL,
+  a path, credential, socket, shell text, or RCON text
+- **THEN** no transport call occurs and validation fails
@@ -1,38 +1,37 @@
 ## ADDED Requirements

 ### Requirement: SCUM feature ownership is plugin-local
-The system SHALL place SCUM-specific configuration semantics, player/gift/map/state-patch behavior, schemas, validators, Companion handlers, and feature UI modules in the SCUM plugin package. The platform SHALL expose only generic authorization, isolation, audit, storage, queue, retention, and plugin-host primitives and SHALL NOT add new SCUM-named domain services, API handlers, or frontend panels.

-#### Scenario: A new SCUM capability is added
- **WHEN** a SCUM-specific configuration field, event type, command, or view is introduced
- **THEN** its implementation and tests are added to the SCUM plugin package while the platform change, if any, is reusable by non-SCUM plugins
+The SCUM plugin SHALL own SCUM schemas, allowlists, migration adapters,
+Companion behavior, and feature UI. The platform SHALL retain only reusable
+authorization, isolation, auditing, queues, storage, and generic plugin-host
+primitives. `platform_web` SHALL not import SCUM code or branch on `game.scum`.

-#### Scenario: Existing platform SCUM code is migrated
- **WHEN** an existing SCUM service or panel is replaced by its plugin equivalent
- **THEN** the platform retains only a generic primitive and no hard-coded `game.scum` branch or SCUM component import remains in the plugin host
+#### Scenario: Page mounting

-### Requirement: Plugin-owned pages mount in the platform host
-The SCUM plugin SHALL declare versioned page-module entries and their required permissions/capabilities. The platform web host SHALL mount the declared module inside the existing authenticated themed shell and SHALL pass only server-scoped, permission-filtered host context.
+- **WHEN** an authorized administrator opens the installed plugin route
+- **THEN** the generic host mounts the declared plugin bundle with only
+  server-scoped permission context

-#### Scenario: Authorized administrator opens a SCUM page
- **WHEN** an administrator with the declared permission opens a SCUM plugin route for an assigned server
- **THEN** the host loads the SCUM-declared page module with that server-scoped context and does not use a platform-owned SCUM page implementation
+### Requirement: Feature availability is runtime scoped

-#### Scenario: Page module is unavailable or incompatible
- **WHEN** the declared SCUM page bundle fails integrity/version/capability validation
- **THEN** the host shows an unavailable-page state and does not fall back to a hard-coded SCUM panel
+The plugin SHALL expose a feature as actionable only when its declared
+Companion handler or event producer is currently available for that server.
+Availability SHALL not be gated by a game or adapter version/build/revision.

-### Requirement: Feature availability requires a plugin implementation
-The system SHALL expose a SCUM feature as actionable only when the installed plugin declares the feature and its Companion reports a compatible handler or event producer for the bound server version. Transitional platform records MAY be displayed as migrated read-only history but SHALL NOT imply executable capability.
+#### Scenario: One adapter fails

-#### Scenario: Unsupported state patch adapter
- **WHEN** the bound SCUM version has no verified `game-state.patch` handler
- **THEN** the plugin disables the edit control and reports that the version is unsupported without queuing a generic command
+- **WHEN** a schema probe for state patching fails
+- **THEN** state patching is unavailable with a typed reason while other
+  declared capabilities remain independently available

-#### Scenario: Vehicle spawn handler is unavailable
- **WHEN** the bound Companion does not report the declared `vehicle.spawn` handler for its compatible version
- **THEN** the plugin keeps vehicle spawning unavailable and does not display a raw command field or queue a generic RCON command
+### Requirement: Transitional records are read-only migration input

-#### Scenario: Historical records during migration
- **WHEN** records created by the transitional platform implementation exist for a bound server
- **THEN** the plugin can display them with migration provenance while new writes use the plugin-owned feature path
+Platform records MAY be displayed with provenance while plugin-owned records
+become authoritative per server and feature. Migration flags SHALL be scoped
+to the server and feature, never to a game version.
+
+#### Scenario: Migration flag is absent
+
+- **WHEN** no unique server-feature migration flag is present
+- **THEN** historical records remain readable and plugin writes stay disabled