first commit

openspec/changes/implement-run-job-channel/specs/run-job-channel/spec.md

@@ -0,0 +1,104 @@
+## ADDED Requirements
+
+### Requirement: Run job payloads are typed and bounded
+The system SHALL define typed run job payloads for claim, claim response, ack, progress, result, cancel request, cancel polling, and reconcile workflows without carrying logs, artifact chunks, host paths, raw credentials, direct sockets, or large inline result bodies.
+
+#### Scenario: Job payloads are used
+- **WHEN** run or platform code sends job lifecycle data
+- **THEN** it MUST use named protocol/DTO types from dedicated protocol or DTO packages
+
+#### Scenario: Job payload stays bounded
+- **WHEN** run submits job progress or result
+- **THEN** the request MUST include job identity, run endpoint identity, session token, lifecycle state, progress metadata, message, error code, and result reference only
+
+### Requirement: Platform lets run claim queued jobs
+The platform SHALL expose a job claim endpoint that validates run session continuity, selects a queued job assigned to the run endpoint, leases it, and returns bounded job metadata.
+
+#### Scenario: Run claims queued job
+- **WHEN** a registered run endpoint requests a job claim and a queued job exists for that endpoint
+- **THEN** platform MUST mark the job accepted, return the job metadata, lease token, attempt number, and polling hints
+
+#### Scenario: No queued job exists
+- **WHEN** a registered run endpoint requests a job claim and no queued job exists for that endpoint
+- **THEN** platform MUST return an accepted empty claim response without changing unrelated jobs
+
+#### Scenario: Claim uses invalid session token
+- **WHEN** run submits a claim with a missing or stale session token
+- **THEN** platform MUST return a JSON validation error and MUST NOT change job state
+
+### Requirement: Platform accepts job acknowledgements and progress
+The platform SHALL expose job ack and progress endpoints that require the active session token and active job lease for the run endpoint.
+
+#### Scenario: Job ack succeeds
+- **WHEN** run acknowledges an active lease for an accepted job
+- **THEN** platform MUST keep or move the job to a running lifecycle state and return an accepted ack response
+
+#### Scenario: Job progress succeeds
+- **WHEN** run reports bounded progress for an accepted or running job
+- **THEN** platform MUST update percent, message, heartbeat time, and return an accepted progress response
+
+#### Scenario: Invalid progress is submitted
+- **WHEN** run reports progress outside 0 through 100 or with a stale lease token
+- **THEN** platform MUST return a JSON validation error and MUST NOT update the job
+
+### Requirement: Platform accepts idempotent terminal job results
+The platform SHALL expose a result endpoint that accepts terminal succeeded, failed, or cancelled results for an active lease and treats repeated equivalent terminal result submissions as idempotent.
+
+#### Scenario: Job result succeeds
+- **WHEN** run submits a valid terminal result for an active lease
+- **THEN** platform MUST update the job terminal state, progress, result reference, and return an accepted result response
+
+#### Scenario: Duplicate terminal result is submitted
+- **WHEN** run repeats the same terminal result for a job already in that terminal state
+- **THEN** platform MUST return the same accepted terminal result response without mutating unrelated metadata
+
+#### Scenario: Conflicting terminal result is submitted
+- **WHEN** run submits a different terminal result for a job already terminal
+- **THEN** platform MUST return a JSON validation error and MUST NOT overwrite the existing result
+
+### Requirement: Platform supports job cancellation polling
+The platform SHALL expose a service/API path to request cancellation for a job and a run-facing path to poll cancellation for the active lease.
+
+#### Scenario: Platform requests cancellation
+- **WHEN** platform requests cancellation for an accepted or running job
+- **THEN** platform MUST record the cancel request and keep the job available for run cancellation polling
+
+#### Scenario: Run polls cancellation
+- **WHEN** run polls cancellation for an active leased job with a cancel request
+- **THEN** platform MUST return a cancel response naming that job and cancellation reason
+
+### Requirement: Platform supports run reconciliation
+The platform SHALL expose a reconcile endpoint that lets a registered run endpoint report active job IDs after restart and receive platform-known active jobs for that endpoint.
+
+#### Scenario: Run reconciles active jobs
+- **WHEN** run submits active job IDs for its endpoint after restart
+- **THEN** platform MUST return active jobs known to the platform for that endpoint and mark unknown reported jobs for run-side cleanup
+
+#### Scenario: Reconcile uses invalid session token
+- **WHEN** run submits reconcile with a missing or stale session token
+- **THEN** platform MUST return a JSON validation error and MUST NOT change job state
+
+### Requirement: Run client performs job-channel calls
+The run-side platform client SHALL provide typed claim, ack, progress, result, cancel polling, and reconcile methods that call the platform job endpoints and decode typed responses.
+
+#### Scenario: Run sends job channel calls through client
+- **WHEN** run code calls job-channel client methods
+- **THEN** the client MUST send JSON `POST` requests to the matching `/api/v1/run/jobs/*` endpoints and decode typed responses
+
+#### Scenario: Platform returns job error
+- **WHEN** a platform job endpoint returns a non-success status
+- **THEN** the run client MUST return an error and MUST NOT treat the job call as accepted
+
+### Requirement: Job channel is documented separately from other channels
+The run/platform route and protocol documentation SHALL identify implemented job-channel routes and explicitly keep control, log ingest, artifact transfer, and game client bridge transport separate.
+
+#### Scenario: Contributor inspects job docs
+- **WHEN** a contributor opens run or platform protocol docs
+- **THEN** the docs MUST show job claim, ack, progress, result, cancel polling, and reconcile routes as implemented while heavier log/artifact channels remain deferred
+
+### Requirement: Job channel is verified
+The change SHALL include platform service/API tests, run client tests, job lifecycle tests, and idempotency/reconciliation tests.
+
+#### 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-job-channel --strict` MUST pass