# Run Log Ingest Contract

Logs are durable historical data. They are not transported as best-effort UI messages.

## Implemented Routes

- `POST /api/v1/run/logs/batches`: uploads one bounded log batch and receives an acknowledgement range.
- `POST /api/v1/log-streams/query`: queries stored log entries after a stream sequence cursor.

## Payloads

- `LogBatchIngestRequest`: run ID, session token, server instance ID, stream ID, source, sequence range, compression metadata, checksum, and bounded entries.
- `LogEntry`: sequence, timestamp, level, line, parser metadata, and redaction state.
- `LogBatchIngestResponse`: accepted sequence range, latest acknowledged sequence, duplicate flag, retry hint, and server time.
- `LogStreamCursorRequest`: stream ID, sequence cursor, and limit.
- `LogStreamCursorResponse`: ordered entries, next cursor, and latest acknowledged sequence.

## Local Spool

Run must write unacknowledged logs to a local spool/WAL before upload. Segments may be removed only after platform acknowledgement.

## Priority

Log flush has higher priority than artifact transfer. Artifact work must slow down when log spool pressure rises.

Log spool retry state is independent from artifact/file retry state. Acknowledged log batches may be removed even when artifact chunks are still pending, and artifact chunk acknowledgement must not alter log sequence state. Log ingest payloads carry bounded entries only and must not include artifact chunks, file bodies, host paths, raw credentials, or direct socket details.

## Deferred Channels

Browser live tail, external log storage backends, and optional game client bridge traffic remain separate future channels. Artifact transfer uses its own lower-priority channel and must not be multiplexed through log ingest.