feat(scum): add bounded vehicle spawn adapter

2026-07-29 16:04:26 +08:00
parent 7ae4dbf0b2
commit daa0f330a4
24 changed files with 314 additions and 23 deletions
@@ -38,10 +38,16 @@ The alternative of metadata-only generic forms is insufficient for the map, play

 The Companion SHALL run a bounded dispatch loop after registration. It SHALL claim declared commands, validate the exact command schema and SCUM capability/version, execute only a registered handler, and acknowledge/completely report idempotent typed results. It SHALL produce no output containing raw paths, credentials, IPs, database rows, or arbitrary RCON command text. A version-bound typed UE4SS adapter MAY record the exact generated command text in the command's protected audit payload (for example, the fixed `#spawnvehicle <vehicleCode>` generated by `vehicle.spawn`); that audit record does not create a browser-visible or arbitrary-command RCON interface.

-The adapter SHALL include independent handlers for configuration read/patch, semantic log/event production, `reward.deliver`, `player.notify`, and `game-state.patch`. A handler unavailable for a discovered server version SHALL return an explicit unsupported result; the platform must keep the operation disabled.
+The adapter SHALL include independent handlers for configuration read/patch, semantic log/event production, `reward.deliver`, `player.notify`, `game-state.patch`, and the separately bounded `vehicle.spawn`. A handler unavailable for a discovered server version SHALL return an explicit unsupported result; the platform must keep the operation disabled.

 Direct raw-RCON or raw-SQL dispatch is rejected: legacy code is reference material only and must be translated into narrow typed adapters.

+### 3.1 Fixed vehicle-spawn adapter
+
+`vehicle.spawn` is the sole authorized exception for a generated SCUM command template. Its manifest payload contains exactly one `vehicleCode`, constrained by the plugin's versioned allowlist and identifier pattern. The Companion independently validates the same allowlist, requires its bound server, approval, declared handler capability, pinned UE4SS 3.0.1 build, and pinned reference revision before calling a Companion-local, platform-authorized vehicle-spawn transport port.
+
+The adapter itself creates the exact `#spawnvehicle <vehicleCode>` string and holds it only in a private transport/audit field. It accepts no command text, prefix, extra argument, target, shell text, SQL text, host path, socket, RCON credential, or reply text from callers. The pinned reference removes one leading `#` before dispatch, but the adapter does not infer completion from that implementation's unstructured response. The port returns a bounded receipt that the adapter maps to `succeeded`, `failed`, or `unknown`; unknown is never retried automatically. The plugin UI exposes only catalogued choices and enables its action only when the Companion reports the declared handler available.
+
 ### 4. Declared semantic event pipeline

 The Companion SHALL parse only plugin-declared allowed log/extension sources and upload contiguous typed semantic event batches using the durable log channel. Login/logout, player/vehicle position, and vehicle transitions SHALL be emitted only when their source and required fields can be validated. Map coordinate conversion, sampling, and retention declarations remain SCUM-plugin configuration.
@@ -5,8 +5,14 @@ Checked 2026-07-29 against the pinned read-only UE4SS reference at
 capability evidence is recorded in
 `plugins/examples/scum-server-plugin/companion/UE4SS_CAPABILITY.md`.

-The reference offers only a fixed, online-recipient `SendChat` path, which is
-already bounded by the supported `player.notify` adapter. It has no versioned
+The reference offers a fixed, online-recipient `SendChat` path, which is
+already bounded by the supported `player.notify` adapter. It also removes one
+leading `#` before dispatching a command, but its raw response is not a stable
+operation acknowledgement. Under the separately authorized fixed-template
+exception, the plugin's `vehicle.spawn` adapter can generate only
+`#spawnvehicle <vehicleCode>` from its allowlist through a local authorized
+transport port and maps its bounded receipt to success, failure, or unknown.
+It is not a general RCON surface. The reference otherwise has no versioned
 server-side schema, identity binding, acknowledgement contract, or isolated
 non-production fixture for login/logout events, network correlation, position
 or vehicle events, reward delivery, or state reads and writes.
@@ -6,6 +6,7 @@ The five recent SCUM deliveries implemented most SCUM-specific domain services a

 - Move SCUM-specific feature ownership for configuration, local game-player intelligence, controlled player state changes, gifts, and map trajectories into the SCUM plugin package and its Companion runtime.
 - Introduce a long-running, platform-authorized SCUM Companion adapter that receives only typed commands, emits only declared semantic events, and reports typed, idempotent results.
+- Add one explicitly enabled, version-bound `vehicle.spawn` operation. It accepts only plugin-catalogued vehicle codes and can generate only the fixed `#spawnvehicle <vehicleCode>` template through a Companion-local, platform-authorized transport port; it is not a raw-RCON interface.
 - **BREAKING** Replace platform-owned SCUM panels and SCUM-specific API/domain endpoints with a plugin-page module mounted by the generic platform plugin host.
 - **BREAKING** Replace platform-owned SCUM projections and persistence with plugin-scoped local data accessed through generic platform isolation, audit, job, and storage primitives.
 - Preserve the existing platform responsibilities for authorization, server/tenant isolation, review and approval, durable job delivery, audit records, retention enforcement, and generic page hosting.
@@ -11,6 +11,17 @@ The SCUM Companion SHALL run a bounded authenticated command-dispatch loop and S
 - **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

+### 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.
+
+#### 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
+
+#### 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
+
 ### 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.

@@ -29,6 +29,10 @@ The system SHALL expose a SCUM feature as actionable only when the installed plu
 - **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

+#### 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
+
 #### 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
@@ -32,7 +32,8 @@
 - [x] 5.2 Keep unsupported player state fields, versions, or unsafe windows disabled in the plugin UI and return explicit unsupported results from the Companion.
 - [ ] 5.3 Implement a `reward.deliver` adapter that freezes the approved revision, performs idempotent delivery, and reports delivered/failed/unknown without automatically retrying unknown results.
 - [x] 5.4 Implement a separate `player.notify` adapter that never repeats item delivery after notification failure; verify server-scoped recipient identity and redact message transport details.
- [ ] 5.5 Add isolated non-production end-to-end tests for every supported adapter and ensure no raw SQL, unrestricted RCON, OCR, screenshots, keyboard/mouse injection, or direct game database write path exists.
+- [x] 5.5 Implement the explicitly enabled, version-bound `vehicle.spawn` adapter with a strict vehicle-code catalog, the fixed internal `#spawnvehicle <vehicleCode>` template, protected audit text, structured success/failure/unknown outcomes, Companion-local transport fixture, and fail-closed UI availability.
+- [ ] 5.6 Add isolated non-production end-to-end tests for every supported adapter and ensure no raw SQL, unrestricted RCON, OCR, screenshots, keyboard/mouse injection, or direct game database write path exists.

 ## 6. Migrate transitional platform behavior safely