# 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.