fix: stabilize V3.9 and bump package to 3.9.1

Preserve Second Pass audio and scoped Review conditioning, strengthen Take compatibility, and align Review Driving Audio.

Keep v5 history readable, document v6 restart requirements, and describe the fixes at the top of both READMEs. Remove workstation-specific paths and private operational records from public documentation.
This commit is contained in:
ukr8b3g-cmyk
2026-10-04 19:05:33 +09:00
parent b88c5b4d97
commit 190141e03e
45 changed files with 2211 additions and 4267 deletions
+6 -2
View File
@@ -37,7 +37,7 @@ from .file_backed_buffer import (
format_auto_buffer_decision,
select_auto_buffer_backend,
)
from .plan import FPS, validate_assembly_plan
from .plan import FPS, validate_assembly_plan, REVIEW_AUDIO_PROJECTION_KEY
_COPY_BATCH_FRAMES = 8
@@ -526,7 +526,9 @@ def _write_assembly(
driving_audio_report = ""
if final_audio_override is not None:
result_audio = dict(final_audio_override)
if exact_total_duration:
override_waveform, _ = validate_audio(result_audio)
empty_review = (REVIEW_AUDIO_PROJECTION_KEY in plan and int(override_waveform.shape[-1]) == 0)
if exact_total_duration or empty_review:
result_audio, _ = adjust_audio_duration_direct(
result_audio,
target_frames=output_frames,
@@ -543,6 +545,8 @@ def _write_assembly(
f"sample_rate={int(selected_rate)}, samples={int(waveform.shape[-1])}; "
"generated audio and Audio Seam bypassed."
)
if empty_review:
driving_audio_report += " Empty Review interval: silence added for the selected video duration."
reports.append(
f"Assembled {len(units)} physical decoded group(s) into "
+17 -2
View File
@@ -16,7 +16,7 @@ from ..constants import (
normalize_continuity_mode,
normalize_diagnostics_mode,
)
from ..driving_audio import prepare_driving_audio_source
from ..driving_audio import prepare_driving_audio_source, slice_review_source_audio
from ..guide_timeline import (
GUIDE_TYPE,
make_still_image_guide,
@@ -854,6 +854,20 @@ class H3ContinuumSamplerV39(H3ContinuumSamplerV38):
plan = outputs[2].get("reference_routing_v1")
if not isinstance(plan, dict):
raise RuntimeError("V3.9 Reference Routing has no verified output Plan")
if len(outputs) == 6 and isinstance(outputs[5], dict):
from .refine_context import MAGIC, OUTPUT_SCOPE_KEY, project_refine_context
if outputs[5].get("magic") == MAGIC:
context = project_refine_context(outputs[5], outputs[2])
if context is not outputs[5]:
status = outputs[3]
if context.get(OUTPUT_SCOPE_KEY) is not None:
from .nodes import _PARTIAL_REVIEW_SECOND_PASS_WARNING
status = str(status).replace(
_PARTIAL_REVIEW_SECOND_PASS_WARNING,
"Second Pass: output-scope conditioning verified; "
"the full sequence may still be incomplete.",
)
outputs = (*outputs[:3], status, outputs[4], context)
return {
"ui": {"h3_reference_plan": [format_reference_plan(plan)]},
"result": outputs,
@@ -1102,7 +1116,8 @@ class H3ContinuumAssembleSeamV35(H3ContinuumAssembleSeamV34):
backend = str(_singleton(buffer_backend, "buffer_backend"))
diagnostics_mode = str(_singleton(diagnostics, "diagnostics"))
preserved_audio = _copy_audio(plan.get(_DRIVING_AUDIO_PLAN_KEY))
selected_audio = preserved_audio or _copy_audio(driving_audio)
selected_audio = preserved_audio or _copy_audio(driving_audio)
selected_audio = slice_review_source_audio(selected_audio, plan)
selected_audio_source = None
if selected_audio is not None:
selected_audio_source = (
+5 -1
View File
@@ -23,7 +23,7 @@ from ..v2.nodes import (
validate_sparse_prompt_overrides,
)
from .assembly import H3ContinuumAssembleSeamExperimental, H3ContinuumAssembleV3
from .plan import make_assembly_plan
from .plan import make_assembly_plan, make_review_audio_projection, REVIEW_AUDIO_PROJECTION_KEY
from .execution_planner import (
PROJECTION_CURRENT_REVIEW_UNIT,
PROJECTION_FULL_ACCEPTED_PREFIX,
@@ -188,6 +188,9 @@ def _apply_review_decode_scope(
return outputs
start = int(decision.start_chunk)
end = int(decision.end_chunk)
audio_projection = make_review_audio_projection(
assembly_plan, start_chunk=start, end_chunk=end,
)
selected_entries = entries[start - 1 : end]
sequence_complete = len(entries) == int(configured_chunks)
@@ -220,6 +223,7 @@ def _apply_review_decode_scope(
terminal_merged=selected_terminal_merged,
terminal_initial_pair=(start == 1),
)
scoped_plan[REVIEW_AUDIO_PROJECTION_KEY] = audio_projection
# Projection narrows the AV decode view, not the already-verified routing
# decision. Keep that Queue-local plan available to the public Inspector.
route_plan = assembly_plan.get("reference_routing_v1")
+61 -4
View File
@@ -12,6 +12,7 @@ ASSEMBLY_PLAN_MAGIC = "H3_CONTINUUM_ASSEMBLY_PLAN"
ASSEMBLY_PLAN_SCHEMA_VERSION = 1
FPS = 24
SECOND_PASS_CONTRACT_VERSION = 1
REVIEW_AUDIO_PROJECTION_KEY = "review_audio_projection_v1"
class AssemblyPlanError(ValueError):
@@ -131,10 +132,66 @@ _make_assembly_plan_v300 = make_assembly_plan
_validate_assembly_plan_v300 = validate_assembly_plan
def validate_assembly_plan(plan):
result = _validate_assembly_plan_v300(plan)
_validate_assembly_plan_contract(plan)
return result
def validate_assembly_plan(plan):
result = _validate_assembly_plan_v300(plan)
_validate_assembly_plan_contract(plan)
validate_review_audio_projection(plan)
return result
def validate_review_audio_projection(plan):
"""Check a scoped PCM coordinate without recomputing its absolute origin."""
if REVIEW_AUDIO_PROJECTION_KEY not in plan:
return None
metadata = plan[REVIEW_AUDIO_PROJECTION_KEY]
if not isinstance(metadata, dict):
raise AssemblyPlanError("Review audio projection must be a dictionary")
if (type(metadata.get("version")) is not int or metadata.get("version") != 1 or metadata.get("kind") != "current_review_unit"
or metadata.get("coordinate_space") != "full_source_pcm"):
raise AssemblyPlanError("Review audio projection version or coordinate space is invalid")
for field in ("fps", "start_chunk", "end_chunk", "source_start_frame", "source_stop_frame"):
if type(metadata.get(field)) is not int:
raise AssemblyPlanError(f"Review audio projection {field} must be an integer")
if metadata["fps"] != FPS or int(plan.get("fps", 0)) != FPS:
raise AssemblyPlanError("Review audio projection FPS must be 24")
start, end = metadata["start_chunk"], metadata["end_chunk"]
first, stop = metadata["source_start_frame"], metadata["source_stop_frame"]
chunks = [int(chunk["chunk_index"]) for chunk in plan["chunks"]]
units = plan.get("decode_groups") or plan["chunks"]
if (start < 1 or end < start or len(chunks) != end - start + 1
or any(index != start + position for position, index in enumerate(chunks))
or first < 0 or stop <= first
or stop - first != sum(int(unit["net_frames"]) for unit in units)):
raise AssemblyPlanError("Review audio projection physical range is inconsistent")
return metadata
def make_review_audio_projection(plan, *, start_chunk: int, end_chunk: int):
"""Read natural retained ranges before narrowing the accepted decode view."""
validate_assembly_plan(plan)
if REVIEW_AUDIO_PROJECTION_KEY in plan:
raise AssemblyPlanError("Review output cannot be projected twice")
start, end = int(start_chunk), int(end_chunk)
selected = []
covered = []
for unit in plan.get("decode_groups") or plan["chunks"]:
indices = unit.get("logical_chunk_indices") or [unit["chunk_index"]]
if not any(start <= int(index) <= end for index in indices):
continue
if not all(start <= int(index) <= end for index in indices):
raise AssemblyPlanError("Review audio projection cannot split a physical group")
first, stop = unit.get("frame_start"), unit.get("frame_stop")
if type(first) is not int or type(stop) is not int or stop - first != int(unit["net_frames"]):
raise AssemblyPlanError("Review audio projection needs retained natural frame ranges")
if selected and selected[-1][1] != first:
raise AssemblyPlanError("Review audio projection ranges are not contiguous")
selected.append((first, stop))
covered.extend(int(index) for index in indices)
if not selected or covered != list(range(start, end + 1)):
raise AssemblyPlanError("Review audio projection is outside the accepted sequence")
return dict(version=1, kind="current_review_unit", coordinate_space="full_source_pcm",
fps=FPS, start_chunk=start, end_chunk=end,
source_start_frame=selected[0][0], source_stop_frame=selected[-1][1])
def make_assembly_plan(*args, **kwargs):
+75 -2
View File
@@ -21,6 +21,7 @@ from ..guide_timeline import MARK_STILL_IMAGE_GUIDE
MAGIC = "H3_CONTINUUM_REFINE_CONTEXT"
VERSION = 1
OUTPUT_SCOPE_KEY = "output_scope_v1"
class RefineContextError(ValueError):
@@ -251,6 +252,49 @@ def _group_field_tuple(group: Mapping[str, Any], name: str) -> tuple[int, ...]:
) from exc
def project_refine_context(context: dict[str, Any], assembly_plan: Mapping[str, Any]):
"""Bind a V3.9 runtime-only view to complete physical output groups.
Sequence completion and saved history are unchanged. A partial capture may
serve a smaller decode view only after the ordinary complete-group checks
pass, including the frozen Reference route. Missing or mismatched partial
evidence retains the legacy diagnostic fallback, never guessed conditions.
"""
validate_refine_context(context)
contract = assembly_plan.get("second_pass_contract")
planned = contract.get("physical_groups") if isinstance(contract, Mapping) else None
if not isinstance(planned, list) or not planned:
return context
source = context["groups"]
keys = [tuple(group["logical_chunks"]) for group in source]
targets = [tuple(group.get("logical_chunks", ())) for group in planned]
if context["complete"] and keys == targets:
return validate_refine_context(context, assembly_plan=assembly_plan)
if len(set(keys)) != len(keys) or len(set(targets)) != len(targets):
return context
lookup = dict(zip(keys, source))
if any(key not in lookup for key in targets):
return context
selected = [lookup[key] for key in targets]
view = dict(context)
view["groups"] = tuple(
{**group, "group_id": index} for index, group in enumerate(selected)
)
view[OUTPUT_SCOPE_KEY] = MappingProxyType({
"version": 1,
"source_group_ids": tuple(group["group_id"] for group in selected),
})
try:
validate_refine_context(view, assembly_plan=assembly_plan)
except RefineContextError as exc:
# These groups were previously optional/incomplete. Do not add a new
# execution stop for unavailable output-scope evidence.
fallback = dict(context)
fallback["notes"] = (*context["notes"], f"Output scope unavailable: {exc}")
return fallback
return view
def validate_refine_context(
context: Any, assembly_plan: Mapping[str, Any] | None = None
) -> dict[str, Any]:
@@ -278,6 +322,14 @@ def validate_refine_context(
notes = context.get("notes")
if not isinstance(notes, tuple) or any(not isinstance(note, str) for note in notes):
raise RefineContextError("refine context notes must be an immutable string tuple")
scope = context.get(OUTPUT_SCOPE_KEY)
if scope is not None:
ids = scope.get("source_group_ids") if isinstance(scope, Mapping) else None
if (not isinstance(scope, Mapping) or scope.get("version") != 1
or not isinstance(ids, tuple) or len(ids) != len(groups)
or any(type(value) is not int or value < 0 for value in ids)
or tuple(sorted(set(ids))) != ids or not groups):
raise RefineContextError("refine context output scope is invalid")
previous_clip_index = 0
for expected_id, group in enumerate(groups):
@@ -345,9 +397,9 @@ def validate_refine_context(
# Its local group ids describe capture order, not Assembly Plan position;
# validating those partial entries by index would incorrectly turn the
# intended prompt-only fallback into a broken typed-contract hard error.
if not context["complete"]:
if not context["complete"] and scope is None:
return context
if context["complete"] and len(plan_groups) != len(groups):
if len(plan_groups) != len(groups):
raise RefineContextError(
"complete refine context physical-group count differs from assembly plan"
)
@@ -365,6 +417,15 @@ def validate_refine_context(
view_groups[group_id] if isinstance(view_groups, list)
and group_id < len(view_groups) else None
)
if scope is not None:
# Inspector retains the full run, including pending groups.
# A Chunk-2 view must not compare against Inspector group 1.
matches = [item for item in view_groups
if isinstance(item, Mapping)
and isinstance(item.get("descriptor"), Mapping)
and tuple(item["descriptor"].get("logical_chunks", ()))
== tuple(group["logical_chunks"])] if isinstance(view_groups, list) else []
expected_route = matches[0] if len(matches) == 1 else None
captured_route = group.get("reference_routing_v1")
if (not isinstance(expected_route, Mapping)
or not isinstance(captured_route, Mapping)
@@ -536,6 +597,18 @@ def adapt_group_conditioning(
)
keyframe = dict(frozen_keyframe)
latent = keyframe.get("latent")
audio_latent = keyframe.get("audio_latent")
if audio_latent is not None and (
not torch.is_tensor(audio_latent) or audio_latent.ndim != 4
):
raise RefineConditioningAdaptationError(
f"refine group {group_id} keyframe audio latent is invalid"
)
# Core keyframes may carry audio without a spatial video latent.
# Keep its frozen audio and timing; resize only video payloads.
if latent is None and audio_latent is not None:
adapted_keyframes.append(keyframe)
continue
if not torch.is_tensor(latent) or latent.ndim != 5:
raise RefineConditioningAdaptationError(
f"refine group {group_id} keyframe latent is invalid"
+5 -1
View File
@@ -16,6 +16,7 @@ from ..v2.sampling import latent_from_cpu
from .plan import SECOND_PASS_CONTRACT_VERSION
from .refine_context import (
MAGIC as REFINE_CONTEXT_MAGIC,
OUTPUT_SCOPE_KEY,
RefineConditioningAdaptationError,
RefineContextError,
adapt_group_conditioning,
@@ -283,13 +284,16 @@ def prepare_physical_refine_groups(
f"using legacy prompt-only conditioning ({exc})."
)
else:
if bool(validated_context.get("complete")):
if (bool(validated_context.get("complete"))
or validated_context.get(OUTPUT_SCOPE_KEY) is not None):
captured_groups = validated_context["groups"]
else:
warnings.append(
"WARNING: refine_context capture is incomplete; using legacy "
"prompt-only conditioning."
)
warnings.extend(str(note) for note in validated_context.get("notes", ())
if str(note).startswith("Output scope unavailable:"))
group_models: list[Any] = []
group_conditioning: list[list[Any]] = []