first commit

openspec/changes/implement-platform-api-surface/specs/platform-api-surface/spec.md

@@ -0,0 +1,82 @@
+## ADDED Requirements
+
+### Requirement: Core resource HTTP routes are implemented
+The platform SHALL expose HTTP JSON routes for create, list, and detail workflows for users, AI providers, game management plugins, server instances, run endpoints, jobs, artifacts, log streams, and audit events.
+
+#### Scenario: Resource is created through API
+- **WHEN** a valid create request is posted to a core resource collection route
+- **THEN** the platform MUST persist the resource through `service.Core` and return `201` with the corresponding named response DTO
+
+#### Scenario: Resource list is requested
+- **WHEN** a client sends `GET` to a core resource collection route
+- **THEN** the platform MUST return `200` with a named list response DTO containing resources from `service.Core`
+
+#### Scenario: Resource detail is requested
+- **WHEN** a client sends `GET` to a core resource detail route with an existing resource ID
+- **THEN** the platform MUST return `200` with the corresponding named response DTO
+
+### Requirement: API handlers use centralized DTO and service contracts
+The platform SHALL keep API request, response, list, and error contracts in `platform/dto` and SHALL call `service.Core` for resource workflows.
+
+#### Scenario: Handler decodes request body
+- **WHEN** an API handler accepts a request body
+- **THEN** it MUST decode into a named DTO type from `platform/dto` and convert that DTO to a named domain type before calling `service.Core`
+
+#### Scenario: Handler returns response body
+- **WHEN** an API handler returns a success or error response
+- **THEN** it MUST encode a named DTO response type and MUST NOT define response structs inside handler functions
+
+### Requirement: API errors are stable JSON responses
+The platform SHALL return named JSON error DTOs for malformed requests, validation failures, duplicate resources, missing resources, unsupported methods, and unexpected failures.
+
+#### Scenario: Invalid JSON is submitted
+- **WHEN** a client posts malformed JSON to a core resource route
+- **THEN** the platform MUST return `400` with a JSON error response
+
+#### Scenario: Validation fails
+- **WHEN** a create request violates validator or service invariants
+- **THEN** the platform MUST return `400` with a JSON error response and MUST NOT persist the resource
+
+#### Scenario: Duplicate resource is submitted
+- **WHEN** a create request uses an ID that already exists
+- **THEN** the platform MUST return `409` with a JSON error response
+
+#### Scenario: Missing resource is requested
+- **WHEN** a client requests a resource ID that does not exist
+- **THEN** the platform MUST return `404` with a JSON error response
+
+### Requirement: AI provider API preserves credential redaction
+The AI provider API SHALL return redacted provider response DTOs that include secret references only and never raw API keys.
+
+#### Scenario: AI provider is created through API
+- **WHEN** a valid AI provider create request is posted
+- **THEN** the platform MUST return an `AIProviderResponse` containing `apiKeyRef` and MUST NOT include raw API key fields
+
+#### Scenario: Raw AI key is submitted as key reference
+- **WHEN** an AI provider create request includes raw key material in `apiKeyRef`
+- **THEN** the platform MUST reject the request with `400` and MUST NOT persist the provider
+
+### Requirement: Router is injectable and local-development ready
+The platform SHALL provide router construction that accepts a core service for tests and future persistence, and a default router that uses the in-memory core service for local development.
+
+#### Scenario: Local platform process starts
+- **WHEN** `cmd/platform` creates the default router
+- **THEN** the router MUST expose `/healthz` and all implemented core API routes backed by an in-memory `service.Core`
+
+#### Scenario: Tests provide a service
+- **WHEN** tests call router construction with an explicit `service.Core`
+- **THEN** handlers MUST use that service instance for all route operations
+
+### Requirement: Route catalog matches implemented API surface
+The platform route catalog SHALL identify implemented core API routes and clearly distinguish deferred run transport, log ingest, artifact chunk, plugin bridge, and AI invocation behavior.
+
+#### Scenario: Contributor inspects API catalog
+- **WHEN** a contributor opens `platform/api/routes.md`
+- **THEN** the file MUST list the implemented create, list, and detail routes and MUST identify deferred behavior as not implemented by this change
+
+### Requirement: API handler tests verify surface behavior
+The platform SHALL include API tests covering successful create/list/detail workflows, JSON error mapping, dependency validation, duplicate handling, missing resources, and AI provider redaction.
+
+#### Scenario: Platform API tests run
+- **WHEN** `go test ./...` is executed inside `platform/`
+- **THEN** tests MUST verify the implemented HTTP API behavior without external services or a database