astrbot_plugin_imagestudio/backend/services/branch_lineage_service.py

285 行
11 KiB
Python

"""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)