Files

215 lines
7.2 KiB
Python

"""Versioned, UI-independent sigma contracts for Continuum refinement.
The public Second Pass SIGMAS socket remains authoritative. These helpers attach
meaning to that tensor without recreating it: External and Full retain the exact
input object, while Tail and Partial return views into the same source values.
"""
from __future__ import annotations
import hashlib
import json
from dataclasses import dataclass
from types import MappingProxyType
from typing import Any, Mapping
import torch
MAGIC = "H3_CONTINUUM_REFINE_SCHEDULE"
SCHEMA_VERSION = 1
MODE_EXTERNAL = "external"
MODE_FULL = "full"
MODE_TAIL = "tail"
MODE_PARTIAL = "partial"
MODES = (MODE_EXTERNAL, MODE_FULL, MODE_TAIL, MODE_PARTIAL)
NOISE_MODE_VIDEO_RANDOM_AUDIO_ZERO = "video_random_mask_1_audio_zero_mask_0"
AUDIO_POLICY_LOCKED_PASSTHROUGH = "locked_first_pass_bit_exact_passthrough"
class RefineScheduleError(ValueError):
"""Raised when a refinement schedule cannot safely describe its SIGMAS."""
@dataclass(frozen=True)
class RefineSchedule:
"""One validated effective SIGMAS tensor and its serializable identity."""
sigmas: torch.Tensor
contract: Mapping[str, Any]
source_sigma_hash: str
def _validate_sigmas(sigmas: Any, *, name: str) -> torch.Tensor:
if not torch.is_tensor(sigmas) or sigmas.ndim != 1 or sigmas.numel() < 2:
raise RefineScheduleError(f"{name} must be a one-dimensional tensor with at least two values")
detached = sigmas.detach()
if not bool(torch.isfinite(detached.float()).all().item()):
raise RefineScheduleError(f"{name} contains NaN or Inf")
values = detached.float().to(device="cpu")
if bool((values[1:] > values[:-1]).any().item()):
raise RefineScheduleError(f"{name} must be monotonically non-increasing")
return sigmas
def sigma_hash(sigmas: torch.Tensor) -> str:
"""Hash dtype, shape, and exact tensor bytes without changing the input."""
_validate_sigmas(sigmas, name="sigmas")
cpu = sigmas.detach().to(device="cpu").contiguous()
payload = cpu.view(torch.uint8).numpy().tobytes()
digest = hashlib.sha256()
digest.update(str(cpu.dtype).encode("ascii"))
digest.update(b"|")
digest.update(str(tuple(int(value) for value in cpu.shape)).encode("ascii"))
digest.update(b"|")
digest.update(payload)
return digest.hexdigest()
def _schedule_identity(contract: Mapping[str, Any]) -> str:
payload = {
key: value
for key, value in contract.items()
if key != "schedule_hash"
}
encoded = json.dumps(payload, sort_keys=True, separators=(",", ":")).encode("utf-8")
return hashlib.sha256(encoded).hexdigest()
def _build_schedule(
source_sigmas: torch.Tensor,
*,
mode: str,
start_index: int,
end_index: int,
) -> RefineSchedule:
source = _validate_sigmas(source_sigmas, name="source_sigmas")
canonical_mode = str(mode).lower()
if canonical_mode not in MODES:
raise RefineScheduleError(f"unsupported refine schedule mode {mode!r}")
source_evaluations = int(source.numel()) - 1
if type(start_index) is not int or type(end_index) is not int:
raise RefineScheduleError("schedule indices must be integers")
if start_index < 0 or end_index <= start_index or end_index > source_evaluations:
raise RefineScheduleError(
f"schedule range {start_index}:{end_index} is outside 0:{source_evaluations}"
)
if start_index == 0 and end_index == source_evaluations:
effective = source
else:
effective = source[start_index : end_index + 1]
_validate_sigmas(effective, name="effective sigmas")
effective_hash = sigma_hash(effective)
source_hash = sigma_hash(source)
values = tuple(float(value) for value in effective.detach().to(device="cpu").tolist())
contract: dict[str, Any] = {
"magic": MAGIC,
"schema_version": SCHEMA_VERSION,
"mode": canonical_mode,
"sigma_values": values,
"sigma_hash": effective_hash,
"source_sigma_hash": source_hash,
"start_sigma": values[0],
"end_sigma": values[-1],
"evaluation_count": len(values) - 1,
"source_evaluation_count": source_evaluations,
"start_index": start_index,
"end_index": end_index,
"noise_mode": NOISE_MODE_VIDEO_RANDOM_AUDIO_ZERO,
"audio_policy": AUDIO_POLICY_LOCKED_PASSTHROUGH,
}
contract["schedule_hash"] = _schedule_identity(contract)
return RefineSchedule(
sigmas=effective,
contract=MappingProxyType(contract),
source_sigma_hash=source_hash,
)
def make_external_schedule(sigmas: torch.Tensor) -> RefineSchedule:
evaluations = int(_validate_sigmas(sigmas, name="sigmas").numel()) - 1
return _build_schedule(
sigmas,
mode=MODE_EXTERNAL,
start_index=0,
end_index=evaluations,
)
def make_full_schedule(sigmas: torch.Tensor) -> RefineSchedule:
evaluations = int(_validate_sigmas(sigmas, name="sigmas").numel()) - 1
return _build_schedule(
sigmas,
mode=MODE_FULL,
start_index=0,
end_index=evaluations,
)
def make_tail_schedule(
sigmas: torch.Tensor,
*,
evaluation_count: int,
) -> RefineSchedule:
source_evaluations = int(_validate_sigmas(sigmas, name="sigmas").numel()) - 1
if type(evaluation_count) is not int or not 1 <= evaluation_count <= source_evaluations:
raise RefineScheduleError(
f"tail evaluation_count must be between 1 and {source_evaluations}"
)
return _build_schedule(
sigmas,
mode=MODE_TAIL,
start_index=source_evaluations - evaluation_count,
end_index=source_evaluations,
)
def make_partial_schedule(
sigmas: torch.Tensor,
*,
start_index: int,
end_index: int,
) -> RefineSchedule:
return _build_schedule(
sigmas,
mode=MODE_PARTIAL,
start_index=start_index,
end_index=end_index,
)
def resolve_refine_schedule(
sigmas: torch.Tensor,
schedule: RefineSchedule | None = None,
) -> RefineSchedule:
"""Return External compatibility or validate an explicit internal schedule."""
source = _validate_sigmas(sigmas, name="sigmas")
if schedule is None:
return make_external_schedule(source)
if not isinstance(schedule, RefineSchedule):
raise RefineScheduleError("refine_schedule must be a RefineSchedule")
if sigma_hash(source) != schedule.source_sigma_hash:
raise RefineScheduleError("refine_schedule was derived from different source SIGMAS")
rebuilt = _build_schedule(
source,
mode=str(schedule.contract.get("mode", "")),
start_index=int(schedule.contract.get("start_index", -1)),
end_index=int(schedule.contract.get("end_index", -1)),
)
if rebuilt.contract["schedule_hash"] != schedule.contract.get("schedule_hash"):
raise RefineScheduleError("refine_schedule contract identity is inconsistent")
return schedule
def serializable_schedule_contract(schedule: RefineSchedule) -> dict[str, Any]:
"""Return a mutable JSON-safe copy for Assembly/diagnostic identity."""
if not isinstance(schedule, RefineSchedule):
raise RefineScheduleError("schedule must be a RefineSchedule")
return dict(schedule.contract)