orchestrata_ultimate.factory.scheduler.worktrees

Reference › orchestrata_ultimate › factory › scheduler › worktrees

worktrees leases real git worktrees for level-parallel building (SPEC-033 section 9, row B9). lease creates one git worktree for a task, checked out detached at the task's base commit under a .factory-worktrees directory. It is never a branch checkout, so a build's own git activity cannot be mistaken for the trunk branch or interfere with it. It returns a WorktreeLease (path, branch, commit and the paired FactNamespace keyed by task id and base commit, ADR-0004). release removes the checkout, with best-effort branch cleanup, taking an abandoned flag; _git is the subprocess helper. The git worktree and the graph namespace share a lifecycle, but this module makes no graph calls: garbage collection of abandoned namespaces belongs to PromotionStore.gc alone ("one owner for GC policy, not two"). The dag, queue and scheduler modules import it; tests are in tests/factory/test_scheduler_worktrees.py.

At a glance

Class diagram

Dependency diagram

API

Classes

WorktreeLease (dataclass)

Decorators: dataclass(frozen=True) · Line 27

A real git worktree checked out for exactly one dispatched task.

Functions

Source

Permalink: https://gitlab.com/MSamy/orchestrata-ultimate-architecture/-/blob/a4cbc2bdf/src/orchestrata_ultimate/factory/scheduler/worktrees.py

"""Real git-worktree leases for level-parallel building (SPEC-033 §9, B9).

One real ``git worktree`` per dispatched task, checked out **detached** at
the task's ``base_commit`` -- never a branch checkout, so a build's own
`git` activity inside its worktree can never be mistaken for (or interfere
with) the trunk branch. Every lease is paired 1:1 with a
:class:`~orchestrata_ultimate.factory.promotion.models.FactNamespace` keyed
``(task_id, base_commit)`` (ADR-0004): the git worktree and the Neo4j fact
namespace share the same lifecycle, but this module makes no graph calls
itself -- GC of abandoned namespaces stays the sole responsibility of
:meth:`orchestrata_ultimate.factory.promotion.store.PromotionStore.gc` (see
:func:`release`'s docstring: "one owner for GC policy, not two").
"""

from __future__ import annotations

import subprocess
from dataclasses import dataclass
from pathlib import Path

from orchestrata_ultimate.factory.promotion.models import FactNamespace

_WORKTREES_DIRNAME = ".factory-worktrees"


@dataclass(frozen=True)
class WorktreeLease:
    """A real git worktree checked out for exactly one dispatched task.

    ``branch`` is a reserved, never-checked-out label (``factory/<task_id>``)
    -- the worktree itself is a **detached** checkout of ``commit``; the
    name only exists so :func:`release` has something deterministic to
    ``git branch -D`` in the (best-effort, no-op-if-absent) case a build
    callable created a local branch of that name inside its own worktree.
    """

    path: Path
    branch: str
    commit: str
    namespace: FactNamespace


def _git(
    repo_root: Path, *args: str, check: bool = True
) -> subprocess.CompletedProcess[str]:
    return subprocess.run(
        ["git", *args],
        cwd=repo_root,
        capture_output=True,
        text=True,
        check=check,
    )


def lease(repo_root: Path, task_id: str, base_commit: str) -> WorktreeLease:
    """Create a real, detached ``git worktree`` for ``task_id`` at ``base_commit``.

    Checked out under ``<repo_root>/.factory-worktrees/<task_id>/`` via
    ``git worktree add --detach`` -- never a branch checkout (ADR-0004:
    merge is fact promotion, never the agent's own git). The paired
    :class:`FactNamespace` is ``FactNamespace(worktree=task_id,
    commit=base_commit)``, matching this task's dispatch identity to its
    fact-write scope 1:1.
    """
    worktrees_dir = repo_root / _WORKTREES_DIRNAME
    worktrees_dir.mkdir(parents=True, exist_ok=True)
    path = worktrees_dir / task_id
    _git(repo_root, "worktree", "add", "--detach", str(path), base_commit)
    namespace = FactNamespace(worktree=task_id, commit=base_commit)
    return WorktreeLease(
        path=path, branch=f"factory/{task_id}", commit=base_commit, namespace=namespace
    )


def release(
    repo_root: Path, worktree_lease: WorktreeLease, *, abandoned: bool
) -> WorktreeLease | None:
    """Remove ``worktree_lease``'s real checkout (+ best-effort branch cleanup).

    Always runs ``git worktree remove --force`` (the lease's directory is
    gone either way) and a best-effort ``git branch -D`` of the lease's
    reserved branch name (a no-op if no such branch was ever created --
    the common case, since :func:`lease` checks out detached).

    Args:
        abandoned: When ``True`` (the task was refused/failed/rejected, not
            promoted), the lease is returned so the CALLER can feed it (or
            its namespace) to
            :meth:`orchestrata_ultimate.factory.promotion.store.PromotionStore.gc`
            -- this function never GCs Neo4j facts itself, so there is one
            owner of GC policy, not two. ``False`` (the lease was promoted)
            returns ``None``.
    """
    _git(
        repo_root,
        "worktree",
        "remove",
        "--force",
        str(worktree_lease.path),
        check=False,
    )
    _git(repo_root, "branch", "-D", worktree_lease.branch, check=False)
    return worktree_lease if abandoned else None