browser/openspec/changes/implement-log-ingest-pipeline/specs/log-ingest-pipeline/spec.md

ADDED Requirements

Requirement: Log ingest payloads are typed and bounded

The system SHALL define typed log ingest payloads for log entries, batch ingest requests, batch acknowledgements, and stream cursor queries without carrying artifact chunks, host paths, raw credentials, direct sockets, or unbounded inline data.

Scenario: Log payloads are used

• WHEN run or platform code sends log ingest data
• THEN it MUST use named protocol/DTO types from dedicated protocol or DTO packages

Scenario: Log batch stays bounded

• WHEN run uploads a log batch
• THEN the request MUST include run endpoint ID, session token, stream identity, sequence range, checksum, compression metadata, and bounded entries only

Requirement: Platform accepts durable log batches

The platform SHALL expose a log batch ingest endpoint that validates run session continuity, stream metadata, checksum, and sequence continuity before acknowledging accepted ranges.

Scenario: Contiguous batch succeeds

• WHEN run uploads a valid batch whose first sequence follows the platform's latest acknowledged sequence for that stream
• THEN platform MUST store the entries, update latest acknowledged sequence, and return an accepted acknowledgement for the range

Scenario: Duplicate acknowledged batch is retried

• WHEN run uploads a batch whose range is already fully acknowledged and checksum matches the stored range
• THEN platform MUST return an accepted idempotent acknowledgement without duplicating entries

Scenario: Out-of-order batch is submitted

• WHEN run uploads a batch with a sequence gap or conflicting duplicate data
• THEN platform MUST return a JSON validation error and MUST NOT advance the acknowledged sequence

Requirement: Platform exposes bounded log stream query

The platform SHALL expose a bounded log query endpoint that returns entries for one stream after a cursor sequence and includes the next cursor.

Scenario: Query returns entries after cursor

• WHEN a caller queries a stream after an acknowledged sequence
• THEN platform MUST return ordered entries after that cursor up to the requested limit and include the next cursor

Scenario: Query target is missing

• WHEN a caller queries a missing stream
• THEN platform MUST return a JSON not found error

Requirement: Run spool retains unacknowledged batches

The run-side log spool SHALL persist unacknowledged batches locally and remove them only after platform acknowledgement covers their sequence range.

Scenario: Platform upload fails

• WHEN a batch remains unacknowledged after an upload failure
• THEN the spool MUST retain the batch for retry

Scenario: Platform acknowledges batch

• WHEN platform returns an acknowledgement covering a batch range
• THEN the spool MUST mark that range acknowledged and remove the batch from pending retry listing

Requirement: Run client uploads log batches

The run-side platform client SHALL provide a typed log batch ingest method that calls the platform log endpoint and decodes typed acknowledgement responses.

Scenario: Run uploads log batch through client

• WHEN run code calls the log ingest client method
• THEN the client MUST send a JSON POST to /api/v1/run/logs/batches and decode the acknowledgement response

Scenario: Platform rejects log batch

• WHEN the platform log ingest endpoint returns a non-success status
• THEN the run client MUST return an error and MUST NOT treat the batch as acknowledged

Requirement: Log ingest is documented separately from other channels

The run/platform route and protocol documentation SHALL identify implemented log ingest routes and explicitly keep control, job, artifact, and game client bridge transport separate.

Scenario: Contributor inspects log docs

• WHEN a contributor opens run or platform protocol docs
• THEN the docs MUST show log batch ingest and query as implemented while artifact and game client channels remain separate

Requirement: Log ingest pipeline is verified

The change SHALL include platform service/API tests, run spool tests, run client tests, and retry/ack/query coverage.

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-log-ingest-pipeline --strict MUST pass