browser/openspec/changes/rebuild-scum-plugin-owned-data/design.md

Design

Ownership

Platform owns authentication, server-instance authorization, durable storage mechanics, collection scoping, and transaction boundaries. It does not interpret collection payloads.

The SCUM plugin owns collection names such as scum_users, schemas, upsert keys, data transformations, gifts, map geometry, and UI behavior. It declares database/file/log work in the manifest; Platform dispatches those declarations to Run, and Run executes on the machine.

Generic Platform Data Contract

The generic record is scoped by pluginId, serverInstanceId, collection, and key, with an opaque JSON value and timestamps. The platform validates scope and authorization only. A page bridge exposes list/put/delete and atomic put/delete transaction methods to plugin bundles.

SCUM uses stable scum_* collection names in the Platform database. Game database versions do not become Platform branches: a new SCUM schema updates the plugin SQL, result schema, mappings, and parser declarations while preserving the normalized collection contract.

SCUM Data Flow

1. The plugin declares SQLite sqlRef assets, automatic cadence, collection row targets, config maps, and log projections in its own data pack and manifest. PRAGMA user_version is diagnostic evidence, not a Platform version switch.
2. When Run polls for work, Platform creates every due declared query before selecting the next job. This naturally follows the existing two-second polling channel and works without a UI or a new background daemon.
3. Run executes the declared SQL asset and returns structured rows. Platform applies only the declared collection, key, mapping, merge/replace mode, and fixed values.
4. Full snapshot targets delete records absent from a successful complete result. Merge targets preserve stdout presence fields while SQLite later adds profile, economy, squad, and coordinate facts.
5. Durable stdout batches are evaluated against plugin-declared ordered regex steps. Named captures with the same name must agree across the sequence; the complete sequence emits one stable event value and resets its bounded per-stream state.
6. The SCUM BattlEye declaration correlates reported as player N with Player N SteamID (assumed) by slot. Steam ID is the scum_users key; names are mutable display fields and are never identity keys.
7. The presence policy reads the existing user before mutation. A missing record receives the new-player announcement. A record whose last login is inside ten minutes is updated at most once and receives no duplicate announcement. An older record receives the returning-player announcement.
8. Announcement text and #announce command syntax belong to the SCUM plugin declaration. Platform only renders captured placeholders and queues the already-declared command through the existing Run channel.
9. The SCUM page polls Platform collections for display freshness. It never dispatches SQLite queries and exposes no manual synchronization button.
10. Gift delivery and activity commands use the existing generic Game Client Bridge queue exposed by the plugin-page host.

Declared Cadences

• scum.player.profile, scum.vehicles, and scum.positions: 3 seconds.
• scum.squads and scum.squad-members: 1800 seconds.
• Flags, native event/task observations, and native timed-gift observations use plugin-owned slower cadences appropriate to those datasets.

Cadence is measured from the latest matching job attempt. A still-active matching query suppresses another job, and idempotency keys include the server, template, and cadence bucket.

Real Data Evidence

The provided complete database is /Users/tasia/Downloads/SCUM/SCUM.db; the similarly named file under Logs/ is empty. The complete database reports SQLite user_version=57, contains 162 tables, and passes quick_check. All nine packaged SQL files execute against it. The existing users query starts at user_profile and therefore misses one real account; it must start at user and left join optional profile/prisoner data so stdout-created Steam identities merge correctly.

Compatibility

Recent SCUM-specific Platform routes, types, repository tables, and game-gift APIs are removed. The retained generic bridge remains usable by other game plugins without SCUM imports or switches.