run/protocol/log-ingest.md

Run Live Log Relay Contract

Run log traffic is a best-effort push of output observed now. It is not a durable log database, delivery queue, or acknowledgement-dependent lifecycle channel. Game plugins own durable log storage and analysis.

Implemented Routes

• POST /api/v1/run/logs/relay: pushes one bounded current-output batch to the platform relay. The platform may forward it to live subscribers, but does not persist the body or require a delivery acknowledgement.
• POST /api/v1/log-streams/query: queries stored log entries after a stream sequence cursor.
• GET /api/v1/server-instances/{id}/logs/events: browser-facing Server-Sent Events stream for the current supervised process session. A new subscriber starts at the live boundary and receives no platform log history.

Payloads

• LogBatchIngestRequest: run ID, session token, server instance ID, stream ID, source, sequence range, compression metadata, checksum, and opaque entries.
• LogEntry: sequence, timestamp, level, opaque line, and parser metadata.
• LogBatchIngestResponse: accepted sequence range, latest stream metadata sequence, compatibility duplicate/retry fields, and server time.
• LogStreamCursorRequest: stream ID, sequence cursor, and limit.
• LogStreamCursorResponse: compatibility ordered entries, next cursor, and latest stored metadata sequence.
• LogStreamEventResponse: safe browser event containing server ID, stream metadata, latest sequence, and one log entry.

Autonomous lifecycle output uses run.<runEndpointId>.<serverInstanceId>.<logSessionId>.<streamKey> stream IDs. The platform creates or updates stream metadata from the signed relay batch; the body remains live-only.

Priority

Live relay is asynchronous and lower priority than control and lifecycle progress. A full in-memory relay queue or a failed relay request drops the current event and never blocks, retries, or changes lifecycle state. Run does not create a log spool, resend backlog, or platform delivery watermark.

Log relay payloads preserve supervised stdout/stderr and plugin-declared file tail text verbatim. Run does not inspect, filter, redact, or content-truncate those payloads; the channel still must not carry artifact chunks or direct socket APIs.

Browser Channel

Browser live tail is a platform SSE fan-out from current relay events and process-session metadata. Historical log queries and plugin-owned storage are separate channels. Artifact transfer uses its own lower-priority channel and must not be multiplexed through live log relay.