Home / Projects / Orchestrata Ultimate / Decisions / ADR index / ADR-0132

ADR-0132: One tree is edited and the deployment copy is built from it at a pinned version — which tree is edited at the cut-over

← ADR-0131 · ADR-0133 →

The record

Status: Proposed (a disputed point; Mohamed rules) · Date: 2026-10-23

Context

Master has two copies of most orchestrata code:

The packages were lifted from a frozen src at e57782ea4. Some were generated by codetools templates, and some were hand-edited afterwards (b89593cb5, fe8dece4e in packages/volks).

The two positions, both on 2026-10-22:

• Mohamed, verbatim: "paackages is not for editing, uit is a copy of the code from src at a specific trime and version for deployment in that structure".
• The recorded design:
  • ADR-0103 (Accepted on probation 2026-10-15 until a POC passes): "the byte-faithful LIFT is the parity oracle; the clean target packages/<c>/src is the deliverable". The file exists only on branch architecture/domain-model (b3ea29a31), not on master or components.
  • ADR-0113 and LEVEL0: the cut-over removes src/orchestrata_ultimate/*, there is one merge, and /opt/orchestrata ships from that tree.
  • Python packaging practice (PyPA, uv, PEP 660; researched 2026-10-22): one edited source per package. The built wheel is the deployment artifact. Editable installs are for development only.

The two positions agree that one tree is edited and that a pinned copy, taken at a version, is what gets deployed. They disagree on which tree is edited after the cut-over, and on whether the deployment copy is a source tree or a built wheel.

Decision (proposed, needs Mohamed's ruling)

• Option A (Mohamed's statement). src/ stays the edited source. packages/ is generated from src/ at a pinned commit, in the component layout, and is never hand-edited. The generator reports drift, and edits found in packages/ are ported back to src.
• Option B (ADR-0103/0113, PyPA). Until the cut-over, src/ is edited and packages/ is regenerated from it, so it matches A. At the cut-over, packages/<c>/src becomes the single edited source and src/orchestrata_ultimate is removed. The deployment copy is each package's built wheel at a pinned version, installed non-editable into /opt/orchestrata's venv.
• Recommendation: B. It is A up to the cut-over, and it keeps "a copy at a specific time and version for deployment" as the wheel, which is the standard deployment artifact. It is the only option in which the cut-over ever completes. Under A, the 902-module tree and its 1,596 test modules that import orchestrata_ultimate stay forever.

Alternatives rejected

• Edit both trees. This is the current drift: 13 drifted files ported by hand.
• Deploy from a source tree. Rejected by the platform conventions (no deploy-in-place) and by ADR-0120: tests import from the installed environment.

Consequences

• If A is ruled: the cut-over plan (ADR-0113, INT-01..25, "remove the old tree") is superseded, a generator for packages/ from src/ becomes the deliverable, and ADR-0103 is rejected.
• If B is ruled: ADR-0103 leaves probation and lands on master. The cut-over checklist in ADR-0113 stands, with one workspace and lock, deptry in CI, and the test re-point (1,236 test modules whose imports do not resolve against the landed packages).

Provenance

• Mohamed's statement, 2026-10-22, as quoted above, and his challenge: "you even just agreed wuthb me blind withoutr research and verification on the practcoes".
• Research and evidence:
  • memory file packages-are-a-deployment-copy.md (marked DISPUTED);
  • wiki research page /projects/orchestrata-ultimate/research/;
  • ADR-0103 at b3ea29a31;
  • ADR-0113;
  • the session scratch notes ("Test re-point measurement").

Related ADRs

• Also mentioned: ADR-0103, ADR-0113, ADR-0120

Rulings cited

None.

Specs cited

None (or no spec page exists for the ones named).