Knowledge Wiki Orchestrata Ultimate

Orchestrata Ultimate › Gates › source-provenance

Gate: source-provenance
Purpose Prove that the suite imports the checkout it is testing, as a proper install
Where it runs Suite preflight, scripts/run_tests.py::_run_gates (first of five, run concurrently), so on every run_tests.py run, the pre-push hook and deploy/ship.sh's verify
Trigger Every run_tests.py run unless --skip-gates
Exact command python scripts/check_source_provenance.py [--python <interpreter>]
Blocks Exit 1 fails the preflight, and no test runs. Exit 0 passes
Ruling / ADR RUL-021 (each worktree owns its env); the proper-install ruling of 2026-10-20 in dd919d55c; ADR-0120

Why it exists

From the module docstring (read through the AST toolkit): on 2026-07-27 the "final gate" run in a worktree reported 30 failures that were pure artifacts. An exported PYTHONPATH=.../orchestrata-ultimate-architecture/src landed at sys.path[1] and outranked the worktree's own editable .pth entry at sys.path[6], so "the run executed the worktree's TESTS against a DIFFERENT BRANCH's SOURCE. Both directions of that verdict were worthless." The gate first landed in c3f0680c2 (2026-07-27).

On 2026-10-20 Mohamed ruled for a proper install: "i want a propper install" — no editable, .pth or in-place resolution (dd919d55c). The old check ("resolves to src/") then became permanently false, and 9b4ac72b4 (2026-10-21) re-based the gate on the install record.

What it checks

main() runs two checks, in order:

  1. Install origin. _install_origin() reads the PEP 610 direct_url.json of the orchestrata-ultimate distribution and compares its url with this checkout's file:// URI. A mismatch prints "Another checkout re-synced this venv. Fix: run uv sync --dev --no-editable from THIS checkout." and exits 1.
  2. Import location. A child interpreter (the one the suite uses, --python) imports orchestrata_ultimate with the current environment and reports __file__ and sys.path. If the package resolves under site-packages, the gate passes. Anything else exits 1, printing repo under test, expected source, actual source, any earlier sys.path entries that shadow it, and a PYTHONPATH hint when PYTHONPATH is set.

Diagram projects-orchestrata-ultimate-gates-source-provenance-1

Typical failures and how to fix them

Message Cause Fix
installed from : <other checkout> Another checkout ran uv sync against this venv env -u PYTHONPATH -u PYTEST_ADDOPTS uv sync --dev --no-editable --frozen from this checkout
THE SUITE WOULD TEST THE WRONG SOURCE TREE with identical expected source and actual source The venv is an editable install of this checkout. Check 1 passes (an editable install records the same origin); check 2 fails because the import resolves to src/, which is also expected_src Re-sync non-editable as above, then confirm "editable" is absent from .venv/lib/python3.14t/site-packages/orchestrata_ultimate-*.dist-info/direct_url.json
Same, with shadowed by these earlier sys.path entries A PYTHONPATH or .pth entry outranks the install Unset PYTHONPATH for the run; remove the stray .pth
cannot import orchestrata_ultimate No install, or a broken one Provision the worktree: scripts/worktrees.py provision <path>

What flips a venv editable. A plain uv run in a checkout without UV_NO_EDITABLE=1 (.envrc exports it; hooks and direnv-less worktrees do not get it) re-syncs the project as editable. Measured on 2026-10-22: two uv run calls in start-architecture-sync.sh and one in scripts/hooks/pre-commit (line 166) did it, and three pushes were refused (memory uv-run-flips-venv-editable; commit 8a2cb42ad, not yet pushed). The pre-push hook itself had the same defect and was fixed on 2026-10-21 (949c1628c). The full story is on Workflow — worked example.

Known gap. The editable case prints two equal paths and blames the "source tree", which does not name the condition that failed ("not under site-packages"). The gate's text has not been changed as of 2026-10-23.

Real output

From the 2026-10-22 push logs (session scratchpad):

[source-provenance] ❌ THE SUITE WOULD TEST THE WRONG SOURCE TREE
[source-provenance]    repo under test : /home/mohamed/workspace/wt-MAP-PRECOMMIT
[source-provenance]    expected source : /home/mohamed/workspace/wt-MAP-PRECOMMIT/src
[source-provenance]    actual source   : /home/mohamed/workspace/wt-MAP-PRECOMMIT/src
[source-provenance]    A run in this state proves nothing about this checkout. Fix the import path and re-run.

and, after the re-sync:

[source-provenance] ✅ orchestrata_ultimate resolves to /home/mohamed/workspace/wt-MAP-PRECOMMIT/.venv/lib/python3.14t/site-packages/orchestrata_ultimate

Wiring