Knowledge Wiki Orchestrata Ultimate

Orchestrata Ultimate › Plans › briefs › pi-orchestra

PI-ORCHESTRA — make the wheel installable, and make the proper install stick

Source: plans/briefs/pi-orchestra.md at 8a2cb42ad · last changed 2026-10-20 · first committed 2026-10-20 · 210 lines.

Prose pending.

Plan text

PI-ORCHESTRA — make the wheel installable, and make the proper install stick

Authority: Mohamed's ruling 2026-10-20, verbatim: "python is 3.14t and if love install is sym links or in place, no, i want a propper install", and on the torch defect "Fix it so the wheel is installable". Upstream: the coordinator commit that landed [tool.hatch.build.targets.wheel] packages = [...], removed the .envrc PYTHONPATH export, and re-based tests/conftest.py's provenance guard on PEP 610 (see that commit message for the measurements). Lesson L26: docs/lessons/L26-import-shadow-contaminated-proof.md.

Model routing: openrouter/qwen/qwen3-coder-next, explicit model= (Mohamed's session ruling; stated override of RUL-026's sonnet default). The coordinator re-runs every VERIFY before commit.

Already done — do NOT redo or revert: all three top-level packages (orchestrata_ultimate, orchestrata_tools, orchestrata_ast) now ship in the wheel; .venv is a proper non-editable install (direct_url.json → "editable":false, no _editable_impl_*.pth); .envrc no longer exports PYTHONPATH; the suite's provenance guard reads PEP 610 direct_url.json.

Guard corpus (restated — L7):

PACKET A — torch is a feature dependency declared as a core one, and it makes the wheel uninstallable

GOAL. orchestrata_ultimate's wheel cannot be installed by any consumer from a normal index, because a CORE runtime dependency is torch==2.12.1+cpu — a local-version wheel that exists only on https://download.pytorch.org/whl/cpu. PEP 621 metadata has no field for an index, and uv's [tool.uv.sources] / [[tool.uv.index]] are NOT published into the wheel, so a consumer resolving the wheel's own metadata finds nothing that can satisfy +cpu. Measured: uv pip install orchestrata_ultimate-1.5.0-py3-none-any.whl → "Because there is no version of torch==2.12.1+cpu … we can conclude that your requirements are unsatisfiable." codetools only ever resolved it because it depends on a GIT source, where this repo's own pyproject.toml is present during resolution.

Move the local-embedding stack behind an optional extra so the BASE distribution resolves from PyPI alone, and make dev/test keep working (they use the local backend).

Measured facts — verify each yourself before editing (L19: do not trust this text):

Design constraints (these are the ruling, not suggestions):

FENCE — Packet A:

Explicit negatives: do NOT touch tests/conftest.py, .envrc, [tool.hatch.build.targets.wheel] (just landed), [project.scripts], or anything in src/. Do NOT change SEMANTIC_EMBED_BACKEND values. Do NOT weaken the _assert_free_threaded() guard or any GIL check.

VERIFY (paste verbatim):

cd /home/mohamed/workspace/wt-COMPONENTS
uv lock
rm -rf /tmp/opencode/piA-dist && uv build --wheel -o /tmp/opencode/piA-dist
unzip -l /tmp/opencode/piA-dist/*.whl | grep -oE " (orchestrata_[a-z]+)/" | sort -u   # still all three
rm -rf /tmp/opencode/piA-venv && uv venv /tmp/opencode/piA-venv --python 3.14t
# THE POINT OF THE PACKET — the base wheel resolves with no extra index:
env -u PYTHONPATH uv pip install --python /tmp/opencode/piA-venv/bin/python /tmp/opencode/piA-dist/*.whl
uv sync --dev --no-editable
grep -n "SEMANTIC_EMBED_BACKEND" env/test.env
ORCHESTRATA_ENV_PROFILE=test python scripts/run_tests.py tests/semantic_graph/ --skip-gates
ORCHESTRATA_ENV_PROFILE=test python scripts/run_tests.py tests/core/threading/ --skip-gates   # GIL guard lane
uv run --no-sync ruff check pyproject.toml 2>/dev/null; uv run --no-sync ruff check src/ tests/ | tail -3

Expected: uv lock clean; all three packages still in the wheel; the clean-venv install of the BASE wheel SUCCEEDS with no --extra-index-url (this is the acceptance criterion — if it still fails on torch, the packet is not done); tests/semantic_graph/ green with the local backend still constructed (report the count); the GIL/threading lane green.

Known non-defect, do not chase: scripts/run_tests.py may print a git_sentinel ❌ ("a test wrote to the repository", a moved components ref) while the tests themselves report N passed, 0 failed. A CONCURRENT session is committing to this branch during runs; the sentinel attributes an external commit to the test. Report the test counts and name the sentinel line as this known artifact — do NOT "fix" it and do not weaken the sentinel.

DONE WHEN: the base wheel installs into a clean 3.14t venv from PyPI alone; dev/test still exercise the local embedder; prod's declared install no longer carries torch; every version floor and the GIL reasoning survive verbatim; uv.lock regenerated by uv lock; the five RUL-034 items addressed for a dependency-declaration change (no @traces apply — this is packaging, deliberately untraced per the two-lane rule; docs updated where they state the dependency set; wiki update is the coordinator's, not yours). Reply with: files changed, every VERIFY output verbatim, the extra's final name, and anything you could not execute faithfully, NAMED.

PACKET B — make the proper install stick, so it cannot silently drift back to editable

GOAL. uv sync installs the project and every workspace member EDITABLE by default (uv's own docs, [tool.uv] package: "Packages are built and installed into the virtual environment in editable mode"). The ruling wants a proper install, so the non-editable mode must be the DEFAULT here, not something one person remembers to pass. uv sync honours UV_NO_EDITABLE (measured in uv sync --help: --no-editable … [env: UV_NO_EDITABLE=]). Make every path that creates or refreshes an environment in this repo produce a non-editable install, and make the requirement visible where a reader would look.

MEASURE FIRST, then edit only what you measured. Inventory every place an environment is created or synced, and report the full list in your reply whether or not you change it:

grep -rn "uv sync\|uv pip install\|uv run\b" --include="*.sh" --include="*.py" --include="*.md" --include="*.toml" --include="*.yaml" --include="*.yml" --include=".envrc" . | grep -v "\.venv/\|__pycache__\|/plans/ast-"
grep -rn "UV_NO_EDITABLE\|--no-editable" . --include="*" 2>/dev/null | grep -v "\.venv/\|__pycache__"

Also inventory the worktree-provisioning path — this project's rule (RUL-021) is that every worktree gets its OWN full env, and there is a provisioning script for it (scripts/provision_worktree_env.py per ADR-0118's Tier-1 list; confirm it exists and read it before editing). A worktree provisioner that runs a bare uv sync will re-create an editable install and undo this packet.

Design constraint: prefer setting UV_NO_EDITABLE=1 where environments are MADE (.envrc for interactive shells, the provisioner, any deploy/install script) over editing dozens of uv sync call sites — but if a call site runs where no .envrc is loaded (a systemd unit, a container build, CI), that site needs the flag or the env var explicitly. Name which mechanism you used for each site and why. Do NOT introduce a wrapper script that replaces uv sync unless measurement shows the call sites are too many to make consistent — if you do introduce one, it must be wired into every site you found, not left as an option.

FENCE — Packet B:

Explicit negatives: do NOT touch pyproject.toml or uv.lock (Packet A owns them, and it runs concurrently — if you need a dependency change, report it, do not make it). Do NOT touch tests/conftest.py's provenance guard. Do NOT change endpoint values in env/*.env. Do NOT commit or push.

VERIFY (paste verbatim):

cd /home/mohamed/workspace/wt-COMPONENTS
grep -n "UV_NO_EDITABLE" .envrc
# a fresh shell-like environment produces a NON-editable install with no explicit flag:
env -u PYTHONPATH bash -lc 'cd /home/mohamed/workspace/wt-COMPONENTS && uv sync --dev >/dev/null 2>&1; cat .venv/lib/python3.14t/site-packages/orchestrata_ultimate-*.dist-info/direct_url.json'
ls .venv/lib/python3.14t/site-packages/ | grep -iE "editable|\.pth$"      # no _editable_impl_*.pth
ls -d .venv/lib/python3.14t/site-packages/orchestrata_*/                   # all three, real dirs
env -u PYTHONPATH .venv/bin/orchestrata-discover --help | head -3          # orchestrata_tools verb works
env -u PYTHONPATH .venv/bin/ast-sync --help | head -3                      # orchestrata_ast reachable
ORCHESTRATA_ENV_PROFILE=test python scripts/run_tests.py tests/core/config/ --skip-gates

Expected: direct_url.json shows "editable":false after a bare uv sync (that is the acceptance criterion — the default must now be proper); no _editable_impl_*.pth; all three packages present as real directories; both console scripts OK with no PYTHONPATH.

DONE WHEN: a bare uv sync in this repo yields a non-editable install; every environment-creating path you measured is covered or explicitly reported as out of reach with the reason; the requirement is documented where a new session would read it (AGENTS.md + .envrc); no out-of-fence edits. Reply with: the measured inventory of uv sync/uv pip install call sites (all of them, changed or not), the mechanism chosen per site, files changed, every VERIFY output verbatim, and anything you could not execute faithfully, NAMED.