first commit

openspec/changes/implement-platform-core-domain/design.md

@@ -0,0 +1,79 @@
+## Context
+
+`platform/` currently contains the development baseline: a Go module, config loader, health route, route catalog, and markdown contracts for platform resources. The bootstrap architecture requires fixed backend directories for domain types, DTOs, database models, repositories, services, validators, protocol contracts, routes, and shared helpers. Later changes will implement HTTP handlers, run registration, job channels, logs, artifacts, plugin registry, and frontend workflows; those changes need stable core platform types first.
+
+This change stays inside `platform/` and converts the markdown resource contracts into Go packages with unit-tested in-memory behavior. It does not introduce a database driver or full API handler surface.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Define typed Go domain resources for users, game management plugins, server instances, AI providers, run endpoints, jobs, artifacts, log streams, and audit events.
+- Define DTO and database-model contracts in dedicated packages so future handlers and persistence work do not invent structs locally.
+- Add repository interfaces and an in-memory implementation for deterministic unit tests and early service composition.
+- Add services that enforce core invariants for plugin installation metadata, server creation, AI provider redaction, job idempotency, artifacts, logs, and audit.
+- Add validation helpers with precise errors for required IDs, enum values, relationships, capability compatibility, redaction, sequence cursors, and bounded summaries.
+- Update route catalog documentation with resource contract routes, while leaving handler implementation for a later API-surface change.
+
+**Non-Goals:**
+
+- No authentication, sessions, role authorization engine, or password storage.
+- No SQL database, migrations, ORM, or external persistence dependency.
+- No full HTTP CRUD handlers beyond existing health behavior.
+- No run control/job/log/artifact transport implementation.
+- No plugin manifest registry implementation or plugin page bridge implementation.
+- No raw AI key exposure, direct plugin-to-run access, billing, cloud host sales, or unrelated marketplace behavior.
+
+## Decisions
+
+### Decision 1: Domain package owns business vocabulary
+
+`platform/domain` will define resource structs, enum-like string types, lifecycle constants, filter structs, and copy helpers. Services, repositories, DTOs, and models will reference this vocabulary instead of redefining resource shapes.
+
+Alternative considered: defining separate shapes independently in every package. Rejected because this would recreate the drift the architecture bootstrap is trying to avoid.
+
+### Decision 2: DTO and model packages are explicit projections
+
+DTO structs will represent API request/response boundaries and must not include raw AI provider secrets. Model structs will represent future database tables with JSON/database tags plus `TableName()` methods. Conversion functions will make differences explicit.
+
+Alternative considered: reusing domain structs directly as API and database structs. Rejected because API redaction and database mapping concerns need independent contracts.
+
+### Decision 3: Repository interfaces live with the in-memory implementation
+
+`platform/repo` will define `Store` and typed repository interfaces, plus an in-memory `MemoryStore`. The store will deep-copy resources on read/write and enforce duplicate IDs. This gives services a realistic boundary without committing to SQL in this change.
+
+Alternative considered: package-level maps in services. Rejected because it hides persistence contracts inside orchestration logic and makes future database replacement harder.
+
+### Decision 4: Services own cross-resource invariants
+
+Validators will check local resource validity. Services will enforce cross-resource rules such as “server instances require an installed plugin” and “run endpoint capabilities must satisfy plugin requirements.” Job creation will use an idempotency key to return an existing job for duplicate requests.
+
+Alternative considered: repositories enforcing all invariants. Rejected because repositories should guard storage integrity while service use cases should own platform behavior.
+
+### Decision 5: No database or HTTP framework dependency yet
+
+This change uses only the Go standard library. SQL, migrations, and API handler frameworks are deferred until changes that explicitly implement persistence and API surface behavior.
+
+Alternative considered: adding SQLite or an HTTP framework now. Rejected because it would widen scope beyond the core domain foundation and complicate verification before handlers exist.
+
+## Risks / Trade-offs
+
+- [Risk] In-memory repositories can drift from future SQL behavior. Mitigation: keep interfaces small, copy-on-read/write, and test behavior that future implementations must preserve.
+- [Risk] Domain structs may need fields added by later run/log/plugin changes. Mitigation: include the bootstrap resource fields now and allow additive changes through future OpenSpec deltas.
+- [Risk] DTO/model projections add boilerplate. Mitigation: keep conversion helpers straightforward and limited to core resources.
+- [Risk] Services may look broad before API handlers exist. Mitigation: expose focused methods only for current core workflows and leave transport-specific behavior to later changes.
+
+## Migration Plan
+
+1. Add platform domain, DTO, model, validator, repository, and service code behind new unit tests.
+2. Keep existing health route behavior unchanged.
+3. Update route and resource contract documentation to reference the implemented core resources.
+4. Verify with platform unit tests, `scripts/check-structure.sh`, and strict OpenSpec validation.
+
+Rollback before dependent changes is file removal for the new platform packages and this OpenSpec change. After later API or persistence changes depend on these packages, rollback must follow a new OpenSpec change.
+
+## Open Questions
+
+- Which persistent database implementation should replace `MemoryStore` first?
+- Which authentication and authorization model should own user/session behavior?
+- Which route handlers from the core route catalog should be implemented first in `implement-platform-api-surface`?