browser/platform/domain/resources.md

Platform Domain Resources

This file defines the first platform resource contracts. Concrete Go domain structs are implemented in platform/domain/resources.go; API DTO projections live in platform/dto/resources.go; database model projections live in platform/model/resources.go. Do not define these resource shapes inside handlers or service functions.

Implemented Boundaries

• Domain constants centralize allowed status, state, provider kind, relay mode, artifact owner, storage backend, and audit result values.
• DTO responses expose apiKeyRef for AI providers but never raw key material.
• Model structs include JSON/database tags and explicit TableName() mappings for future persistence work.
• platform/repo.NewFileStore provides durable local metadata snapshots for platform startup, while platform/repo.NewMemoryStore provides deterministic in-memory repository behavior for unit tests and disposable local runs.
• Log stream metadata records the selected body backend. The current durable local body backend uses local-segments; future production adapters should target log-optimized stores such as clickhouse, loki, opensearch, or elasticsearch rather than row-per-line relational tables.
• platform/service.Core enforces create/list/get workflows and cross-resource invariants before resources are persisted.

User

• id: stable user ID.
• displayName: visible user name.
• email: optional login email.
• status: active, disabled, or pending.
• roles: role keys assigned to the user.
• createdAt: creation time.
• updatedAt: last update time.

AIProvider

• id: stable provider ID.
• name: display name.
• kind: openai-compatible, openai, claude, gemini, ollama, or custom.
• baseUrl: provider or relay base URL.
• apiKeyRef: secret reference, never the raw key.
• models: allowed model IDs.
• defaultModel: optional default model.
• relayMode: direct, relay, or local.
• timeoutMs: request timeout.
• status: active, disabled, or error.
• redactionPolicy: policy key for prompt/input/output redaction.

GamePlugin

• id: plugin ID such as game.example.
• name: display name.
• description: bounded marketplace/registry summary.
• version: installed version.
• serverType: game/server type key.
• serverDisplayName: visible server type name.
• supportedOs: operating systems declared by the plugin manifest.
• manifestRef: immutable manifest artifact reference.
• createFormSchemaRef: create form schema reference.
• requiredRunCapabilities: run capabilities required by this plugin.
• declaredPermissions: scoped manifest permission keys used by plugin bridge and marketplace views.
• permissions: aggregate platform ability declarations for AI, logs, files, jobs, and artifacts.
• lifecycleActions: manifest action contract references for install/start/stop and optional restart/status.
• pages: plugin-local page metadata with scoped permission requirements.
• tags: bounded catalog tags.
• aiPurposes: platform-mediated AI purposes such as config suggestions or log diagnosis.
• validationViolations: safe validation findings for invalid plugin records.
• status: installed, disabled, invalid, or updating.

Manifest registration uses GamePluginManifestRegistrationRequest at POST /api/v1/game-plugins/register-manifest. Platform validation repeats plugin workspace safety checks and rejects raw host paths, direct run sockets, raw credentials, and raw AI/provider keys before metadata reaches the registry.

ServerInstance

• id: server instance ID.
• pluginId: installed game management plugin ID.
• pluginVersion: plugin version used to create or last reconcile the instance.
• runEndpointId: selected run endpoint.
• name: server display name.
• state: draft, installing, ready, running, stopped, failed, or deleted.
• configVersion: optimistic concurrency version for platform-managed config.
• createdAt: creation time.
• updatedAt: last update time.

RunEndpoint

• id: run endpoint ID.
• displayName: visible executor name.
• version: run binary version.
• status: online, offline, degraded, or disabled.
• capabilities: current capability keys.
• capacity: current queue and resource summary.
• lastHeartbeatAt: last control heartbeat time.

Job

• id: job ID.
• serverInstanceId: optional target server.
• runEndpointId: target run endpoint.
• capability: requested capability key.
• idempotencyKey: duplicate detection key.
• state: queued, accepted, running, succeeded, failed, or cancelled.
• progress: bounded progress summary.
• resultRef: optional terminal result reference.

Lifecycle workflow jobs use fixed capabilities:

• process.install: dispatched by server create workflow and projects successful terminal results to ready.
• process.start: dispatched by server start workflow and projects successful terminal results to running.
• process.stop: dispatched by server stop workflow and projects successful terminal results to stopped.

Failed or cancelled lifecycle jobs project the server instance to failed. Active start/stop jobs are visible through job metadata; this change does not add separate starting or stopping server states.

Artifact

• id: artifact ID.
• ownerKind: platform, plugin, server-instance, or job.
• ownerId: owning resource ID.
• sizeBytes: expected or final size.
• checksum: final checksum.
• state: uploading, available, expired, or failed.

LogStream

• id: log stream ID.
• serverInstanceId: target server.
• source: process, file, plugin, or custom source.
• streamKey: stable stream key.
• latestSeq: latest accepted sequence.
• storageBackend: local-segments, loki, clickhouse, opensearch, or elasticsearch.
• retentionPolicy: retention key.

AuditEvent

• id: audit event ID.
• actorId: user or system actor.
• action: stable action key.
• resourceKind: resource kind.
• resourceId: resource ID.
• result: success, denied, failed, or queued.
• summary: bounded redacted summary.
• createdAt: event time.