browser/platform/protocol/run-contracts.md

Run Protocol Contracts

The platform side of run communication is split into independent contracts.

Control

Implemented HTTP JSON routes:

• POST /api/v1/run/control/hello
• POST /api/v1/run/control/heartbeat

Named control DTOs:

• RunHelloRequest
• RunHelloResponse
• RunHeartbeatRequest
• RunHeartbeatResponse
• RunCapabilityReport
• RunCapacityReport

Control payloads must remain small and must not include logs, artifact chunks, host paths, raw credentials, direct sockets, or long task results. Hello creates or updates run endpoint metadata and issues an in-memory platform session token. Heartbeat requires that active session token and may request capability refresh when the fingerprint changes.

Control is the highest-priority run/platform path. Artifact/file transfer load must not delay heartbeat acceptance or mutate heartbeat capacity state through heavy payload fields.

Job

Implemented HTTP JSON routes:

• POST /api/v1/run/jobs/claim
• POST /api/v1/run/jobs/ack
• POST /api/v1/run/jobs/progress
• POST /api/v1/run/jobs/result
• POST /api/v1/run/jobs/cancel
• POST /api/v1/run/jobs/reconcile

Named job DTOs:

• RunJobClaimRequest
• RunJobClaimResponse
• RunJobAckRequest
• RunJobProgressRequest
• RunJobResultRequest
• RunJobCancelPollRequest
• RunJobReconcileRequest
• RunJobReconcileResponse

Jobs must carry bounded metadata such as jobId, runEndpointId, serverInstanceId, capability, idempotencyKey, lease token, attempt, progress, terminal state, message, error code, and result reference. Job payloads must not carry logs, artifact chunks, host paths, raw credentials, direct sockets, or large inline result bodies.

Job ack, progress, cancellation polling, reconciliation, and terminal result calls are lightweight lifecycle metadata. They must remain valid while artifact chunks or log retries are pending, and duplicate equivalent terminal results remain idempotent under channel pressure.

Log Ingest

Implemented HTTP JSON routes:

• POST /api/v1/run/logs/batches
• POST /api/v1/log-streams/query

Named log DTOs:

• LogBatchIngestRequest
• LogBatchIngestResponse
• LogEntry
• LogStreamCursorRequest
• LogStreamCursorResponse

Log ingest supports bounded batches, sequence ranges, checksum validation, retry-safe duplicate acknowledgement, latest sequence tracking, and cursor query. Log payloads must not carry artifact chunks, host paths, raw credentials, direct sockets, or unbounded inline data.

Log ingest is durable and independently retried. Artifact/file transfer backlog must not prevent log batch acknowledgement, duplicate acknowledgement, cursor state updates, or spool cleanup.

The platform stores log stream metadata through repo.Store and stores log bodies through the configured LogBodyStore. The default file backend persists platform metadata to PLATFORM_METADATA_PATH and appends log entries to segmented JSONL files under PLATFORM_LOG_DIR; the memory backend is only for tests and disposable local development. MySQL/Postgres are appropriate for platform metadata, stream state, retention policy, indexes, and audit records, but should not be the primary row-per-log-line store for hundreds or thousands of servers. Production log bodies should move behind the same boundary to append/query backends such as ClickHouse, Loki, OpenSearch/Elasticsearch, or object-storage segments with compact indexes.

Artifact

Implemented HTTP JSON routes:

• POST /api/v1/run/artifacts/open
• POST /api/v1/run/artifacts/chunks
• POST /api/v1/run/artifacts/status
• POST /api/v1/run/artifacts/complete

Named artifact DTOs:

• ArtifactTransferOpenRequest
• ArtifactTransferOpenResponse
• ArtifactChunkUploadRequest
• ArtifactChunkUploadResponse
• ArtifactTransferStatusRequest
• ArtifactTransferStatusResponse
• ArtifactTransferCompleteRequest
• ArtifactTransferCompleteResponse
• ArtifactResponse

Artifact upload supports active run session validation, job/server-instance owner scoping, bounded JSON chunk payloads, per-chunk checksum validation, duplicate chunk acknowledgement, resume status, and final checksum verification before an artifact becomes available. Artifact transport is separate from control, job result, log ingest, plugin bridge, and browser file APIs.

Artifact/file transfer is the lower-priority heavy channel. Chunk upload and completion must not block control heartbeat, job ack/result delivery, cancellation/reconcile calls, or log ingest acknowledgement. Lightweight routes must reject heavy transfer payloads instead of accepting or storing them.

Game Client Bridge

The optional game client bridge is separate from run lifecycle, control registration, job handling, log ingest, and artifact transport.