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

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