browser/platform/protocol/scum-run-integration.md

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.