356 行
13 KiB
Python
356 行
13 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
|
|
|
|
|
|
BRANCH_STATE_FIELDS = frozenset(
|
|
{
|
|
"character_execution",
|
|
"material_binding_schema_version",
|
|
"material_binding_source_node_id",
|
|
"material_binding_updated_at",
|
|
"material_bindings",
|
|
"prompt_plan_schema_version",
|
|
"prompt_plan_source_node_id",
|
|
"prompt_plan_updated_at",
|
|
"prompt_plan",
|
|
"prompt_matrix",
|
|
"stage_input_schema_version",
|
|
"stage_inputs",
|
|
"restoration_input_schema_version",
|
|
"restoration_inputs",
|
|
"stage_review_handoffs",
|
|
"last_stage_review_confirmed_at",
|
|
"last_stage_review_node_id",
|
|
"last_stage_review_image_id",
|
|
"current_stage_input_image_id",
|
|
"final_archive_schema_version",
|
|
"final_archive_history_id",
|
|
"final_archive_image_ids",
|
|
"final_archive_node_id",
|
|
"final_archive_source_node_id",
|
|
"final_archive_completed_at",
|
|
}
|
|
)
|
|
|
|
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 branch_state_for(metadata: dict[str, Any] | None, branch_name: str) -> dict[str, Any]:
|
|
"""Read branch state with a root-metadata fallback for pre-1.0.16 data."""
|
|
|
|
source = metadata if isinstance(metadata, dict) else {}
|
|
branch_states = source.get("branch_state")
|
|
if isinstance(branch_states, dict) and isinstance(branch_states.get(branch_name), dict):
|
|
return deepcopy(branch_states[branch_name])
|
|
return {
|
|
key: deepcopy(source[key])
|
|
for key in BRANCH_STATE_FIELDS
|
|
if key in source
|
|
}
|
|
|
|
|
|
def workflow_metadata_for_branch(metadata: dict[str, Any] | None, branch_name: str) -> dict[str, Any]:
|
|
"""Return the legacy root projection overlaid with one branch's state."""
|
|
|
|
result = deepcopy(metadata) if isinstance(metadata, dict) else {}
|
|
state = branch_state_for(result, branch_name)
|
|
for key in BRANCH_STATE_FIELDS:
|
|
result.pop(key, None)
|
|
result.update(state)
|
|
return result
|
|
|
|
|
|
def with_branch_state(
|
|
metadata: dict[str, Any] | None,
|
|
branch_name: str,
|
|
patch: dict[str, Any],
|
|
*,
|
|
activate: bool,
|
|
) -> dict[str, Any]:
|
|
"""Merge one branch state while preserving every sibling branch."""
|
|
|
|
result = deepcopy(metadata) if isinstance(metadata, dict) else {}
|
|
states = deepcopy(result.get("branch_state")) if isinstance(result.get("branch_state"), dict) else {}
|
|
state = branch_state_for(result, branch_name)
|
|
state.update({key: deepcopy(value) for key, value in patch.items() if key in BRANCH_STATE_FIELDS})
|
|
states[branch_name] = state
|
|
result["branch_state"] = states
|
|
if activate:
|
|
for key in BRANCH_STATE_FIELDS:
|
|
result.pop(key, None)
|
|
result.update(deepcopy(state))
|
|
return result
|
|
|
|
|
|
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 _optional_text(value: Any) -> str | None:
|
|
if value is None:
|
|
return None
|
|
text = str(value).strip()
|
|
return text or None
|
|
|
|
|
|
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)
|