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

Why

The run build/download flow is split across Platform, platform_web, local debug scripts, and the independent run checkout. The editable run source may live at browser/run for convenience, but that directory must be treated as source input only. Local debug must snapshot or upload that source into an ignored, closed build bucket, let Platform dispatch distribution.build, build from the bucket, and prove the generated artifact can be downloaded and executed/updated without using the editable source tree as the runtime artifact.

What Changes

• Treat run/ under this repository root as the editable independent run source checkout for local debug, while keeping it ignored by the browser repository and still owned by git@git.npc0.com:admin343/run.git.
• Snapshot the editable run source into a closed ignored local build bucket before starting build-capable local debug flows; RUN_BUILD_SOURCE_ROOT must point at that bucket snapshot, not the editable checkout.
• Build the local bootstrap run worker from the bucket snapshot instead of executing browser/run in place; generated run packages remain Platform-dispatched distribution.build artifacts.
• Harden run distribution build workspaces so build output is isolated by plugin and job, not by server-wide mutable directories or editable source folders.
• Add tests that prove two servers for the same plugin can generate separate run distributions without artifact/config/key/result cross-talk.
• Upgrade local smoke proof so scum-alpha run generation is mandatory when the run endpoint advertises distribution.build, then download the generated artifact and verify safe metadata.
• Document every configuration value operators must provide or may tune for local debug and run distribution builds.

Capabilities

New Capabilities

• run-build-download-flow: Covers local-debug source snapshotting, closed build buckets, plugin/job-scoped run package builds, browser-safe run artifact downloads, and same-plugin multi-server build isolation.

Modified Capabilities

• run-distribution-and-client-managers: Completed implementation must use the current-directory run checkout only as source input and prove generated run artifacts are downloadable.
• artifact-transfer-channel: Completed implementation must prove browser downloads and run artifact uploads remain chunked, checksummed, and free of leaked host paths or secrets.

Impact

• Affected roots: scripts/, platform/, platform_web/, and the ignored independent checkout at run/.
• Affected local configuration: RUN_SOURCE_DIR/legacy RUN_REPO_DIR, RUN_BUILD_BUCKET_ROOT, RUN_BUILD_SOURCE_ROOT, RUN_BOOTSTRAP_BIN, RUN_WORKSPACE_ROOT, RUN_SPOOL_ROOT, RUN_MAX_JOBS, RUN_PLATFORM_URL, RUN_ENDPOINT_ID, platform storage/artifact paths, and bootstrap credentials.
• Verification requires structure checks, Platform tests, run tests from run/, frontend tests where touched, OpenSpec validation, and local debug smoke evidence.