molecule-ai/docs
35
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(runtime): document PyPI-canonical / git-mirror-lag asymmetry

Browse Source 
Adds a "Runtime Distribution" section to agent-runtime/workspace-runtime.md
explaining that the PyPI wheel is the canonical artifact and the
molecule-ai-workspace-runtime git mirror may lag behind (or be skipped
entirely on transient publish failures).

Originally drafted as a README change to the mirror itself
(molecule-ai-workspace-runtime#62), but mirror-guard correctly blocks
direct PRs there. The docs surface is the right home for "how the
publish pipeline works" — it's discoverable from the agent-runtime
section and lives next to the existing Boot-Smoke Contract section
that gates publish.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Hongming Wang 2026-05-01 21:20:00 -07:00
parent 86cf6c3a5c
commit d6282cb127
1 changed files with 22 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
content/docs/agent-runtime/workspace-runtime.md
View File

@ -139,6 +139,28 @@ If you need correctness coverage, write a separate integration test that runs th
A `config.yaml` from the template repo's root is mounted at `/configs/config.yaml`.
## Runtime Distribution: PyPI Is Canonical, The Git Mirror May Lag
The runtime ships as **two surfaces**, and only one of them is wire-truth.
| Surface | Repo / location | Role |
|---|---|---|
| **PyPI wheel** | `pip install molecule-ai-workspace-runtime==X.Y.Z` | **Canonical artifact.** Workspace template images, the controlplane runtime smoke harness, and self-hosters all consume this. |
| **Git mirror** | [`Molecule-AI/molecule-ai-workspace-runtime`](https://github.com/Molecule-AI/molecule-ai-workspace-runtime) | **Human-readable copy.** Exists for browsing + giving `mirror-guard` a concrete branch to enforce its "no direct PRs" policy against. |
Both are produced by the [`publish-runtime.yml`](https://github.com/Molecule-AI/molecule-monorepo/blob/main/.github/workflows/publish-runtime.yml) workflow on every push to `molecule-monorepo/workspace/`, but **the wheel publish and the mirror push are separate steps**. The mirror push can lag the wheel by hours, or be skipped entirely on transient failures while the wheel still ships.
If you're chasing "is module X in the published runtime yet?", trust the wheel listing, not the mirror's `git log`:
```bash
pip download molecule-ai-workspace-runtime==X.Y.Z --no-deps
unzip -l molecule_ai_workspace_runtime-X.Y.Z-*.whl | grep your_module
```
To find out what version the controlplane is actually deploying, check the workspace template image's `requirements.txt` pin (it's a `>=`, so the resolved version is whatever PyPI hands back at image-build time — not whatever's in the mirror).
**Do not edit the git mirror directly.** `mirror-guard` rejects all PRs to `molecule-ai-workspace-runtime`. Edit `molecule-monorepo/workspace/` and let `publish-runtime.yml` regenerate both surfaces.
## Core Runtime Pieces
| File | Responsibility |