browser/openspec/changes/complete-run-build-download-flow/specs/run-build-download-flow/spec.md

ADDED Requirements

Requirement: Local debug snapshots run source into a closed build bucket

The system SHALL default local debug run source input to the independent run/ checkout under the browser repository root when that checkout exists, SHALL keep that checkout outside browser Git tracking, and SHALL snapshot that source into an ignored closed build bucket before build-capable local debug execution.

Scenario: Default run source snapshot resolution

• WHEN local debug scripts start the run worker without an explicit RUN_SOURCE_DIR or legacy RUN_REPO_DIR
• THEN they use <browser-root>/run as editable source input, copy it into RUN_BUILD_SOURCE_ROOT under an ignored local build bucket, and start the local bootstrap worker from a binary built from that snapshot

Scenario: Sibling checkout is optional

• WHEN /Users/tasia/Desktop/code/run exists or does not exist
• THEN local debug behavior does not depend on that sibling checkout unless RUN_SOURCE_DIR or legacy RUN_REPO_DIR is explicitly overridden

Requirement: Run distribution builds are plugin and job isolated

The run worker SHALL build generated run and client-manager distributions in a closed workspace scoped by plugin ID and job ID, and SHALL NOT use a mutable per-server build directory or editable source checkout for source, config, archive, upload, or terminal result state.

Scenario: Same plugin builds for multiple servers

• WHEN two distribution.build jobs for different servers but the same plugin run concurrently or back-to-back
• THEN each job writes to a distinct plugin/job workspace and uploads only its assigned artifact ID

Scenario: Build package config isolation

• WHEN a run distribution archive is produced
• THEN its config belongs to the job's server instance, plugin, endpoint, target, key generation, and auth key without leaking those secret values through API or UI responses

Requirement: Generated run artifacts are downloadable after build success

The system SHALL make a generated run distribution downloadable only after the build job succeeds and the referenced artifact is available, checksummed, and owned by the build job.

Scenario: Download latest generated run

• WHEN a server has an available run distribution
• THEN /api/v1/server-instances/{id}/run/download returns a browser-safe artifact reference and /api/v1/artifacts/{artifactId}/content returns bounded byte ranges with checksum headers

Scenario: No synthetic success before artifact upload

• WHEN a distribution build result is reported before the artifact upload is available
• THEN Platform rejects the terminal success and the distribution remains non-downloadable

Requirement: Local smoke proves run build and download

The local debug smoke SHALL fail when a build-capable run endpoint cannot complete run generation and artifact download for the SCUM fixture.

Scenario: Build-capable endpoint smoke

• WHEN scum-alpha exposes generate-run as available
• THEN smoke generates the run package, waits for the build job to succeed, opens the latest download reference, reads the artifact content, verifies size/checksum metadata, and rejects forbidden fragments

Scenario: Build-unavailable endpoint smoke

• WHEN the endpoint does not advertise distribution.build
• THEN smoke records that generation is unavailable without claiming a fake run artifact was built