first commit

2026-07-11 14:56:10 +08:00
commit 7e05d0a4e7
660 changed files with 78119 additions and 0 deletions
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-07-03
@@ -0,0 +1,79 @@
+## Context
+
+The platform already has a `RunEndpoint` domain resource and generic create/list/detail API. The run executable currently only produces a smoke summary and a base URL-normalizing client. The architecture requires a high-priority control channel for hello, heartbeat, version, capability, and capacity metadata before later job/log/artifact channels are implemented.
+
+This change implements the first control-channel workflow across `run/` and `platform/`. It stays on HTTP JSON and in-memory platform storage because persistence and streaming transport are later changes. The control payloads must remain small and must not carry logs, artifact chunks, job result bodies, host paths, raw credentials, or direct sockets.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Define typed run control protocol payloads in `run/protocol` and matching platform DTOs in `platform/dto`.
+- Add platform control routes for hello registration and heartbeat.
+- Persist/update run endpoint metadata through `service.Core` with validation and capability/capacity checks.
+- Generate platform session tokens on hello and require the matching token on heartbeat.
+- Add run-side client methods for hello and heartbeat.
+- Add tests for protocol shape, platform service/API behavior, run client requests, and a registration/heartbeat integration flow.
+
+**Non-Goals:**
+
+- No job claim, ack, progress, result, cancel, or reconcile channel.
+- No log ingest, artifact transfer, or game client bridge behavior.
+- No WebSocket/gRPC streaming transport.
+- No persistent database, token vault, mTLS, or auth policy engine.
+- No frontend pages, plugin behavior, billing, cloud host sales, or direct plugin-to-run access.
+
+## Decisions
+
+### Decision 1: HTTP JSON control endpoints
+
+The initial control channel uses `POST /api/v1/run/control/hello` and `POST /api/v1/run/control/heartbeat`. This matches the existing platform API shape and keeps the first registration workflow testable without introducing a streaming dependency.
+
+Alternative considered: one long-lived WebSocket. Rejected because the architecture explicitly separates control from heavier job/log/artifact channels and later transport choices should be made after the metadata loop is stable.
+
+### Decision 2: Session token is platform-generated and in-memory
+
+Hello returns a deterministic session token derived from platform-side session state. Heartbeat must echo that token for the same run endpoint. The in-memory repository remains the backing state for now.
+
+Alternative considered: accepting a run-provided session token. Rejected because platform must own control session acceptance and future auth hardening.
+
+### Decision 3: Run endpoint metadata remains the platform source of truth
+
+Hello and heartbeat write to the existing `RunEndpoint` domain resource. This avoids a separate control-session aggregate until persistence and auth requirements need it.
+
+Alternative considered: adding a new run session table/model now. Rejected because current storage is in-memory and this change only needs one active session per run endpoint.
+
+### Decision 4: Capability fingerprint is metadata only
+
+Heartbeat accepts a compact capability fingerprint and may request a capability refresh when it differs from platform metadata. The full capability list is still kept on the run endpoint payload.
+
+Alternative considered: transmitting full capability metadata on every heartbeat. Rejected because control payloads must stay small.
+
+### Decision 5: Run client stays transport-only
+
+`run/api.PlatformClient` will encode/decode control requests and responses, but runtime scheduling, retry loops, and background heartbeat timers remain future work.
+
+Alternative considered: starting a daemon heartbeat loop in this change. Rejected because that would expand scope beyond registration and complicate tests before job/log/artifact channels exist.
+
+## Risks / Trade-offs
+
+- [Risk] In-memory session tokens disappear on platform restart. Mitigation: document this as early development behavior and keep token handling behind `service.Core` for future persistence.
+- [Risk] Capability fingerprint refresh cannot carry detailed capability changes alone. Mitigation: heartbeat returns `refreshCapabilities` and later changes can add a capability report endpoint.
+- [Risk] No auth layer means registration token validation is minimal. Mitigation: require a non-empty registration token now and leave credential verification to the auth/control hardening change.
+- [Risk] Run client has methods but no daemon loop. Mitigation: keep this change testable and defer scheduling/retry policy to later run lifecycle work.
+
+## Migration Plan
+
+1. Add control protocol and DTO contracts.
+2. Add platform service methods and API handlers for hello/heartbeat.
+3. Add run client methods and tests for request/response behavior.
+4. Update protocol/route docs.
+5. Verify with platform tests, run tests, structure check, and strict OpenSpec validation.
+
+Rollback before dependent changes is removal of the control route/client additions and this OpenSpec change. After job/log/artifact changes depend on registered run endpoints, rollback must use a new OpenSpec change.
+
+## Open Questions
+
+- What registration credential source will replace the development registration token?
+- Should session tokens become signed JWTs, opaque DB-backed tokens, or mTLS-bound session identifiers?
+- What heartbeat interval and timeout thresholds should production use?
@@ -0,0 +1,28 @@
+## Why
+
+The platform can model run endpoints, but the run executor still has no real control-channel registration or heartbeat path. This change establishes the lightweight run-platform control loop so later job, log, and artifact channels can attach to known run sessions without exposing host paths or credentials.
+
+## What Changes
+
+- Add typed run control payloads for hello registration, heartbeat, capability reporting, capacity reporting, session tokens, and polling hints.
+- Add platform API routes for run hello and heartbeat that create/update run endpoint metadata through `service.Core`.
+- Add service-level control registration behavior that validates endpoint identity, capabilities, capacity, and session token continuity.
+- Extend the run-side platform client with hello and heartbeat calls using the typed control protocol.
+- Add focused platform API/service tests and run client tests, including an integration-style registration/heartbeat flow.
+
+## Capabilities
+
+### New Capabilities
+
+- `run-control-registration`: Platform/run control-channel registration, heartbeat, session token, capability, and capacity metadata workflow.
+
+### Modified Capabilities
+
+- None.
+
+## Impact
+
+- Affects `platform/` and `run/` only.
+- Adds Go protocol/DTO/domain/service/API code and tests for control registration.
+- Updates run control documentation and platform route catalog.
+- Does not implement job claim/ack/result, log ingest, artifact transfer, plugin bridge behavior, frontend pages, billing, cloud host sales, or direct plugin/run access.
@@ -0,0 +1,71 @@
+## ADDED Requirements
+
+### Requirement: Run control payloads are typed and bounded
+The system SHALL define typed run control payloads for hello registration, hello response, heartbeat, heartbeat response, capability report, and capacity report without carrying logs, artifact chunks, job result bodies, host paths, raw credentials, or direct sockets.
+
+#### Scenario: Control payloads are used
+- **WHEN** run or platform code sends control registration or heartbeat data
+- **THEN** it MUST use named protocol/DTO types from dedicated protocol or DTO packages
+
+#### Scenario: Control payload stays lightweight
+- **WHEN** run sends hello or heartbeat
+- **THEN** the request MUST include run ID, display name, version, status, capability summary, and capacity metadata only
+
+### Requirement: Platform accepts run hello registration
+The platform SHALL expose a hello endpoint that accepts a run registration request, validates it, persists or updates the run endpoint metadata, and returns a platform-generated session token with polling hints.
+
+#### Scenario: New run endpoint registers
+- **WHEN** run sends a valid hello request for an unknown run endpoint
+- **THEN** platform MUST create a run endpoint, mark it online, store capabilities/capacity, and return an accepted hello response with a session token
+
+#### Scenario: Existing run endpoint registers again
+- **WHEN** run sends a valid hello request for an existing run endpoint
+- **THEN** platform MUST update version, display name, capabilities, capacity, heartbeat time, and return a new accepted hello response
+
+#### Scenario: Invalid hello request is submitted
+- **WHEN** run sends a missing ID, missing registration token, invalid capacity, or empty required metadata
+- **THEN** platform MUST return a JSON validation error and MUST NOT create a run endpoint
+
+### Requirement: Platform accepts authenticated run heartbeat
+The platform SHALL expose a heartbeat endpoint that requires the active platform-issued session token for the target run endpoint and updates status, capacity, heartbeat time, and capability fingerprint state.
+
+#### Scenario: Heartbeat succeeds
+- **WHEN** run sends a heartbeat with the active session token
+- **THEN** platform MUST update the run endpoint heartbeat metadata and return an accepted heartbeat response with the next heartbeat interval
+
+#### Scenario: Heartbeat uses invalid session token
+- **WHEN** run sends a heartbeat with a missing or stale session token
+- **THEN** platform MUST reject it with a JSON validation error and MUST NOT update the endpoint metadata
+
+#### Scenario: Capability fingerprint changes
+- **WHEN** run heartbeat reports a capability fingerprint that differs from platform's known fingerprint
+- **THEN** platform MUST accept the heartbeat and request capability refresh in the heartbeat response
+
+### Requirement: Run client performs control registration calls
+The run-side platform client SHALL provide typed hello and heartbeat methods that call the platform control endpoints and decode typed responses.
+
+#### Scenario: Run sends hello through client
+- **WHEN** run code calls the hello client method
+- **THEN** the client MUST send a JSON `POST` to `/api/v1/run/control/hello` and decode the hello response
+
+#### Scenario: Run sends heartbeat through client
+- **WHEN** run code calls the heartbeat client method
+- **THEN** the client MUST send a JSON `POST` to `/api/v1/run/control/heartbeat` and decode the heartbeat response
+
+#### Scenario: Platform returns error
+- **WHEN** the platform control endpoint returns a non-success status
+- **THEN** the run client MUST return an error and MUST NOT treat the control call as accepted
+
+### Requirement: Control registration is documented separately from heavier channels
+The run/platform route and protocol documentation SHALL identify implemented control registration routes and explicitly defer job, log, artifact, and game client bridge transport.
+
+#### Scenario: Contributor inspects control docs
+- **WHEN** a contributor opens run or platform protocol docs
+- **THEN** the docs MUST show hello/heartbeat routes as implemented and heavier channels as deferred
+
+### Requirement: Control registration is verified
+The change SHALL include platform service/API tests, run client tests, and an integration-style hello/heartbeat flow test.
+
+#### Scenario: Verification commands run
+- **WHEN** the change is complete
+- **THEN** `go test ./...` from `platform/`, `go test ./...` from `run/`, `scripts/check-structure.sh`, and `openspec validate implement-run-control-registration --strict` MUST pass
@@ -0,0 +1,34 @@
+## 1. Control Contracts
+
+- [x] 1.1 Add typed run control protocol payloads in `run/protocol` for hello, heartbeat, capability report, and capacity report.
+- [x] 1.2 Add matching platform DTO/domain contracts and conversion helpers for run control hello and heartbeat.
+
+## 2. Platform Control Registration
+
+- [x] 2.1 Extend platform service behavior to register run endpoints, issue session tokens, validate heartbeat tokens, and request capability refresh on fingerprint drift.
+- [x] 2.2 Implement platform control HTTP routes for hello and heartbeat using named DTOs and service methods.
+- [x] 2.3 Add platform service/API tests for new registration, re-registration, heartbeat success, invalid tokens, validation failures, and capability refresh.
+
+## 3. Run Control Client
+
+- [x] 3.1 Extend `run/api.PlatformClient` with typed hello and heartbeat methods.
+- [x] 3.2 Add run client tests for request paths, JSON payloads, response decoding, and platform error handling.
+- [x] 3.3 Add an integration-style test that performs platform hello then heartbeat through the run client.
+
+## 4. Documentation
+
+- [x] 4.1 Update run and platform protocol/route documentation to mark hello/heartbeat implemented and heavier channels deferred.
+
+## 5. Verification
+
+- [x] 5.1 Run `go test ./...` from `platform/` and record evidence.
+- [x] 5.2 Run `go test ./...` from `run/` and record evidence.
+- [x] 5.3 Run `scripts/check-structure.sh` and record evidence.
+- [x] 5.4 Run `openspec validate implement-run-control-registration --strict` and record evidence.
+
+## Evidence
+
+- 2026-07-03: `go test ./...` from `platform/` passed.
+- 2026-07-03: `go test ./...` from `run/` passed.
+- 2026-07-03: `scripts/check-structure.sh` passed with `structure check passed`.
+- 2026-07-03: `openspec validate implement-run-control-registration --strict` passed with `Change 'implement-run-control-registration' is valid`.