64 lines
7.8 KiB
Markdown
64 lines
7.8 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.
|
|
|
|
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.
|
|
|
|
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.
|