"""Workflow branch lineage and branch-scoped metadata helpers. The existing workflow model keeps a physical node copy per branch. This module adds a read-time lineage layer without replacing that storage model: locked copied ancestors resolve back to their immutable source node, while editable/regenerated branch nodes remain owned by their branch. """ from __future__ import annotations from copy import deepcopy from dataclasses import dataclass from typing import Any from backend.dto.common import ApiError, ErrorCode from backend.dto.workflow_dto import WorkflowBranch, WorkflowNode from database.repositories.workflow_repository import WorkflowRepository # Re-exported: the pure metadata transforms now live in core so the data layer # can use them without importing this module (which owns a WorkflowRepository). from core.branch_state import ( # noqa: F401 BRANCH_STATE_FIELDS, branch_state_for, with_branch_state, workflow_metadata_for_branch, ) from core.text_utils import optional_text as _optional_text EFFECTIVE_CONTEXT_STATUSES = frozenset({"completed", "selected", "skipped"}) @dataclass(frozen=True) class ResolvedNodeSource: """A logical branch node and the effective immutable source it reads.""" logical_node: WorkflowNode source_node: WorkflowNode inherited: bool source_branch: str source_node_id: str lineage: tuple[str, ...] class BranchLineageResolver: """Resolve effective node sources through ``base_branch_name`` ancestry.""" def __init__(self, workflow_repository: WorkflowRepository): self.workflow_repository = workflow_repository self._workflow_id: str | None = None self._branches: dict[str, WorkflowBranch] = {} self._nodes_by_branch: dict[str, list[WorkflowNode]] = {} self._nodes_by_id: dict[str, WorkflowNode] = {} def branch_chain(self, workflow_id: str, branch_name: str) -> tuple[str, ...]: self._load(workflow_id) current = str(branch_name or "main") chain: list[str] = [] seen: set[str] = set() while True: if current in seen: raise _lineage_error( "workflow branch parent cycle detected", workflow_id, branch_name, reason="workflow_branch_parent_cycle", lineage=chain + [current], ) seen.add(current) chain.append(current) if current == "main": return tuple(chain) branch = self._branches.get(current) if branch is None: raise _lineage_error( "workflow branch parent is missing", workflow_id, branch_name, reason="workflow_branch_parent_missing", missing_branch=current, lineage=chain, ) current = str(branch.base_branch_name or "main") def resolve_dependencies( self, target: WorkflowNode, *, include_draft: bool = False, ) -> list[ResolvedNodeSource]: """Resolve ordered logical dependencies for ``target``. Branch-local completed nodes win. A reset/missing node falls back to the nearest parent branch. Locked copied ancestors are unwrapped to the original immutable node so callers can explain the true source. """ self._load(target.workflow_id) local_nodes = self._nodes_by_branch.get(target.branch_name, []) dependencies: list[ResolvedNodeSource] = [] for logical in local_nodes: if logical.sort_order >= target.sort_order: continue resolved = self._resolve_stage( target.workflow_id, target.branch_name, logical, include_draft=include_draft, seen=set(), ) if resolved is not None: dependencies.append(resolved) return dependencies def resolve_parent_seed(self, target: WorkflowNode) -> ResolvedNodeSource | None: """Return the nearest confirmed ancestor value for an editable node.""" self._load(target.workflow_id) if target.branch_name == "main": return None branch = self._branches.get(target.branch_name) if branch is None: return None parent_name = str(branch.base_branch_name or "main") parent_logical = self._matching_node(parent_name, target) if parent_logical is None: return None return self._resolve_stage( target.workflow_id, parent_name, parent_logical, include_draft=False, seen=set(), logical_node=target, ) def _resolve_stage( self, workflow_id: str, branch_name: str, logical: WorkflowNode, *, include_draft: bool, seen: set[str], logical_node: WorkflowNode | None = None, ) -> ResolvedNodeSource | None: if branch_name in seen: raise _lineage_error( "workflow branch parent cycle detected", workflow_id, branch_name, reason="workflow_branch_parent_cycle", lineage=sorted(seen | {branch_name}), ) seen = {*seen, branch_name} local = self._matching_node(branch_name, logical) if local is not None and (include_draft or local.status in EFFECTIVE_CONTEXT_STATUSES): source, source_lineage = self._unwrap_locked_copy(local) display_logical = logical_node or logical lineage = _unique_lineage((display_logical.branch_name, *source_lineage, source.branch_name)) return ResolvedNodeSource( logical_node=display_logical, source_node=source, inherited=(source.node_id != display_logical.node_id or source.branch_name != display_logical.branch_name), source_branch=source.branch_name, source_node_id=source.node_id, lineage=lineage, ) if branch_name == "main": return None branch = self._branches.get(branch_name) if branch is None: raise _lineage_error( "workflow branch parent is missing", workflow_id, branch_name, reason="workflow_branch_parent_missing", missing_branch=branch_name, ) parent_name = str(branch.base_branch_name or "main") parent_logical = self._matching_node(parent_name, logical) if parent_logical is None: return None return self._resolve_stage( workflow_id, parent_name, parent_logical, include_draft=include_draft, seen=seen, logical_node=logical_node or logical, ) def _unwrap_locked_copy(self, node: WorkflowNode) -> tuple[WorkflowNode, tuple[str, ...]]: current = node lineage: list[str] = [current.branch_name] seen: set[str] = set() while True: metadata = current.metadata if isinstance(current.metadata, dict) else {} copied_from = _optional_text(metadata.get("copied_from_node_id")) if not copied_from or metadata.get("branch_locked_ancestor") is not True: return current, tuple(lineage) if copied_from in seen: raise _lineage_error( "workflow copied-node lineage cycle detected", current.workflow_id, node.branch_name, reason="workflow_node_lineage_cycle", node_id=node.node_id, ) seen.add(copied_from) source = self._nodes_by_id.get(copied_from) or self.workflow_repository.get_node(copied_from) if source is None: return current, tuple(lineage) current = source lineage.append(current.branch_name) def _matching_node(self, branch_name: str, reference: WorkflowNode) -> WorkflowNode | None: candidates = self._nodes_by_branch.get(branch_name, []) by_key = next((node for node in candidates if node.node_key == reference.node_key), None) if by_key is not None: return by_key return next((node for node in candidates if node.sort_order == reference.sort_order), None) def _load(self, workflow_id: str) -> None: if self._workflow_id == workflow_id: return self._workflow_id = workflow_id self._branches = { branch.branch_name: branch for branch in self.workflow_repository.list_branches(workflow_id) if branch.branch_name != "main" } nodes = self.workflow_repository.list_nodes(workflow_id) self._nodes_by_id = {node.node_id: node for node in nodes} self._nodes_by_branch = {} for node in nodes: self._nodes_by_branch.setdefault(node.branch_name, []).append(node) for branch_nodes in self._nodes_by_branch.values(): branch_nodes.sort(key=lambda item: (item.sort_order, item.created_at, item.node_id)) def activate_branch_state(metadata: dict[str, Any] | None, branch_name: str) -> dict[str, Any]: return with_branch_state(metadata, branch_name, {}, activate=True) def branch_state_patch(metadata: dict[str, Any] | None) -> dict[str, Any]: source = metadata if isinstance(metadata, dict) else {} return {key: deepcopy(source[key]) for key in BRANCH_STATE_FIELDS if key in source} def remap_branch_state_node_ids(value: Any, node_id_map: dict[str, str]) -> Any: """Deep-copy state while remapping node-id dictionary keys and values.""" if isinstance(value, dict): return { node_id_map.get(str(key), str(key)): remap_branch_state_node_ids(item, node_id_map) for key, item in value.items() } if isinstance(value, list): return [remap_branch_state_node_ids(item, node_id_map) for item in value] if isinstance(value, tuple): return [remap_branch_state_node_ids(item, node_id_map) for item in value] if isinstance(value, str): return node_id_map.get(value, value) return deepcopy(value) def _lineage_error(message: str, workflow_id: str, branch_name: str, **details: Any) -> ApiError: return ApiError( ErrorCode.VALIDATION_FAILED, message, {"workflow_id": workflow_id, "branch_name": branch_name, **details}, ) def _unique_lineage(values: tuple[str, ...]) -> tuple[str, ...]: result: list[str] = [] for value in values: text = str(value or "").strip() if text and (not result or result[-1] != text): result.append(text) return tuple(result)