60 lines
6.6 KiB
Markdown
60 lines
6.6 KiB
Markdown
# 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.
|
|
|
|
Run verifies the packaged asset digest, enforces one approved read-only statement or introspection boundary, binds parameters, applies short busy/operation timeouts, row/result-byte limits, and returns a terminal envelope with safe rows matching the declared result schema. DDL, mutation, `ATTACH`, extension loading, write PRAGMAs, multi-statement input, and string-concatenated parameters are rejected.
|
|
|
|
## 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.
|
|
|
|
Run never accepts browser command text or branches on SCUM command names. 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.
|
|
|
|
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.
|