phase-loop-runtime 0.2.0__py3-none-any.whl

phase_loop_runtime/consiliency_scaffold.py

@@ -0,0 +1,305 @@
+"""CS-0.5 -- the `.consiliency/` scaffolder (first-writer).
+
+`phase-loop consiliency-scaffold --repo <path> --archetype <name>` writes a
+schema-valid `.consiliency/` layout: a manifest declaring the archetype(s) +
+governed-doc allowlist, a contract-version/status artifact, an (initially
+empty) interface declaration, and presence-only L0 stubs for the archetype's
+required baseline docs.
+
+Design constraints (roadmap CS-0.5):
+
+* **Additive, never destructive.** This module never modifies or deletes
+  `.phase-loop/` or `.pipeline/`, and it never overwrites a file that already
+  exists -- "first-writer" means the scaffolder only fills gaps. Re-running it
+  on an already-scaffolded (or hand-edited) repo is a safe no-op for anything
+  present.
+* **No fake projections.** Where the required-documents registry marks a doc
+  ``l0_stub_allowed: true`` (the common case), the scaffolder writes a minimal
+  presence-only stub with an explicit "authored zone" -- honest about being
+  unauthored, never a hand-written imitation of real content. Where a doc is
+  ``l0_stub_allowed: false`` (``readme``, ``license``, and the ``document``
+  archetype's ``document-index``), the scaffolder never invents content: it
+  references the file if the repo already has it at the conventional path,
+  and otherwise only *declares* the manifest entry, leaving the gap for a
+  human -- the CS-0.6 presence gate reports that gap as a WARN finding.
+* **Vendored schemas only.** All shapes come from ``consiliency_contract``
+  (the published shared contract package); nothing here re-implements or
+  copies schema literals.
+"""
+from __future__ import annotations
+
+import json
+import re
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from jsonschema import Draft202012Validator
+
+from .consiliency_layout import (
+    ARCHETYPE_IDS,
+    MODIFIER_IDS,
+    RequiredDocRow,
+    compose_required_documents,
+    consiliency_root,
+    contract_version_status_schema,
+    find_consiliency_manifest,
+    installed_contract_version,
+    interface_declaration_schema,
+    interfaces_path,
+    manifest_path,
+    manifest_schema,
+    status_path,
+)
+from .models import utc_now
+
+#: Docs the scaffolder generates as REAL minimal artifacts (not stubs) -- their
+#: content is true/current information (installed package version, an empty
+#: declared-edge set), never a placeholder standing in for unauthored prose.
+_MACHINE_REAL_IDS = ("contract-version-status", "interface-declaration")
+
+#: Well-known repo-root filenames for the handful of baseline docs that have
+#: an obvious conventional home. Everything else is scaffolded under
+#: `.consiliency/docs/<id>.md`, a namespace that can never collide with a
+#: repo's own doc layout.
+_ROOT_CONVENTION_PATHS: dict[str, str] = {
+    "readme": "README.md",
+    "license": "LICENSE",
+    "contributing": "CONTRIBUTING.md",
+    "changelog": "CHANGELOG.md",
+    "codeowners": "CODEOWNERS",
+}
+
+_SLUG_RE = re.compile(r"[^a-z0-9_.-]+")
+
+
+def _slugify(name: str) -> str:
+    slug = _SLUG_RE.sub("-", name.strip().lower()).strip("-.")
+    if not slug or not slug[0].isalnum():
+        slug = f"repo-{slug}" if slug else "repo"
+    return slug
+
+
+def _default_branch(repo: Path) -> str:
+    try:
+        ref = subprocess.check_output(
+            ["git", "-C", str(repo), "symbolic-ref", "--short", "HEAD"],
+            text=True,
+            stderr=subprocess.DEVNULL,
+        ).strip()
+        if ref:
+            return ref
+    except Exception:
+        pass
+    return "main"
+
+
+def _doc_target_path(row: RequiredDocRow) -> str:
+    if row.id in _MACHINE_REAL_IDS:
+        return f".consiliency/{'status.json' if row.id == 'contract-version-status' else 'interfaces.json'}"
+    if row.id in _ROOT_CONVENTION_PATHS:
+        return _ROOT_CONVENTION_PATHS[row.id]
+    return f".consiliency/docs/{row.id}.md"
+
+
+def _stub_body(row: RequiredDocRow) -> str:
+    title = row.id.replace("-", " ").title()
+    note = row.l0_note or (
+        f"This is an L0 presence-only stub. Its existence satisfies the Consiliency "
+        f"`{row.id}` document surface at maturity `presence-only` -- it declares that "
+        "this surface is tracked, not that its content has been authored."
+    )
+    if row.id == "codeowners":
+        return (
+            f"# Generated by: phase-loop consiliency-scaffold (doc-id={row.id}, maturity=presence-only)\n"
+            f"# {note}\n"
+            "# consiliency:authored-zone:start\n"
+            "# TODO: author real CODEOWNERS entries.\n"
+            "# consiliency:authored-zone:end\n"
+        )
+    return (
+        f"<!-- consiliency:generated-by=phase-loop consiliency-scaffold -->\n"
+        f"<!-- consiliency:doc-id={row.id} -->\n"
+        f"<!-- consiliency:maturity=presence-only -->\n\n"
+        f"# {title}\n\n"
+        f"{note}\n\n"
+        "<!-- consiliency:authored-zone:start -->\n"
+        "TODO: author this document's real content.\n"
+        "<!-- consiliency:authored-zone:end -->\n"
+    )
+
+
+@dataclass(frozen=True)
+class ScaffoldResult:
+    repo: Path
+    dry_run: bool
+    manifest_path: Path
+    manifest_written: bool
+    created_paths: tuple[str, ...]
+    referenced_paths: tuple[str, ...]
+    declared_missing_paths: tuple[str, ...]
+    already_present: bool
+
+    def to_json(self) -> dict[str, Any]:
+        return {
+            "repo": str(self.repo),
+            "dry_run": self.dry_run,
+            "manifest_path": str(self.manifest_path),
+            "manifest_written": self.manifest_written,
+            "created_paths": list(self.created_paths),
+            "referenced_paths": list(self.referenced_paths),
+            "declared_missing_paths": list(self.declared_missing_paths),
+            "already_present": self.already_present,
+        }
+
+
+class ScaffoldError(ValueError):
+    """Bad scaffold input (unknown archetype/modifier, baseline-only + archetypes, ...)."""
+
+
+def scaffold(
+    repo: str | Path,
+    *,
+    mode: str,
+    archetypes: tuple[str, ...] = (),
+    modifiers: tuple[str, ...] = (),
+    repo_id: str | None = None,
+    display_name: str | None = None,
+    dry_run: bool = False,
+) -> ScaffoldResult:
+    repo = Path(repo)
+    if mode not in ("baseline-only", "archetyped"):
+        raise ScaffoldError(f"invalid mode: {mode!r} (expected 'baseline-only' or 'archetyped')")
+    if mode == "baseline-only" and (archetypes or modifiers):
+        raise ScaffoldError("baseline-only mode does not accept --archetype/--modifier")
+    if mode == "archetyped" and not archetypes:
+        raise ScaffoldError("archetyped mode requires at least one --archetype")
+    unknown_archetypes = sorted(set(archetypes) - set(ARCHETYPE_IDS))
+    if unknown_archetypes:
+        raise ScaffoldError(f"unknown archetype(s): {unknown_archetypes}; known: {list(ARCHETYPE_IDS)}")
+    unknown_modifiers = sorted(set(modifiers) - set(MODIFIER_IDS))
+    if unknown_modifiers:
+        raise ScaffoldError(f"unknown modifier(s): {unknown_modifiers}; known: {list(MODIFIER_IDS)}")
+
+    existing_manifest = find_consiliency_manifest(repo)
+    already_present = existing_manifest is not None
+    target_manifest_path = manifest_path(repo)
+
+    rows = compose_required_documents(mode=mode, archetypes=archetypes, modifiers=modifiers)
+
+    created: list[str] = []
+    referenced: list[str] = []
+    declared_missing: list[str] = []
+    documents: list[dict[str, Any]] = []
+
+    for row in sorted(rows, key=lambda r: r.id):
+        rel_path = _doc_target_path(row)
+        abs_path = repo / rel_path
+        documents.append(
+            {
+                "id": row.id,
+                "class": row.doc_class,
+                "path": rel_path,
+                "maturity": "presence-only",
+                "target_level": "L0",
+                "required": row.required,
+            }
+        )
+        if abs_path.exists():
+            referenced.append(rel_path)
+            continue
+        if row.id in _MACHINE_REAL_IDS or row.l0_stub_allowed:
+            created.append(rel_path)
+            if not dry_run:
+                abs_path.parent.mkdir(parents=True, exist_ok=True)
+                if row.id == "contract-version-status":
+                    abs_path.write_text(
+                        json.dumps(_status_payload(), indent=2, sort_keys=True) + "\n", encoding="utf-8"
+                    )
+                elif row.id == "interface-declaration":
+                    abs_path.write_text(
+                        json.dumps(_interfaces_payload(repo_id or _slugify(repo.name)), indent=2, sort_keys=True) + "\n",
+                        encoding="utf-8",
+                    )
+                else:
+                    abs_path.write_text(_stub_body(row), encoding="utf-8")
+        else:
+            # l0_stub_allowed: false and nothing on disk -- do NOT fabricate.
+            # Declared in the manifest; the presence gate reports the gap.
+            declared_missing.append(rel_path)
+
+    manifest = {
+        "schema": "consiliency.manifest.v1",
+        "contract_version": installed_contract_version(),
+        "repo": {
+            "id": repo_id or _slugify(repo.name),
+            "display_name": display_name or repo.name,
+            "default_branch": _default_branch(repo),
+        },
+        "declaration": (
+            {"mode": "baseline-only"}
+            if mode == "baseline-only"
+            else {
+                "mode": "archetyped",
+                "archetypes": sorted(archetypes),
+                **({"modifiers": sorted(modifiers)} if modifiers else {}),
+            }
+        ),
+        "documents": documents,
+        "interfaces": ".consiliency/interfaces.json",
+    }
+    Draft202012Validator(manifest_schema()).validate(manifest)
+
+    manifest_written = False
+    if not already_present and not dry_run:
+        target_manifest_path.parent.mkdir(parents=True, exist_ok=True)
+        target_manifest_path.write_text(json.dumps(manifest, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+        manifest_written = True
+    elif not already_present:
+        manifest_written = True  # what WOULD be written, for dry-run reporting
+
+    return ScaffoldResult(
+        repo=repo,
+        dry_run=dry_run,
+        manifest_path=target_manifest_path,
+        manifest_written=manifest_written,
+        created_paths=tuple(created),
+        referenced_paths=tuple(referenced),
+        declared_missing_paths=tuple(declared_missing),
+        already_present=already_present,
+    )
+
+
+def _status_payload() -> dict[str, Any]:
+    version = installed_contract_version()
+    return {
+        "schema": "consiliency.contract_version_status.v1",
+        "package": {"name": "consiliency-contract", "version": version},
+        "repo_contract_version": version,
+        "compatibility": "compatible",
+        "maturity": "presence-only",
+        "checked_at": utc_now(),
+        "evidence": [],
+    }
+
+
+def _interfaces_payload(repo_id: str) -> dict[str, Any]:
+    return {
+        "schema": "consiliency.interface_declaration.v1",
+        "repo_id": repo_id,
+        "realized_edges": [],
+        "promised_edges": [],
+    }
+
+
+# Defensive self-checks -- the schemas ARE the contract; validate our own
+# generated shapes against them so a drift in this module fails loud in tests
+# rather than silently shipping a manifest the gates can't parse.
+def _validate_generated_artifacts(repo: Path) -> None:
+    status_file = status_path(repo)
+    if status_file.is_file():
+        Draft202012Validator(contract_version_status_schema()).validate(json.loads(status_file.read_text(encoding="utf-8")))
+    interfaces_file = interfaces_path(repo)
+    if interfaces_file.is_file():
+        Draft202012Validator(interface_declaration_schema()).validate(json.loads(interfaces_file.read_text(encoding="utf-8")))

phase_loop_runtime/cross_repo_channel.py

@@ -0,0 +1,331 @@
+"""Cross-repo consumption-channel descriptor and injection primitive.
+
+IF-0-P2-2 contract: every cross-repo dependency edge declares HOW the
+downstream workspace references the upstream — via a manifest-file version pin,
+a ``git submodule``, or a workspace/path override.  **NOT a git rebase**: two
+repos have unrelated git histories.
+
+The load-bearing primitive is :func:`set_upstream_ref`, which the coordinator
+calls (with the upstream draft branch ref in P3 and the upstream merged SHA in
+P4) **before** invoking the unchanged per-repo ``run_loop`` in the downstream
+workspace.  This is how an unchanged ``run_loop`` can consume the upstream at
+all.
+
+Channel kinds (closed set — no plugin system):
+
+``pin``
+    A manifest-file version pin: the executor rewrites a file the downstream
+    build ACTUALLY reads (e.g. ``requirements.txt``, ``package.json``, a
+    lockfile, a plain version file).
+
+    Two forms:
+      ``pin file=<path>``               — plain version/ref file: writes ``ref``
+                                          as the sole file content.
+      ``pin file=<path> key=<a.b.c>``  — JSON manifest: loads existing JSON,
+                                          sets the nested dotted key to ``ref``,
+                                          writes back with 2-space indent.
+
+    Required param: ``file`` (repo-relative path of the file to rewrite).
+    Optional param: ``key`` (dotted JSON key; absent → plain file).
+
+``submodule``
+    A ``git submodule``.  Params: ``path`` (submodule path relative to the
+    downstream workspace root).
+
+``workspace``
+    A workspace/path override (e.g. a ``[tool.uv.sources]`` workspace entry or
+    a Cargo workspace path dep).  Params: ``path`` (the override path).
+    **Rejected at train validation (T-E)**: workspace injection is not
+    implemented for real consumption and is rejected at preflight.
+
+``none``
+    No upstream dependency; declared explicitly for root nodes.
+
+Zero external deps (stdlib only).
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Callable, Dict, List, Literal, Optional
+
+# ---------------------------------------------------------------------------
+# Channel descriptor — IF-0-P2-2
+
+ChannelKind = Literal["pin", "submodule", "workspace", "none", "order-only"]
+
+VALID_CHANNEL_KINDS: frozenset[str] = frozenset(
+    {"pin", "submodule", "workspace", "none", "order-only"}
+)
+
+_NONE_VALUES = frozenset({"(none)", "none", ""})
+
+
+@dataclass(frozen=True)
+class ChannelDescriptor:
+    """Per-edge consumption-channel descriptor (IF-0-P2-2).
+
+    Attributes:
+        kind: One of ``pin``, ``submodule``, ``workspace``, or ``none``.
+        params: Kind-specific parameters (see module docstring).
+    """
+
+    kind: ChannelKind
+    params: Dict[str, str] = field(default_factory=dict, compare=True, hash=False)
+
+    def __hash__(self) -> int:
+        return hash((self.kind, tuple(sorted(self.params.items()))))
+
+    def __repr__(self) -> str:  # pragma: no cover
+        if self.kind == "none":
+            return "ChannelDescriptor(none)"
+        params_str = " ".join(f"{k}={v}" for k, v in sorted(self.params.items()))
+        return f"ChannelDescriptor({self.kind} {params_str})"
+
+
+# ---------------------------------------------------------------------------
+# Parser
+
+def parse_channel_line(raw: str) -> ChannelDescriptor:
+    """Parse a ``**Channel:**`` field value into a :class:`ChannelDescriptor`.
+
+    Accepted forms::
+
+        (none)                                         → ChannelDescriptor(kind="none")
+        submodule path=vendor/consiliency-portal
+        pin file=manifest.json                         → plain version/ref file
+        pin file=manifest.json key=deps.schema         → JSON manifest, dotted key
+        workspace path=../mylib
+
+    Raises :exc:`ValueError` on unrecognised channel kind or missing required params.
+    """
+    stripped = raw.strip()
+    if stripped.lower() in _NONE_VALUES:
+        return ChannelDescriptor(kind="none", params={})
+
+    parts = stripped.split()
+    kind = parts[0].lower()
+    if kind not in VALID_CHANNEL_KINDS or kind == "none":
+        raise ValueError(
+            f"unknown channel kind '{kind}'; expected one of: pin, submodule, "
+            f"workspace, order-only"
+        )
+
+    params: Dict[str, str] = {}
+    for token in parts[1:]:
+        if "=" in token:
+            k, _, v = token.partition("=")
+            params[k.strip()] = v.strip()
+        else:
+            raise ValueError(
+                f"channel param '{token}' has no '='; expected 'key=value' form"
+            )
+
+    _validate_params(kind, params, raw)  # type: ignore[arg-type]
+    return ChannelDescriptor(kind=kind, params=params)  # type: ignore[arg-type]
+
+
+def _validate_params(kind: ChannelKind, params: Dict[str, str], raw: str) -> None:
+    if kind == "pin":
+        if "file" not in params:
+            raise ValueError(
+                f"pin channel requires a 'file' param (the manifest file that gets "
+                f"rewritten with the upstream ref); got: {raw!r}"
+            )
+    elif kind in ("submodule", "workspace"):
+        if "path" not in params:
+            raise ValueError(
+                f"{kind} channel requires a 'path' param; got: {raw!r}"
+            )
+
+
+# ---------------------------------------------------------------------------
+# Injection primitive — IF-0-P2-2
+
+# The git/fs boundary is injectable for tests (stub it; never call real git in
+# unit tests).  The protocol is a callable:
+#   executor(workspace: Path, kind: ChannelKind, params: dict, ref: str) -> List[str]
+# The return value is the list of workspace-relative paths modified (for the
+# coordinator to union into the downstream's published owned_paths).
+
+ChannelExecutor = Callable[[Path, str, Dict[str, str], str], List[str]]
+
+
+def _assert_within_workspace(resolved: Path, workspace_resolved: Path, param: str) -> None:
+    """Fail loud if ``resolved`` escapes ``workspace_resolved``.
+
+    Raises :exc:`ValueError` if the resolved path is not strictly within the
+    workspace root (``../`` traversal or absolute path that escapes the tree).
+    """
+    try:
+        resolved.relative_to(workspace_resolved)
+    except ValueError:
+        raise ValueError(
+            f"channel param {param!r} resolves to {str(resolved)!r}, which is "
+            f"outside the workspace {str(workspace_resolved)!r}; "
+            f"refusing to read/write outside the workspace (path containment violation)"
+        )
+
+
+class UnsupportedChannelKind(ValueError):
+    """Raised by the live executor when a channel kind is valid in the schema but
+    not yet implemented for real consumption in this MVP.
+
+    Using a hollow sentinel file (written but never read by the downstream
+    build) would silently build the downstream against the absent upstream,
+    corrupting the whole train.  We fail loud instead.
+    """
+
+
+def _default_executor(
+    workspace: Path,
+    kind: str,
+    params: Dict[str, str],
+    ref: str,
+) -> List[str]:
+    """Default live executor — runs real git/fs operations.
+
+    Channel support:
+      ``submodule`` — git fetch + checkout; the downstream build ACTUALLY
+          consumes the injected ref (submodule HEAD is updated).
+      ``pin``       — rewrites the manifest file the downstream build reads:
+          - ``file`` only → writes ``ref`` as the plain file content (+ newline).
+          - ``file`` + ``key`` → loads existing JSON, sets the nested dotted key
+            to ``ref``, writes back with 2-space indent + trailing newline.
+          The downstream build reads the file directly, so injection is real.
+      ``workspace`` — NOT IMPLEMENTED for real consumption; raises
+          :exc:`UnsupportedChannelKind`.  Workspace edges are rejected at train
+          validation (T-E) before any executor is reached.
+
+    Returns the workspace-relative paths modified (for the coordinator to union
+    into the downstream's published owned_paths so pin/submodule changes always
+    ship in the PR even if run_loop's snapshot excludes them).
+
+    Hardening:
+      - Path containment: rejects ``file``/``path`` params that escape the
+        workspace root via ``../`` traversal or absolute paths.
+      - JSON key safety: rejects empty or malformed ``key`` params; raises when
+        a non-dict intermediate value would be silently overwritten.
+
+    Stubbing the executor (``_executor=stub``) is the correct approach for
+    tests that exercise workspace channel kinds (which remain unimplemented).
+    """
+    workspace_resolved = workspace.resolve()
+
+    if kind == "submodule":
+        submodule_path = params["path"]
+        # Path containment: reject ../- or absolute-escaping params.
+        resolved = (workspace / submodule_path).resolve()
+        _assert_within_workspace(resolved, workspace_resolved, submodule_path)
+        # Dereference the submodule to the given ref so the downstream build
+        # actually runs against the injected upstream content.
+        subprocess.run(
+            ["git", "fetch", "origin"],
+            cwd=workspace / submodule_path,
+            check=True,
+        )
+        subprocess.run(
+            ["git", "checkout", ref],
+            cwd=workspace / submodule_path,
+            check=True,
+        )
+        return [submodule_path]
+    elif kind == "pin":
+        file_param = params["file"]
+        file_path = workspace / file_param
+        # Path containment: reject ../- or absolute-escaping params.
+        resolved = file_path.resolve()
+        _assert_within_workspace(resolved, workspace_resolved, file_param)
+        key = params.get("key")
+        if key is not None:
+            # Validate the key: reject empty or malformed dotted paths.
+            if not key or not all(part for part in key.split(".")):
+                raise ValueError(
+                    f"pin 'key' param is empty or malformed: {key!r}; "
+                    f"expected a non-empty dotted path like 'deps.schema'"
+                )
+            # JSON manifest: load existing file (or start with empty dict), set
+            # the nested dotted key to ref, write back with consistent indent.
+            data: Dict = json.loads(file_path.read_text(encoding="utf-8")) if file_path.exists() else {}
+            keys = key.split(".")
+            node: Dict = data
+            for k in keys[:-1]:
+                if k not in node:
+                    node[k] = {}
+                elif not isinstance(node[k], dict):
+                    # Safety: raise rather than silently clobber a non-dict value.
+                    raise ValueError(
+                        f"cannot set dotted key {key!r}: intermediate key {k!r} "
+                        f"exists but is not a dict (got {type(node[k]).__name__!r}); "
+                        f"refusing to silently overwrite"
+                    )
+                node = node[k]
+            node[keys[-1]] = ref
+            file_path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+        else:
+            # Plain version/ref file: write ref as the sole content.
+            file_path.write_text(ref + "\n", encoding="utf-8")
+        return [file_param]
+    elif kind == "workspace":
+        raise UnsupportedChannelKind(
+            f"'workspace' channel injection is not implemented for real consumption "
+            f"(path={params.get('path')!r}). Workspace edges are rejected at train "
+            f"validation (T-E) before reaching the executor; a workspace channel in a "
+            f"live train means the train roadmap was not validated — check preflight."
+        )
+    elif kind == "order-only":
+        # #47: an order-only edge carries NO physical channel — the downstream does
+        # not consume the upstream artifact, so there is nothing to inject. The
+        # coordinator skips set_upstream_ref for order-only edges; reaching the
+        # executor here means a caller forgot to skip — fail loud, never no-op.
+        raise UnsupportedChannelKind(
+            "'order-only' edges carry no consumption channel and must never be "
+            "injected; the train coordinator skips set_upstream_ref for them "
+            "(they enforce merge order only)."
+        )
+    else:
+        raise ValueError(f"unknown channel kind for executor: {kind!r}")
+
+
+def set_upstream_ref(
+    workspace: Path,
+    channel: ChannelDescriptor,
+    ref: str,
+    *,
+    _executor: Optional[ChannelExecutor] = None,
+) -> List[str]:
+    """Re-resolve the downstream workspace's dependency channel to ``ref``.
+
+    This is the **load-bearing injection primitive** (IF-0-P2-2): the
+    coordinator calls this *before* invoking the unchanged per-repo
+    ``run_loop`` to point the downstream's consumption channel at a specific
+    upstream ref — the draft branch ``head_sha`` in P3 and the upstream
+    **merge SHA** in P4.
+
+    Returns the workspace-relative paths modified by the injection (e.g.
+    ``["manifest.json"]`` for a pin, ``["vendor/repo-a"]`` for a submodule).
+    The coordinator unions these into the downstream node's ``owned_paths``
+    before publishing so the pin/submodule change always ships in the PR even
+    if ``run_loop``'s snapshot excludes the injected file.
+
+    Args:
+        workspace: Absolute path to the downstream repo's worktree.
+        channel: The :class:`ChannelDescriptor` for this edge.
+        ref: The upstream ref or SHA to pin the channel to.
+        _executor: Optional injectable executor (for testing).  Defaults to
+            the live git/fs executor.
+
+    Raises:
+        ValueError: If the channel kind is ``none`` (root nodes have no
+            channel to re-resolve) or unknown.
+    """
+    if channel.kind == "none":
+        raise ValueError(
+            "set_upstream_ref called on a 'none' channel — root nodes have no "
+            "upstream dependency to resolve"
+        )
+    executor = _executor if _executor is not None else _default_executor
+    return executor(workspace, channel.kind, dict(channel.params), ref) or []