first commit
This commit is contained in:
npc0-hue
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-07-02
|
||||
@@ -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`?
|
||||
@@ -0,0 +1,28 @@
|
||||
## Why
|
||||
|
||||
The platform backend currently has architecture contracts and a health endpoint, but the core platform resources are only described in markdown. This change turns those contracts into typed, validated Go domain foundations so later API, run, frontend, and plugin work can depend on stable platform behavior.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Add typed platform domain resources for users, game management plugins, server instances, AI providers, run endpoints, jobs, artifacts, log streams, and audit events.
|
||||
- Add DTO and model contracts for those resources in their required directories.
|
||||
- Add repository interfaces plus an in-memory repository implementation suitable for unit tests and early service wiring.
|
||||
- Add service interfaces and implementations for core create/list/get workflows and lifecycle-safe state changes.
|
||||
- Add validators for identity, enum values, plugin-to-server relationships, run capability compatibility, AI provider redaction constraints, job idempotency, artifact metadata, log stream cursors, and audit summaries.
|
||||
- Extend route catalog documentation with the core resource contract surface, without implementing full HTTP handlers in this change.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
- `platform-core-domain`: Typed backend domain, DTO, model, repository, service, validation, and route-contract foundations for core platform resources.
|
||||
|
||||
### Modified Capabilities
|
||||
- None.
|
||||
|
||||
## Impact
|
||||
|
||||
- Affects `platform/` only.
|
||||
- Adds Go packages under `platform/domain`, `platform/dto`, `platform/model`, `platform/repo`, `platform/service`, and `platform/validator`.
|
||||
- Updates `platform/api/routes.md` and platform markdown contracts where needed to reflect the implemented route contract surface.
|
||||
- Adds focused platform unit tests for validators, repository behavior, service behavior, and model mappings.
|
||||
- Does not add billing, cloud host sales, plugin-to-run direct access, raw AI key exposure, or full API handler behavior.
|
||||
@@ -0,0 +1,85 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Core platform resources are typed
|
||||
The platform SHALL define typed domain resources for users, AI providers, game management plugins, server instances, run endpoints, jobs, artifacts, log streams, and audit events in the platform domain package.
|
||||
|
||||
#### Scenario: Domain resource definitions are available
|
||||
- **WHEN** platform services, repositories, DTOs, or models need a core platform resource
|
||||
- **THEN** they MUST reference named domain resource types instead of defining business structs inside handlers or functions
|
||||
|
||||
#### Scenario: Lifecycle values are centralized
|
||||
- **WHEN** code validates resource status, state, result, or provider kind values
|
||||
- **THEN** it MUST use centralized domain constants for the allowed values
|
||||
|
||||
### Requirement: API and database contracts are separated from business logic
|
||||
The platform SHALL provide named DTO and model structs for core resources in dedicated packages, and model structs SHALL expose explicit table names and database tags.
|
||||
|
||||
#### Scenario: API response contract is needed
|
||||
- **WHEN** a later API handler returns a core resource
|
||||
- **THEN** the response shape MUST be available as a named DTO and MUST NOT be declared inside the handler
|
||||
|
||||
#### Scenario: Database model contract is needed
|
||||
- **WHEN** a future migration or repository references a core resource table
|
||||
- **THEN** the table mapping MUST be available as a named model with tags and an explicit table name function
|
||||
|
||||
### Requirement: AI provider contracts redact secrets
|
||||
The platform SHALL store AI provider secret references but MUST NOT expose raw provider API keys through domain responses, DTO responses, services, or plugin-facing contracts.
|
||||
|
||||
#### Scenario: AI provider is returned by service
|
||||
- **WHEN** an AI provider is created or fetched through the core service layer
|
||||
- **THEN** the returned provider MUST include an API key reference only and MUST NOT include raw key material
|
||||
|
||||
#### Scenario: AI provider validation runs
|
||||
- **WHEN** an AI provider uses a direct or relay endpoint
|
||||
- **THEN** validation MUST require a key reference and redaction policy while rejecting raw secret values in API contract fields
|
||||
|
||||
### Requirement: Core validators enforce resource invariants
|
||||
The platform SHALL validate required IDs, display names, enum values, bounded lists, server/plugin/run relationships, job idempotency keys, artifact checksums, log cursors, and audit summaries before services persist resources.
|
||||
|
||||
#### Scenario: Invalid core resource is submitted
|
||||
- **WHEN** a resource has a missing ID, invalid enum value, missing required relationship, unsupported capability, or unbounded summary
|
||||
- **THEN** validation MUST return a clear error and the service MUST NOT persist the resource
|
||||
|
||||
#### Scenario: Server creation is requested
|
||||
- **WHEN** a server instance is created from a game management plugin
|
||||
- **THEN** validation MUST require an installed plugin, a non-deleted server state, a run endpoint, and capability compatibility
|
||||
|
||||
### Requirement: Repository contracts support deterministic core storage
|
||||
The platform SHALL expose repository interfaces for core resources and an in-memory implementation that supports create, get, list, update, and idempotent job lookup behavior.
|
||||
|
||||
#### Scenario: Duplicate resource is created
|
||||
- **WHEN** a repository create operation receives an ID that already exists
|
||||
- **THEN** it MUST return a duplicate error and MUST NOT replace the existing resource
|
||||
|
||||
#### Scenario: Stored resource is read and mutated by caller
|
||||
- **WHEN** a caller mutates a value returned by the in-memory repository
|
||||
- **THEN** the stored resource MUST remain unchanged unless an explicit update operation succeeds
|
||||
|
||||
### Requirement: Core services enforce cross-resource workflows
|
||||
The platform SHALL provide services that compose repositories and validators for core user, plugin, server instance, AI provider, run endpoint, job, artifact, log stream, and audit workflows.
|
||||
|
||||
#### Scenario: Server instance is created from an installed plugin
|
||||
- **WHEN** a service request names an installed game management plugin and an online or degraded run endpoint with all required capabilities
|
||||
- **THEN** the service MUST persist a server instance linked to that plugin and run endpoint
|
||||
|
||||
#### Scenario: Server instance creation uses invalid dependencies
|
||||
- **WHEN** a service request names a disabled or invalid plugin, missing plugin, missing run endpoint, disabled run endpoint, or run endpoint without required capabilities
|
||||
- **THEN** the service MUST reject the request and MUST NOT persist the server instance
|
||||
|
||||
#### Scenario: Duplicate job request is submitted
|
||||
- **WHEN** a job create request repeats an existing run endpoint and idempotency key pair
|
||||
- **THEN** the service MUST return the existing job instead of creating a second job
|
||||
|
||||
### Requirement: Route catalog exposes core resource contract groups
|
||||
The platform SHALL document route groups for core resources before full API handlers are implemented.
|
||||
|
||||
#### Scenario: Contributor inspects platform API contracts
|
||||
- **WHEN** a contributor opens the platform route catalog
|
||||
- **THEN** it MUST list core resource route groups and the DTO contracts those future handlers will use
|
||||
|
||||
### Requirement: Platform core unit tests verify the domain foundation
|
||||
The platform SHALL include unit tests covering validation, in-memory repository behavior, service invariants, DTO redaction, and model table mappings.
|
||||
|
||||
#### Scenario: Platform tests run
|
||||
- **WHEN** `go test ./...` is executed inside `platform/`
|
||||
- **THEN** the tests MUST verify core domain behavior without external services or a database
|
||||
@@ -0,0 +1,34 @@
|
||||
## 1. Domain Contracts
|
||||
|
||||
- [x] 1.1 Implement typed domain resources, enum constants, filters, and copy helpers for users, AI providers, game plugins, server instances, run endpoints, jobs, artifacts, log streams, and audit events.
|
||||
- [x] 1.2 Implement named DTO request/response contracts with AI provider redaction helpers for core resources.
|
||||
- [x] 1.3 Implement database model contracts with JSON/database tags, table-name mappings, and domain conversion helpers for core resources.
|
||||
|
||||
## 2. Validation And Storage
|
||||
|
||||
- [x] 2.1 Implement validator rules and tests for IDs, enum values, AI redaction constraints, plugin/server/run compatibility, job idempotency, artifacts, logs, and audit summaries.
|
||||
- [x] 2.2 Implement repository interfaces and an in-memory repository with duplicate detection, copy-on-read/write behavior, list/get/update methods, and idempotent job lookup.
|
||||
|
||||
## 3. Services And Contracts
|
||||
|
||||
- [x] 3.1 Implement service interfaces and core service methods for create/list/get workflows across users, AI providers, game plugins, run endpoints, server instances, jobs, artifacts, log streams, and audit events.
|
||||
- [x] 3.2 Enforce service-level cross-resource invariants for server creation, AI provider redaction, disabled resources, run capability compatibility, and duplicate job idempotency.
|
||||
- [x] 3.3 Update platform route/resource contract documentation to reference the implemented DTO/domain contracts without adding full HTTP handlers.
|
||||
|
||||
## 4. Verification
|
||||
|
||||
- [x] 4.1 Run platform unit tests with `go test ./...` from `platform/` and record evidence.
|
||||
- [x] 4.2 Run `scripts/check-structure.sh` and record evidence.
|
||||
- [x] 4.3 Run `openspec validate implement-platform-core-domain --strict` and record evidence.
|
||||
|
||||
## Evidence
|
||||
|
||||
- `go test ./domain`: passed.
|
||||
- `go test ./dto`: passed.
|
||||
- `go test ./model`: passed.
|
||||
- `go test ./validator`: passed.
|
||||
- `go test ./repo`: passed.
|
||||
- `go test ./service`: passed.
|
||||
- `go test ./...` from `platform/`: passed.
|
||||
- `scripts/check-structure.sh`: passed.
|
||||
- `openspec validate implement-platform-core-domain --strict`: passed.
|
||||
Reference in New Issue
Block a user