813 lines
27 KiB
Python
813 lines
27 KiB
Python
"""Pure execution-policy resolvers for V3.8 chunk review.
|
|
|
|
This module deliberately owns no ComfyUI, torch, filesystem, Run Storage, or
|
|
sampling behavior. It turns already-validated storage facts into an execution
|
|
decision that later phases can apply to the existing Production engine.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
from collections.abc import Mapping
|
|
from dataclasses import dataclass
|
|
from typing import Any
|
|
|
|
from ..branch_provenance import TAKE_ACTION_CONTINUE, TAKE_ACTION_USE
|
|
|
|
|
|
GENERATION_MODE_FULL_RUN = "Full Run"
|
|
GENERATION_MODE_REVIEW = "Review Each Chunk"
|
|
GENERATION_MODE_OPTIONS = (
|
|
GENERATION_MODE_FULL_RUN,
|
|
GENERATION_MODE_REVIEW,
|
|
)
|
|
|
|
REVIEW_ACTION_CONTINUE = "Continue / Next"
|
|
REVIEW_ACTION_REGENERATE_CURRENT = "Regenerate Current"
|
|
REVIEW_ACTION_FINISH_REMAINING = "Finish Remaining"
|
|
REVIEW_ACTION_OPTIONS = (
|
|
REVIEW_ACTION_CONTINUE,
|
|
REVIEW_ACTION_REGENERATE_CURRENT,
|
|
REVIEW_ACTION_FINISH_REMAINING,
|
|
)
|
|
|
|
RUN_STORAGE_OFF = "Off"
|
|
RUN_STORAGE_SAVE_AUTO_RESUME = "Save + Auto Resume"
|
|
|
|
REVISION_STATUS_IN_PROGRESS = "in_progress"
|
|
REVISION_STATUS_INTERRUPTED = "interrupted"
|
|
REVISION_STATUS_REVIEW_READY = "review_ready"
|
|
REVISION_STATUS_COMPLETE = "complete"
|
|
REVISION_STATUSES = (
|
|
REVISION_STATUS_IN_PROGRESS,
|
|
REVISION_STATUS_INTERRUPTED,
|
|
REVISION_STATUS_REVIEW_READY,
|
|
REVISION_STATUS_COMPLETE,
|
|
)
|
|
|
|
EXECUTION_MODE_FULL_RUN = "full_run"
|
|
EXECUTION_MODE_REVIEW_CONTINUE = "review_continue"
|
|
EXECUTION_MODE_REVIEW_REGENERATE = "review_regenerate_current"
|
|
EXECUTION_MODE_REVIEW_FINISH = "review_finish_remaining"
|
|
EXECUTION_MODE_REVIEW_USE_TAKE = "review_use_take"
|
|
EXECUTION_MODE_REVIEW_CONTINUE_FROM_TAKE = "review_continue_from_take"
|
|
|
|
NONCE_POLICY_INACTIVE = "inactive"
|
|
NONCE_POLICY_INHERIT = "inherit_branch"
|
|
NONCE_POLICY_ADVANCE = "advance_variation"
|
|
NONCE_POLICY_MANUAL = "manual"
|
|
|
|
REVIEW_PAUSE_REASON = "review_each_chunk"
|
|
|
|
|
|
class ReviewControlError(ValueError):
|
|
"""Raised when a requested review policy is structurally ambiguous."""
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class ReviewUnit:
|
|
"""One atomic physical sampling group expressed in logical chunk numbers."""
|
|
|
|
start: int
|
|
end: int
|
|
physical_group: int
|
|
|
|
def as_metadata(self) -> dict[str, int]:
|
|
return {
|
|
"start": self.start,
|
|
"end": self.end,
|
|
"physical_group": self.physical_group,
|
|
}
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class ReviewExecution:
|
|
"""Side-effect-free decision consumed by later execution phases."""
|
|
|
|
execution_mode: str
|
|
requires_run_storage: bool
|
|
effective_regenerate_from: int
|
|
max_new_physical_groups: int | None
|
|
next_review_unit_start: int | None
|
|
next_review_unit_end: int | None
|
|
next_review_physical_group: int | None
|
|
finish_remaining: bool
|
|
smart_regenerate: bool
|
|
one_shot_reset_required: bool
|
|
partial_review: bool
|
|
projected_prefix_count: int
|
|
nonce_policy: str
|
|
branch_regenerate_from: int
|
|
base_effective_nonce: int
|
|
requested_effective_nonce: int | None
|
|
status_hint: str
|
|
|
|
|
|
def _integer(value: Any, *, name: str, minimum: int, maximum: int) -> int:
|
|
if isinstance(value, bool) or not isinstance(value, int):
|
|
raise ReviewControlError(f"{name} must be an integer")
|
|
if not minimum <= value <= maximum:
|
|
raise ReviewControlError(
|
|
f"{name} must be between {minimum} and {maximum}"
|
|
)
|
|
return value
|
|
|
|
|
|
def _manual_regenerate_from(value: Any, *, configured_chunks: int) -> int:
|
|
if value is None or value == "Auto" or value == 0:
|
|
return 0
|
|
if isinstance(value, str) and value.startswith("Chunk "):
|
|
try:
|
|
value = int(value[6:])
|
|
except ValueError as exc:
|
|
raise ReviewControlError(
|
|
"manual_regenerate_from must be Auto or a valid chunk"
|
|
) from exc
|
|
return _integer(
|
|
value,
|
|
name="manual_regenerate_from",
|
|
minimum=1,
|
|
maximum=configured_chunks,
|
|
)
|
|
|
|
|
|
def _terminal_pair_start(
|
|
*,
|
|
configured_chunks: int,
|
|
terminal_merge_enabled: bool,
|
|
terminal_pair_start: Any,
|
|
) -> int | None:
|
|
if type(terminal_merge_enabled) is not bool:
|
|
raise ReviewControlError("terminal_merge_enabled must be a boolean")
|
|
if not terminal_merge_enabled:
|
|
return None
|
|
if configured_chunks < 2:
|
|
raise ReviewControlError(
|
|
"Terminal Merge requires at least two configured chunks"
|
|
)
|
|
start = _integer(
|
|
terminal_pair_start,
|
|
name="terminal_pair_start",
|
|
minimum=1,
|
|
maximum=configured_chunks - 1,
|
|
)
|
|
if start != configured_chunks - 1:
|
|
raise ReviewControlError(
|
|
"Terminal Merge must cover the final two configured chunks"
|
|
)
|
|
return start
|
|
|
|
|
|
def _review_geometry(
|
|
*,
|
|
configured_chunks: Any,
|
|
validated_prefix_count: Any,
|
|
terminal_merge_enabled: bool,
|
|
terminal_pair_start: Any,
|
|
) -> tuple[int, int, int | None]:
|
|
chunks = _integer(
|
|
configured_chunks,
|
|
name="configured_chunks",
|
|
minimum=1,
|
|
maximum=0x7FFFFFFF,
|
|
)
|
|
prefix = _integer(
|
|
validated_prefix_count,
|
|
name="validated_prefix_count",
|
|
minimum=0,
|
|
maximum=chunks,
|
|
)
|
|
pair_start = _terminal_pair_start(
|
|
configured_chunks=chunks,
|
|
terminal_merge_enabled=terminal_merge_enabled,
|
|
terminal_pair_start=terminal_pair_start,
|
|
)
|
|
if pair_start is not None and pair_start <= prefix < chunks:
|
|
raise ReviewControlError(
|
|
"validated prefix ends inside the atomic Terminal Merge pair"
|
|
)
|
|
return chunks, prefix, pair_start
|
|
|
|
|
|
def resolve_next_review_unit(
|
|
*,
|
|
configured_chunks: int,
|
|
validated_prefix_count: int,
|
|
terminal_merge_enabled: bool,
|
|
terminal_pair_start: int | None,
|
|
) -> ReviewUnit | None:
|
|
"""Return the next atomic physical group after a validated logical prefix."""
|
|
|
|
chunks, prefix, pair_start = _review_geometry(
|
|
configured_chunks=configured_chunks,
|
|
validated_prefix_count=validated_prefix_count,
|
|
terminal_merge_enabled=terminal_merge_enabled,
|
|
terminal_pair_start=terminal_pair_start,
|
|
)
|
|
if prefix == chunks:
|
|
return None
|
|
start = prefix + 1
|
|
if pair_start is not None and start == pair_start:
|
|
return ReviewUnit(
|
|
start=pair_start,
|
|
end=chunks,
|
|
physical_group=pair_start,
|
|
)
|
|
return ReviewUnit(start=start, end=start, physical_group=start)
|
|
|
|
|
|
def _review_unit_for_chunk(
|
|
chunk: int,
|
|
*,
|
|
configured_chunks: int,
|
|
terminal_pair_start: int | None,
|
|
) -> ReviewUnit:
|
|
if terminal_pair_start is not None and chunk >= terminal_pair_start:
|
|
return ReviewUnit(
|
|
start=terminal_pair_start,
|
|
end=configured_chunks,
|
|
physical_group=terminal_pair_start,
|
|
)
|
|
return ReviewUnit(start=chunk, end=chunk, physical_group=chunk)
|
|
|
|
|
|
def _validated_review_unit(
|
|
value: Any,
|
|
*,
|
|
configured_chunks: int,
|
|
validated_prefix_count: int,
|
|
terminal_pair_start: int | None,
|
|
) -> ReviewUnit | None:
|
|
if value is None:
|
|
return None
|
|
if isinstance(value, ReviewUnit):
|
|
unit = value
|
|
elif isinstance(value, Mapping):
|
|
try:
|
|
unit = ReviewUnit(
|
|
start=value["start"],
|
|
end=value["end"],
|
|
physical_group=value["physical_group"],
|
|
)
|
|
except KeyError as exc:
|
|
raise ReviewControlError(
|
|
"latest_review_unit is missing required metadata"
|
|
) from exc
|
|
else:
|
|
raise ReviewControlError(
|
|
"latest_review_unit must be review metadata or None"
|
|
)
|
|
start = _integer(
|
|
unit.start,
|
|
name="latest_review_unit.start",
|
|
minimum=1,
|
|
maximum=configured_chunks,
|
|
)
|
|
end = _integer(
|
|
unit.end,
|
|
name="latest_review_unit.end",
|
|
minimum=start,
|
|
maximum=configured_chunks,
|
|
)
|
|
physical_group = _integer(
|
|
unit.physical_group,
|
|
name="latest_review_unit.physical_group",
|
|
minimum=1,
|
|
maximum=configured_chunks,
|
|
)
|
|
if physical_group != start:
|
|
raise ReviewControlError(
|
|
"latest_review_unit physical group must equal its first logical chunk"
|
|
)
|
|
if terminal_pair_start is not None and start == terminal_pair_start:
|
|
if end != configured_chunks:
|
|
raise ReviewControlError(
|
|
"latest_review_unit splits the atomic Terminal Merge pair"
|
|
)
|
|
elif end != start:
|
|
raise ReviewControlError(
|
|
"a non-terminal review unit must contain exactly one logical chunk"
|
|
)
|
|
if terminal_pair_start is not None and start > terminal_pair_start:
|
|
raise ReviewControlError(
|
|
"latest_review_unit starts inside the atomic Terminal Merge pair"
|
|
)
|
|
if end != validated_prefix_count:
|
|
raise ReviewControlError(
|
|
"latest_review_unit is not the head of the validated prefix"
|
|
)
|
|
return ReviewUnit(start=start, end=end, physical_group=physical_group)
|
|
|
|
|
|
def make_review_pause_metadata(review_unit: ReviewUnit) -> dict[str, Any]:
|
|
"""Build non-identity manifest metadata for a successful review pause."""
|
|
|
|
if not isinstance(review_unit, ReviewUnit):
|
|
raise ReviewControlError("review_unit must be a ReviewUnit")
|
|
start = _integer(
|
|
review_unit.start,
|
|
name="review_unit.start",
|
|
minimum=1,
|
|
maximum=0x7FFFFFFF,
|
|
)
|
|
end = _integer(
|
|
review_unit.end,
|
|
name="review_unit.end",
|
|
minimum=start,
|
|
maximum=0x7FFFFFFF,
|
|
)
|
|
physical_group = _integer(
|
|
review_unit.physical_group,
|
|
name="review_unit.physical_group",
|
|
minimum=1,
|
|
maximum=0x7FFFFFFF,
|
|
)
|
|
if physical_group != start:
|
|
raise ReviewControlError(
|
|
"review_unit physical group must equal its first logical chunk"
|
|
)
|
|
return {
|
|
"review_unit": {
|
|
"start": start,
|
|
"end": end,
|
|
"physical_group": physical_group,
|
|
},
|
|
"review_pause_reason": REVIEW_PAUSE_REASON,
|
|
}
|
|
|
|
|
|
def _revision_status(value: Any, *, prefix: int, chunks: int) -> str | None:
|
|
if value is None or value == "":
|
|
if prefix:
|
|
raise ReviewControlError(
|
|
"a non-empty validated prefix requires a revision status"
|
|
)
|
|
return None
|
|
status = str(value)
|
|
if status not in REVISION_STATUSES:
|
|
raise ReviewControlError(f"unknown latest revision status: {status!r}")
|
|
if status == REVISION_STATUS_COMPLETE and prefix != chunks:
|
|
raise ReviewControlError(
|
|
"a complete revision must contain every configured chunk"
|
|
)
|
|
if status == REVISION_STATUS_REVIEW_READY and not 0 < prefix < chunks:
|
|
raise ReviewControlError(
|
|
"review_ready requires a non-empty incomplete prefix"
|
|
)
|
|
return status
|
|
|
|
|
|
def _branch_contract(
|
|
*,
|
|
latest_effective_nonce: Any,
|
|
latest_branch_regenerate_from: Any,
|
|
validated_prefix_count: int,
|
|
configured_chunks: int,
|
|
latest_revision_status: str | None,
|
|
) -> tuple[int, int]:
|
|
nonce = _integer(
|
|
latest_effective_nonce,
|
|
name="latest_effective_nonce",
|
|
minimum=0,
|
|
maximum=0xFFFFFFFF,
|
|
)
|
|
branch_start = _manual_regenerate_from(
|
|
latest_branch_regenerate_from,
|
|
configured_chunks=configured_chunks,
|
|
)
|
|
if nonce == 0 and branch_start != 0:
|
|
raise ReviewControlError(
|
|
"a regenerate branch requires a positive effective nonce"
|
|
)
|
|
if nonce > 0 and branch_start == 0:
|
|
raise ReviewControlError(
|
|
"a positive effective nonce requires its regenerate branch boundary"
|
|
)
|
|
if branch_start > validated_prefix_count + 1:
|
|
raise ReviewControlError(
|
|
"regenerate branch boundary skips the validated prefix head"
|
|
)
|
|
if (
|
|
latest_revision_status
|
|
in (REVISION_STATUS_REVIEW_READY, REVISION_STATUS_COMPLETE)
|
|
and branch_start > validated_prefix_count
|
|
):
|
|
raise ReviewControlError(
|
|
"a ready regenerate branch has not committed its boundary chunk"
|
|
)
|
|
return nonce, branch_start
|
|
|
|
|
|
def validate_review_prefix_metadata(
|
|
*,
|
|
configured_chunks: int,
|
|
validated_prefix_count: int,
|
|
terminal_merge_enabled: bool,
|
|
terminal_pair_start: int | None,
|
|
latest_review_unit: ReviewUnit | Mapping[str, Any] | None,
|
|
latest_revision_status: str | None,
|
|
latest_effective_nonce: int,
|
|
latest_branch_regenerate_from: Any = 0,
|
|
) -> ReviewUnit | None:
|
|
"""Validate persisted Review metadata without creating an execution decision.
|
|
|
|
Repository reads and finalization use this boundary after raw prefix
|
|
validation. It deliberately returns no ``ReviewExecution`` so those paths
|
|
cannot become a second policy owner.
|
|
"""
|
|
|
|
chunks, prefix, pair_start = _review_geometry(
|
|
configured_chunks=configured_chunks,
|
|
validated_prefix_count=validated_prefix_count,
|
|
terminal_merge_enabled=terminal_merge_enabled,
|
|
terminal_pair_start=terminal_pair_start,
|
|
)
|
|
status = _revision_status(
|
|
latest_revision_status,
|
|
prefix=prefix,
|
|
chunks=chunks,
|
|
)
|
|
unit = _validated_review_unit(
|
|
latest_review_unit,
|
|
configured_chunks=chunks,
|
|
validated_prefix_count=prefix,
|
|
terminal_pair_start=pair_start,
|
|
)
|
|
_branch_contract(
|
|
latest_effective_nonce=latest_effective_nonce,
|
|
latest_branch_regenerate_from=latest_branch_regenerate_from,
|
|
validated_prefix_count=prefix,
|
|
configured_chunks=chunks,
|
|
latest_revision_status=status,
|
|
)
|
|
return unit
|
|
|
|
|
|
def _nonce_decision(
|
|
*,
|
|
manual_regenerate_from: int,
|
|
smart_regenerate: bool,
|
|
latest_effective_nonce: int,
|
|
latest_branch_regenerate_from: int,
|
|
smart_target: int = 0,
|
|
) -> tuple[str, int, int | None]:
|
|
if smart_regenerate:
|
|
if latest_effective_nonce >= 0xFFFFFFFF:
|
|
raise ReviewControlError(
|
|
"effective reroll nonce variation space is exhausted"
|
|
)
|
|
return (
|
|
NONCE_POLICY_ADVANCE,
|
|
smart_target,
|
|
latest_effective_nonce + 1,
|
|
)
|
|
if manual_regenerate_from:
|
|
return NONCE_POLICY_MANUAL, manual_regenerate_from, None
|
|
if latest_effective_nonce:
|
|
return (
|
|
NONCE_POLICY_INHERIT,
|
|
latest_branch_regenerate_from,
|
|
latest_effective_nonce,
|
|
)
|
|
return NONCE_POLICY_INACTIVE, 0, 0
|
|
|
|
|
|
def _unit_status(unit: ReviewUnit, *, chunks: int, verb: str) -> str:
|
|
if unit.start == unit.end:
|
|
return f"{verb}: Chunk {unit.start} / {chunks}."
|
|
return (
|
|
f"{verb}: Chunks {unit.start}-{unit.end} / {chunks}; "
|
|
"Terminal Merge atomic group."
|
|
)
|
|
|
|
|
|
def resolve_review_execution(
|
|
*,
|
|
generation_mode: str,
|
|
review_action: str,
|
|
configured_chunks: int,
|
|
validated_prefix_count: int,
|
|
terminal_merge_enabled: bool,
|
|
terminal_pair_start: int | None,
|
|
manual_regenerate_from: Any,
|
|
run_storage_mode: str,
|
|
latest_review_unit: ReviewUnit | Mapping[str, Any] | None,
|
|
latest_revision_status: str | None,
|
|
latest_effective_nonce: int,
|
|
latest_branch_regenerate_from: Any = 0,
|
|
) -> ReviewExecution:
|
|
"""Resolve V3.8 review intent without touching Production or storage state."""
|
|
|
|
if generation_mode not in GENERATION_MODE_OPTIONS:
|
|
raise ReviewControlError(f"unknown Generation Mode: {generation_mode!r}")
|
|
if review_action not in REVIEW_ACTION_OPTIONS:
|
|
raise ReviewControlError(f"unknown Review Action: {review_action!r}")
|
|
chunks, prefix, pair_start = _review_geometry(
|
|
configured_chunks=configured_chunks,
|
|
validated_prefix_count=validated_prefix_count,
|
|
terminal_merge_enabled=terminal_merge_enabled,
|
|
terminal_pair_start=terminal_pair_start,
|
|
)
|
|
status = _revision_status(
|
|
latest_revision_status,
|
|
prefix=prefix,
|
|
chunks=chunks,
|
|
)
|
|
manual_from = _manual_regenerate_from(
|
|
manual_regenerate_from,
|
|
configured_chunks=chunks,
|
|
)
|
|
nonce, existing_branch_start = _branch_contract(
|
|
latest_effective_nonce=latest_effective_nonce,
|
|
latest_branch_regenerate_from=latest_branch_regenerate_from,
|
|
validated_prefix_count=prefix,
|
|
configured_chunks=chunks,
|
|
latest_revision_status=status,
|
|
)
|
|
|
|
if generation_mode == GENERATION_MODE_FULL_RUN:
|
|
nonce_policy, branch_start, requested_nonce = _nonce_decision(
|
|
manual_regenerate_from=manual_from,
|
|
smart_regenerate=False,
|
|
latest_effective_nonce=nonce,
|
|
latest_branch_regenerate_from=existing_branch_start,
|
|
)
|
|
return ReviewExecution(
|
|
execution_mode=EXECUTION_MODE_FULL_RUN,
|
|
requires_run_storage=False,
|
|
effective_regenerate_from=(manual_from or branch_start),
|
|
max_new_physical_groups=None,
|
|
next_review_unit_start=None,
|
|
next_review_unit_end=None,
|
|
next_review_physical_group=None,
|
|
finish_remaining=False,
|
|
smart_regenerate=False,
|
|
one_shot_reset_required=False,
|
|
partial_review=False,
|
|
projected_prefix_count=chunks,
|
|
nonce_policy=nonce_policy,
|
|
branch_regenerate_from=branch_start,
|
|
base_effective_nonce=nonce,
|
|
requested_effective_nonce=requested_nonce,
|
|
status_hint="Full Run: Review execution limit disabled.",
|
|
)
|
|
|
|
if run_storage_mode != RUN_STORAGE_SAVE_AUTO_RESUME:
|
|
raise ReviewControlError(
|
|
"Review Each Chunk requires Run Storage = Save + Auto Resume."
|
|
)
|
|
|
|
latest_unit = _validated_review_unit(
|
|
latest_review_unit,
|
|
configured_chunks=chunks,
|
|
validated_prefix_count=prefix,
|
|
terminal_pair_start=pair_start,
|
|
)
|
|
|
|
if review_action == REVIEW_ACTION_REGENERATE_CURRENT:
|
|
if manual_from:
|
|
raise ReviewControlError(
|
|
"Regenerate Current cannot be combined with manual Regenerate From. "
|
|
"Set Regenerate From to Auto."
|
|
)
|
|
if prefix == 0:
|
|
raise ReviewControlError(
|
|
"Regenerate Current requires an existing reviewed unit"
|
|
)
|
|
if latest_unit is None:
|
|
raise ReviewControlError(
|
|
"Regenerate Current requires latest review_unit metadata"
|
|
)
|
|
if status not in (
|
|
REVISION_STATUS_REVIEW_READY,
|
|
REVISION_STATUS_COMPLETE,
|
|
):
|
|
raise ReviewControlError(
|
|
"Regenerate Current requires a review_ready revision or a complete "
|
|
"revision with review_unit metadata"
|
|
)
|
|
nonce_policy, branch_start, requested_nonce = _nonce_decision(
|
|
manual_regenerate_from=0,
|
|
smart_regenerate=True,
|
|
latest_effective_nonce=nonce,
|
|
latest_branch_regenerate_from=existing_branch_start,
|
|
smart_target=latest_unit.start,
|
|
)
|
|
projected = latest_unit.end
|
|
return ReviewExecution(
|
|
execution_mode=EXECUTION_MODE_REVIEW_REGENERATE,
|
|
requires_run_storage=True,
|
|
effective_regenerate_from=latest_unit.start,
|
|
max_new_physical_groups=1,
|
|
next_review_unit_start=latest_unit.start,
|
|
next_review_unit_end=latest_unit.end,
|
|
next_review_physical_group=latest_unit.physical_group,
|
|
finish_remaining=False,
|
|
smart_regenerate=True,
|
|
one_shot_reset_required=True,
|
|
partial_review=projected < chunks,
|
|
projected_prefix_count=projected,
|
|
nonce_policy=nonce_policy,
|
|
branch_regenerate_from=branch_start,
|
|
base_effective_nonce=nonce,
|
|
requested_effective_nonce=requested_nonce,
|
|
status_hint=_unit_status(
|
|
latest_unit,
|
|
chunks=chunks,
|
|
verb="Smart Regenerate",
|
|
),
|
|
)
|
|
|
|
nonce_policy, branch_start, requested_nonce = _nonce_decision(
|
|
manual_regenerate_from=manual_from,
|
|
smart_regenerate=False,
|
|
latest_effective_nonce=nonce,
|
|
latest_branch_regenerate_from=existing_branch_start,
|
|
)
|
|
if review_action == REVIEW_ACTION_FINISH_REMAINING:
|
|
return ReviewExecution(
|
|
execution_mode=EXECUTION_MODE_REVIEW_FINISH,
|
|
requires_run_storage=True,
|
|
effective_regenerate_from=(manual_from or branch_start),
|
|
max_new_physical_groups=None,
|
|
next_review_unit_start=None,
|
|
next_review_unit_end=None,
|
|
next_review_physical_group=None,
|
|
finish_remaining=True,
|
|
smart_regenerate=False,
|
|
one_shot_reset_required=True,
|
|
partial_review=False,
|
|
projected_prefix_count=chunks,
|
|
nonce_policy=nonce_policy,
|
|
branch_regenerate_from=branch_start,
|
|
base_effective_nonce=nonce,
|
|
requested_effective_nonce=requested_nonce,
|
|
status_hint=(
|
|
f"Review Mode: finish remaining after accepted prefix "
|
|
f"{prefix} / {chunks}."
|
|
),
|
|
)
|
|
|
|
if manual_from:
|
|
next_unit = _review_unit_for_chunk(
|
|
manual_from,
|
|
configured_chunks=chunks,
|
|
terminal_pair_start=pair_start,
|
|
)
|
|
else:
|
|
next_unit = resolve_next_review_unit(
|
|
configured_chunks=chunks,
|
|
validated_prefix_count=prefix,
|
|
terminal_merge_enabled=terminal_merge_enabled,
|
|
terminal_pair_start=pair_start,
|
|
)
|
|
if next_unit is None:
|
|
projected = chunks
|
|
status_hint = "Review Mode: Sequence complete."
|
|
unit_start = unit_end = physical_group = None
|
|
else:
|
|
projected = next_unit.end
|
|
status_hint = _unit_status(
|
|
next_unit,
|
|
chunks=chunks,
|
|
verb="Review next unit",
|
|
)
|
|
unit_start = next_unit.start
|
|
unit_end = next_unit.end
|
|
physical_group = next_unit.physical_group
|
|
return ReviewExecution(
|
|
execution_mode=EXECUTION_MODE_REVIEW_CONTINUE,
|
|
requires_run_storage=True,
|
|
effective_regenerate_from=(manual_from or branch_start),
|
|
max_new_physical_groups=1,
|
|
next_review_unit_start=unit_start,
|
|
next_review_unit_end=unit_end,
|
|
next_review_physical_group=physical_group,
|
|
finish_remaining=False,
|
|
smart_regenerate=False,
|
|
one_shot_reset_required=False,
|
|
partial_review=projected < chunks,
|
|
projected_prefix_count=projected,
|
|
nonce_policy=nonce_policy,
|
|
branch_regenerate_from=branch_start,
|
|
base_effective_nonce=nonce,
|
|
requested_effective_nonce=requested_nonce,
|
|
status_hint=status_hint,
|
|
)
|
|
|
|
|
|
def resolve_take_execution(
|
|
*,
|
|
take_action: str,
|
|
configured_chunks: int,
|
|
selected_prefix_count: int,
|
|
terminal_merge_enabled: bool,
|
|
terminal_pair_start: int | None,
|
|
selected_review_unit: ReviewUnit | Mapping[str, Any],
|
|
selected_effective_nonce: int,
|
|
selected_branch_regenerate_from: int,
|
|
next_effective_nonce: int,
|
|
) -> ReviewExecution:
|
|
"""Resolve an already-validated immutable Take selection.
|
|
|
|
The selected prefix is a Run Storage fact. Continuing from it starts a
|
|
fresh downstream nonce boundary without changing the Sampling Contract.
|
|
"""
|
|
|
|
if take_action not in (TAKE_ACTION_USE, TAKE_ACTION_CONTINUE):
|
|
raise ReviewControlError(f"unknown Take action: {take_action!r}")
|
|
chunks, prefix, pair_start = _review_geometry(
|
|
configured_chunks=configured_chunks,
|
|
validated_prefix_count=selected_prefix_count,
|
|
terminal_merge_enabled=terminal_merge_enabled,
|
|
terminal_pair_start=terminal_pair_start,
|
|
)
|
|
unit = _validated_review_unit(
|
|
selected_review_unit,
|
|
configured_chunks=chunks,
|
|
validated_prefix_count=prefix,
|
|
terminal_pair_start=pair_start,
|
|
)
|
|
if unit is None:
|
|
raise ReviewControlError("selected Take is missing its physical review unit")
|
|
selected_nonce, selected_branch = _branch_contract(
|
|
latest_effective_nonce=selected_effective_nonce,
|
|
latest_branch_regenerate_from=selected_branch_regenerate_from,
|
|
validated_prefix_count=prefix,
|
|
configured_chunks=chunks,
|
|
latest_revision_status=(
|
|
REVISION_STATUS_COMPLETE if prefix == chunks else REVISION_STATUS_REVIEW_READY
|
|
),
|
|
)
|
|
if take_action == TAKE_ACTION_USE:
|
|
return ReviewExecution(
|
|
execution_mode=EXECUTION_MODE_REVIEW_USE_TAKE,
|
|
requires_run_storage=True,
|
|
effective_regenerate_from=selected_branch,
|
|
max_new_physical_groups=0,
|
|
next_review_unit_start=None,
|
|
next_review_unit_end=None,
|
|
next_review_physical_group=None,
|
|
finish_remaining=False,
|
|
smart_regenerate=False,
|
|
one_shot_reset_required=True,
|
|
partial_review=prefix < chunks,
|
|
projected_prefix_count=prefix,
|
|
nonce_policy=NONCE_POLICY_INHERIT if selected_nonce else NONCE_POLICY_INACTIVE,
|
|
branch_regenerate_from=selected_branch,
|
|
base_effective_nonce=selected_nonce,
|
|
requested_effective_nonce=selected_nonce,
|
|
status_hint=_unit_status(unit, chunks=chunks, verb="Use This Take"),
|
|
)
|
|
|
|
next_unit = resolve_next_review_unit(
|
|
configured_chunks=chunks,
|
|
validated_prefix_count=prefix,
|
|
terminal_merge_enabled=terminal_merge_enabled,
|
|
terminal_pair_start=pair_start,
|
|
)
|
|
if next_unit is None:
|
|
return ReviewExecution(
|
|
execution_mode=EXECUTION_MODE_REVIEW_USE_TAKE,
|
|
requires_run_storage=True,
|
|
effective_regenerate_from=selected_branch,
|
|
max_new_physical_groups=0,
|
|
next_review_unit_start=None,
|
|
next_review_unit_end=None,
|
|
next_review_physical_group=None,
|
|
finish_remaining=False,
|
|
smart_regenerate=False,
|
|
one_shot_reset_required=True,
|
|
partial_review=False,
|
|
projected_prefix_count=chunks,
|
|
nonce_policy=NONCE_POLICY_INHERIT if selected_nonce else NONCE_POLICY_INACTIVE,
|
|
branch_regenerate_from=selected_branch,
|
|
base_effective_nonce=selected_nonce,
|
|
requested_effective_nonce=selected_nonce,
|
|
status_hint="Continue From Here: selected Take is already complete.",
|
|
)
|
|
nonce = _integer(
|
|
next_effective_nonce,
|
|
name="next_effective_nonce",
|
|
minimum=1,
|
|
maximum=0xFFFFFFFF,
|
|
)
|
|
return ReviewExecution(
|
|
execution_mode=EXECUTION_MODE_REVIEW_CONTINUE_FROM_TAKE,
|
|
requires_run_storage=True,
|
|
effective_regenerate_from=next_unit.start,
|
|
max_new_physical_groups=1,
|
|
next_review_unit_start=next_unit.start,
|
|
next_review_unit_end=next_unit.end,
|
|
next_review_physical_group=next_unit.physical_group,
|
|
finish_remaining=False,
|
|
smart_regenerate=False,
|
|
one_shot_reset_required=True,
|
|
partial_review=next_unit.end < chunks,
|
|
projected_prefix_count=next_unit.end,
|
|
nonce_policy=NONCE_POLICY_ADVANCE,
|
|
branch_regenerate_from=next_unit.start,
|
|
base_effective_nonce=selected_nonce,
|
|
requested_effective_nonce=nonce,
|
|
status_hint=_unit_status(next_unit, chunks=chunks, verb="Continue From Here"),
|
|
)
|