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

SCUM Run Integration Contract

This repository owns the Platform/plugin side of SCUM real-data operations. The machine-side executor remains the independent git@git.npc0.com:admin343/run.git repository, and no run/ source tree or SCUM-specific executor branch belongs in this repository.

Ownership Boundary

• Platform owns server instances, target-server authorization, durable jobs, local SCUM records, capability evidence, generated Run package inputs, safe browser APIs, idempotency, and internal write confirmation evidence.
• The SCUM plugin owns versioned parser declarations, SQLite template assets, result schemas, schema-adapter compatibility, map metadata, typed command templates, gift catalogs, and guarded mutation declarations.
• Run owns generic machine-side execution beside the current bound service: resolving package-scoped logical targets, enforcing declared capabilities, executing bounded jobs, supervising declared log sources, and returning terminal envelopes through the existing signed channels.

Run and Platform Web must never receive or expose raw SQL, raw RCON text, raw XML, host/database paths, DSNs, sockets, credentials, raw row content, IP/network material, or arbitrary browser-supplied execution payloads.

Capability Gate

Every database-backed SCUM read or write capability stays disabled until the active Run binding reports compatible current-service evidence for that exact server, endpoint, binding, plugin version, adapter version, game version, database identity, schema fingerprint, and asset digest set.

Disabled capability results are ordinary safe availability states such as probe_executor_absent, probe_missing, schema_incompatible, binding_mismatch, fingerprint_mismatch, digest_mismatch, or evidence_expired. They are not Workflow, observation, projection, audit-initiation, or manual-refresh states.

Schema Probe Jobs

Platform may dispatch a schema probe only as a durable job through the active authenticated Run binding. The probe payload contains a logical target key, binding identity, timeout/row/result bounds, and no SCUM table names, database path, SQL text, row values, XML, credentials, or host identifiers.

Run executes the generic remote.run.db.sqlite.probe capability against the package-resolved current database or a short-lived read-only snapshot fenced to the same binding/database identity. The terminal result returns only redacted object, column, index, foreign-key, approximate cardinality, and sample fingerprints with the applied limits and a safe status.

Read-Only SQLite Template Jobs

After probe evidence matches a plugin adapter, Platform can schedule plugin-owned read-only SQLite template jobs by template key, adapter/schema version, immutable asset digest, and bounded parameters. Platform does not build SQL strings, and the browser never submits query text or undeclared parameters.

The leased Run assignment carries a typed sqliteTemplate request only. Required fields are requestId, server/plugin binding, read capability, logical targetKey, templateKey, adapterVersion, requiredSchemaFingerprint, immutable assetDigest, canonical parameterDigest, bounded scalar parameters, and limits containing maxParameters, maxRows, timeoutMs, busyTimeoutMs, and maxResultBytes. The payload carries no SQL text, table names from the browser, database path, DSN, socket, credential, raw XML, RCON text, or host identifier.

Run verifies the packaged asset digest, adapter/schema fingerprint, canonical parameter digest, and active binding before opening a query-only SQLite connection or fenced short-lived read-only snapshot. It enforces one approved read-only statement or introspection boundary, bound parameters, short busy/operation timeouts, cancellation, row/result-byte limits, and rejects DDL, mutation, ATTACH, extension loading, write PRAGMAs, multi-statement input, and string-concatenated parameters.

The terminal sqlite.template-query envelope contains requestId, jobId, binding, status (succeeded, failed, or cancelled), capability, target/template key, adapter version, schema fingerprint, asset digest, parameter digest, source fingerprint, observed time, result digest, row count, bounded rows, truncation flag, safe error, and applied limits. Platform validates the envelope against the original durable job, lease attempt, binding, template key, schema fingerprint, asset digest, and parameter digest before any local SCUM generation can consume the rows.

Parsed Log Event Jobs

Login/logout ingestion starts from plugin-declared log sources and versioned parser assets. Each parsed event carries server/plugin/parser identity, transport cursor (source identity, stream generation, sequence), a separate privacy-safe logical event identity, and occurrence time.

Run and Platform discard raw IP addresses and other network identifiers before durable storage or logical fingerprinting. Malformed, failed-login, obsolete-binding, duplicate, or out-of-order events must not fabricate players or sessions.

Typed RCON Template Jobs

SCUM command writes use only plugin-owned typed command templates. Platform dispatches a template key, adapter version, digest, target identity, idempotency key, validated parameters, and review reason through the durable job channel.

The leased Run assignment carries a typed rconTemplate request only. Required fields are requestId, server/plugin binding, write capability, logical transportKey, logical targetKey, templateKey, adapterVersion, optional requiredSchemaFingerprint, immutable assetDigest, canonical payloadDigest, confirmationDigest, targetIdentityDigest, idempotency key, bounded scalar payload, review reason, and limits containing maxPayloadBytes, timeoutMs, maxResponseBytes, and maxConfirmRecords. The payload carries no browser command text, raw RCON, SQL, XML, host path, socket, credential, or undeclared command key.

Run resolves the packaged command template and protected RCON transport from the generated Run package, verifies the asset/payload/confirmation digests and active binding, renders only the packaged template with bound scalar payload values, executes through generic protected RCON, and performs only the declared confirmation path. Run never accepts browser command text, exposes the rendered command in result envelopes, or branches on SCUM command names, SCUM keys, SCUM commands, SCUM tables, or gift/economy semantics.

The terminal rcon.template-command envelope contains requestId, jobId, binding, status (succeeded, failed, or cancelled), capability, transport/target/template key, adapter version, schema fingerprint when required, asset digest, payload digest, confirmation digest, target identity digest, observed time, result digest, response digest, confirmation status, confirmation digest id, safe summary, safe error, and applied limits. A write is successful only after the declared confirmation path returns schema-valid conclusive evidence; missing, partial, mismatched, cancelled, or timed-out confirmation is reported as failed, partial, or unknown rather than success.

Guarded SQLite/XML Mutation Jobs

Database/XML writes are disabled until current-service evidence proves the source row, XML field, named attribute mapping, backup/offline safety requirements, and preserving patch contract. 855 is never an executable field key; it may only be a reviewed preset label that expands to explicit named attributes after the mapping is confirmed.

Platform dispatches guarded mutations only with effective server.game-client.maintenance, explicit danger confirmation, target identity, expected before values/checksum, same-instance backup evidence, idempotency key, reason, adapter/digest, and declared safety requirements. Run performs one bounded transaction, updates exactly one guarded row, preserves untargeted XML content, rolls back on zero/multiple affected rows or conflicts, and performs read-after-write confirmation before any success result.

The leased Run assignment carries a typed guardedMutation request only. Required fields are requestId, server/plugin binding, profile-xml.write capability, logical targetKey, templateKey, adapterVersion, requiredSchemaFingerprint, immutable assetDigest, targetIdentityDigest, expectedRowDigest, expectedValueDigest, expectedXmlDigest, patchDigest, backupEvidenceDigest, offlineEvidenceDigest, dangerConfirmationDigest, readbackExpectationDigest, idempotency key, bounded scalar payload, review reason, and limits containing maxPayloadBytes, timeoutMs, busyTimeoutMs, maxReadbackBytes, and maxAffectedRows=1. The payload carries no raw SQL, raw XML, database path, table/column override, 855 field key, browser mutation text, host path, socket, credential, or undeclared patch field.

The terminal sqlite.guarded-mutation envelope contains requestId, jobId, binding, status (succeeded, failed, or cancelled), capability, target/template key, adapter/schema fingerprint, asset digest, source fingerprint, target identity digest, expected row/value/XML digests, patch digest, backup/offline/danger-confirmation digests, readback expectation digest, observed time, result digest, before/after/readback digests, affected-row count, readback status, safe summary, safe error, and applied limits. Platform accepts success only when the envelope matches the leased job and binding, affectedRows is exactly 1, and readbackStatus is confirmed; zero/multiple rows, guard mismatches, malformed XML, missing backup/offline/danger confirmation, missing readback, or stale schema remain safe failed/conflict/unknown results.

Saving attributes must never implicitly kill, respawn, kick, or otherwise activate destructive game behavior. Any verified required activation is a separate permission-checked and explicitly confirmed typed command.

Terminal Result Envelope

Every probe, read template, typed command, parsed-log batch, or guarded mutation result returns a typed terminal envelope containing server/plugin binding, adapter/schema version, template/action/parser key, asset digest, job identity, observed time, checksum/result digest, row or affected-row count where applicable, and a stable safe result/error code.

Platform validates the envelope against the original durable job before updating local SCUM records or write-confirmation state. Late, duplicate, foreign, stale, incompatible, or unsafe results are rejected idempotently while preserving the last completed local generation.

External Run Evidence Required

The independent Run repository still needs separately authorized implementation and verification evidence for generic schema probing, packaged SQLite-template execution, typed RCON execution, guarded SQLite/XML mutation execution, plugin-declared log-source tailing, and terminal-envelope fencing. This browser repository must record that tested Run commit/deployment evidence before enabling database-backed adapters, adding production query/mutation assets, or marking the real-service verification tasks complete.