75 lines
4.4 KiB
Markdown
75 lines
4.4 KiB
Markdown
## 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
|