admin343/browser
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Integrate SCUM real ops workflows

Browse Source
This commit is contained in:
npc0-hue
2026-08-10 21:12:53 +08:00
parent 1063330710
commit a770bc6250
88 changed files with 6375 additions and 2719 deletions
Download Patch File Download Diff File Expand all files Collapse all files
platform/protocol/scum-run-integration.md
+67
View File
@@ -0,0 +1,67 @@
# SCUM Run Integration Contract
This repository defines the platform/plugin side of SCUM real-data operations. The executable machine-side implementation belongs in the independent `git@git.npc0.com:admin343/run.git` repository and must not be added here.
## Ownership Boundary
- Platform owns server instances, authorization, audit, local projections, typed operation/workflow records, idempotency, approval state, and safe browser APIs.
- The SCUM plugin owns query template keys, operation template keys, result schemas, safety rules, confirmation schemas, and lifecycle action assets.
- Run owns local machine execution beside the current SCUM service: locating the declared logical SCUM.db/log/RCON targets from its scoped package, executing bounded jobs, and returning typed results through existing signed job channels.
Run must never send host paths, DSNs, sockets, credentials, raw SQL, raw RCON text, or protected request bodies to browser/product APIs. Platform persists only safe job metadata, projection rows, checksums, confirmation summaries, and audit references.
## Read Observation Jobs
Run must implement plugin-declared SQLite read templates for the current server binding and return rows matching the referenced schema files under `plugins/examples/scum-server-plugin/schemas/bridge/queries/`.
Required template keys:
| Key | Required behavior |
| --- | --- |
| `scum.player.profile` | Read player identity, profile ID, optional Steam/user ID, character/prisoner fields, economy balances, squad summary, and current coordinates where available. |
| `scum.squads` | Read squad IDs, names, leader/profile references, and bounded member counts. |
| `scum.squad-members` | Read roster membership, ranks, player/profile references, and unknown fields without fabricating missing identities. |
| `scum.vehicles` | Read vehicle/entity rows and coordinates; unknown class/name mappings remain unknown. |
| `scum.flags` | Read base flag/entity ownership, squad/player confidence, and coordinates where available. |
| `scum.positions` | Read current player, vehicle, and flag coordinate projections. |
Each successful result must include the server binding, template key, observed time, monotonically comparable sequence, row count within manifest bounds, and `sha256:<hex>` checksum. Failures must return safe error codes such as missing database, locked database, schema mismatch, timeout, or row-bound exceeded; platform will mark affected projections stale while keeping last-known-good records.
Login/logout evidence comes from plugin-declared log sources. A login line can create/update a local player/session projection; `last_save_time` is only freshness evidence and must not be treated as online-state proof by itself.
## Controlled Write Jobs
Run must execute only typed operations declared by the SCUM plugin manifest.
| Operation key | Transport | Required behavior |
| --- | --- | --- |
| `player.fame.set` | RCON | Use the declared command template for fame and confirm through follow-up readback. |
| `player.currency.normal.set` | RCON | Use the declared command template for normal currency and confirm through follow-up readback. |
| `player.currency.gold.set` | RCON | Use the declared command template for gold and confirm through follow-up readback. |
| `player.notify` | RCON/declared notification command | Deliver bounded player notification text and report unknown if delivery cannot be proven. |
| `reward.deliver` | Declared reward transport | Deliver catalogued reward/notification only once per idempotency key and confirmation state. |
| `player.attribute.855.set` | SQLite mutation | Execute the declared DB-only mutation with before-value guard, max affected rows = 1, maintenance/offline evidence, backup/snapshot reference, and confirmation query. |
RCON-supported fame/currency writes must not be converted to DB mutations. DB-only mutations must fail safely when the current value differs from the approved `before` value, the affected row bound is exceeded, backup evidence is missing, or the player safety state is online/unknown.
## Result And Confirmation Contract
Run job results for SCUM reads, RCON writes, and SQLite mutations must return:
- `kind` identifying the declared result type.
- `checksum` as `sha256:<64 hex chars>`.
- Bounded JSON content matching the plugin result/confirmation schema.
- `affectedRows` for mutations and zero/one row confirmation details where applicable.
- A safe audit summary that excludes raw SQL, raw RCON text, SCUM.db paths, host paths, tokens, sockets, and credentials.
If execution may have happened but confirmation is missing, run should report an unknown/pending-confirmation state rather than success. Platform will read back before retrying so gifts, currency, fame, and DB fields are not duplicated or overwritten.
## External Run Tasks
The independent run repository needs implementation work for:
1. Resolve package-scoped logical SCUM.db and log targets from the generated run plan without exposing resolved host paths to Platform Web.
2. Execute the six declared SQLite read templates with row/time bounds and schema-compatible JSON rows.
3. Execute typed RCON operation templates for fame, currency, notification, and reward delivery without accepting arbitrary browser command text.
4. Execute `player.attribute.855.set` through a guarded SQLite mutation with backup, maintenance/offline checks, before-value match, affected-row bound, and confirmation read.
5. Report observation failures and write unknown states with safe codes and checksums so platform projections and workflows can reconcile deterministically.