browser/openspec/changes/harden-log-artifact-channel-isolation/specs/log-artifact-channel-isolation/spec.md

ADDED Requirements

Requirement: Run channels preserve non-starvation under large transfers

The run executor SHALL keep control heartbeat, job acknowledgement, job result delivery, and log batch upload on bounded execution paths that are not blocked by large artifact or file transfer work.

Scenario: Artifact upload does not block lifecycle calls

• WHEN a run endpoint is uploading or retrying a large artifact or file transfer
• THEN control heartbeat, job acknowledgement, job progress, cancellation polling, reconciliation, and terminal job result calls MUST remain able to complete through their typed platform client methods without waiting for the transfer payload to finish

Scenario: Log upload continues during transfer pressure

• WHEN artifact or file transfer chunks are queued, slow, or retrying
• THEN the run log spool MUST still select bounded log batches, upload them through the log ingest client, and remove acknowledged batches independently from artifact/file queue state

Requirement: Platform routes mutate only their own channel state

The platform SHALL handle interleaved control, job, log, artifact, and file requests for the same run endpoint without one channel accepting another channel's payload or mutating another channel's state.

Scenario: Interleaved valid requests succeed independently

• WHEN a registered run endpoint interleaves valid heartbeat, job ack/result, log batch ingest, and artifact chunk or completion requests
• THEN each route MUST validate its own typed DTO, update only the corresponding control/job/log/artifact state, and return the same acknowledgement semantics as if the requests were sent without interleaving

Scenario: Heavy payload is rejected from lightweight routes

• WHEN a control, job, or log route receives an artifact chunk, file body, host path, raw credential, direct socket, or other transport payload owned by another channel
• THEN the platform MUST reject the request as a JSON validation error and MUST NOT mutate control session, job lifecycle, log acknowledgement, or artifact state

Requirement: Retry queues remain independently bounded

The run executor SHALL keep log retry state and artifact/file retry state independently bounded and independently acknowledged.

Scenario: Artifact retry backlog does not consume log retry state

• WHEN artifact or file chunks remain unacknowledged after platform upload failures
• THEN the artifact/file retry queue MUST retain those chunks without preventing log spool retry listing, log batch upload, or acknowledged log batch removal

Scenario: Log retry backlog does not consume artifact retry state

• WHEN log batches remain unacknowledged after platform ingest failures
• THEN the log spool MUST retain those batches without preventing artifact/file retry listing, chunk upload, or acknowledged artifact chunk removal

Requirement: Job terminal results remain bounded and prioritized

The run job channel SHALL submit terminal job results as bounded metadata and result references, not inline logs, artifact chunks, file bodies, host paths, raw credentials, or direct sockets.

Scenario: Terminal result arrives while transfer is active

• WHEN a job finishes while artifact/file transfer work is still active or retrying
• THEN run MUST submit the terminal job result through the job result endpoint with bounded result metadata and the platform MUST accept or reject it only according to job lease and idempotency rules

Scenario: Duplicate terminal result remains idempotent under pressure

• WHEN run retries an equivalent terminal job result while log and artifact retries are also pending
• THEN platform MUST return the accepted idempotent terminal result response and MUST NOT duplicate logs, chunks, artifacts, or unrelated job metadata

Requirement: Channel isolation is documented and verified

The change SHALL document the enforced priority and isolation rules and SHALL include deterministic platform/run tests for interleaved requests, retry independence, and large-transfer non-starvation.

Scenario: Contributor inspects channel docs

• WHEN a contributor opens run or platform protocol documentation
• THEN the docs MUST state that control and job lifecycle calls are lightweight, log ingest is durable and independently retried, artifact/file transfer is chunked and lower priority, and no lightweight route accepts heavy transfer payloads

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 harden-log-artifact-channel-isolation --strict MUST pass