Squashed 'vendor/dumas_h3_continuum/' content from commit d07ed31
git-subtree-dir: vendor/dumas_h3_continuum git-subtree-split: d07ed31b442d283d6a1740f875a843b9feda4c91
This commit is contained in:
@@ -0,0 +1,222 @@
|
||||
"""Pure Branch Provenance Contract v1 helpers.
|
||||
|
||||
The contract describes immutable physical-group revisions independently from
|
||||
the sampling contract that produced their tensors. A display label such as
|
||||
``Take B`` is deliberately not persisted as identity.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import hashlib
|
||||
import json
|
||||
from collections.abc import Iterable, Mapping
|
||||
from dataclasses import dataclass
|
||||
from typing import Any
|
||||
|
||||
|
||||
BRANCH_PROVENANCE_VERSION = 1
|
||||
TAKE_ACTION_AUTOMATIC = "Automatic"
|
||||
TAKE_ACTION_USE = "Use This Take"
|
||||
TAKE_ACTION_CONTINUE = "Continue From Here"
|
||||
TAKE_ACTION_OPTIONS = (
|
||||
TAKE_ACTION_AUTOMATIC,
|
||||
TAKE_ACTION_USE,
|
||||
TAKE_ACTION_CONTINUE,
|
||||
)
|
||||
|
||||
|
||||
class BranchProvenanceError(ValueError):
|
||||
"""Raised when persisted branch ancestry is ambiguous or inconsistent."""
|
||||
|
||||
|
||||
def _canonical(value: Any) -> str:
|
||||
return json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=True)
|
||||
|
||||
|
||||
def _hash(value: Any) -> str:
|
||||
return hashlib.sha256(_canonical(value).encode("utf-8")).hexdigest()
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class PhysicalGroup:
|
||||
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,
|
||||
}
|
||||
|
||||
|
||||
def physical_groups(*, chunks: int, terminal_merge_enabled: bool) -> tuple[PhysicalGroup, ...]:
|
||||
if isinstance(chunks, bool) or not isinstance(chunks, int) or chunks < 1:
|
||||
raise BranchProvenanceError("chunks must be a positive integer")
|
||||
if type(terminal_merge_enabled) is not bool:
|
||||
raise BranchProvenanceError("terminal_merge_enabled must be a boolean")
|
||||
if terminal_merge_enabled and chunks < 2:
|
||||
raise BranchProvenanceError("Terminal Merge requires at least two chunks")
|
||||
terminal_start = chunks - 1 if terminal_merge_enabled else None
|
||||
groups: list[PhysicalGroup] = []
|
||||
chunk = 1
|
||||
while chunk <= chunks:
|
||||
if terminal_start is not None and chunk == terminal_start:
|
||||
groups.append(PhysicalGroup(chunk, chunks, chunk))
|
||||
break
|
||||
groups.append(PhysicalGroup(chunk, chunk, chunk))
|
||||
chunk += 1
|
||||
return tuple(groups)
|
||||
|
||||
|
||||
def _record_identity(record: Mapping[str, Any]) -> dict[str, Any]:
|
||||
entry = record.get("entry") or {}
|
||||
return {
|
||||
"sequence_index": int(record.get("sequence_index", -1)),
|
||||
"storage_revision_id": str(record.get("storage_revision_id", "")),
|
||||
"filename": str(record.get("filename", "")),
|
||||
"file_size": int(record.get("file_size", -1)),
|
||||
"file_sha256": str(record.get("file_sha256", "")),
|
||||
"seed": int(record.get("seed", entry.get("seed", -1))),
|
||||
"prompt_hash": str(record.get("prompt_hash", entry.get("prompt_hash", ""))),
|
||||
}
|
||||
|
||||
|
||||
def make_group_revision(
|
||||
*,
|
||||
parent_revision_id: str | None,
|
||||
group: PhysicalGroup,
|
||||
variation_nonce: int,
|
||||
created_utc: str,
|
||||
storage_revision_id: str,
|
||||
generation_contract_sha256: str,
|
||||
lineage_sha256: str,
|
||||
records: Iterable[Mapping[str, Any]],
|
||||
branch_cut: Mapping[str, Any] | None = None,
|
||||
) -> dict[str, Any]:
|
||||
if not isinstance(group, PhysicalGroup):
|
||||
raise BranchProvenanceError("group must be a PhysicalGroup")
|
||||
nonce = int(variation_nonce)
|
||||
if nonce < 0 or nonce > 0xFFFFFFFF:
|
||||
raise BranchProvenanceError("variation_nonce is outside uint32")
|
||||
record_values = [_record_identity(record) for record in records]
|
||||
expected_positions = list(range(group.start - 1, group.end))
|
||||
if [record["sequence_index"] for record in record_values] != expected_positions:
|
||||
raise BranchProvenanceError("physical group records are incomplete or non-atomic")
|
||||
if not all(record["storage_revision_id"] for record in record_values):
|
||||
raise BranchProvenanceError("physical group record source is missing")
|
||||
seed_identity = _hash(
|
||||
[
|
||||
{
|
||||
"sequence_index": record["sequence_index"],
|
||||
"seed": record["seed"],
|
||||
"prompt_hash": record["prompt_hash"],
|
||||
}
|
||||
for record in record_values
|
||||
]
|
||||
)
|
||||
identity = {
|
||||
"branch_provenance_version": BRANCH_PROVENANCE_VERSION,
|
||||
"parent_revision_id": None if parent_revision_id is None else str(parent_revision_id),
|
||||
"group": group.as_metadata(),
|
||||
"variation_nonce": nonce,
|
||||
"seed_identity": seed_identity,
|
||||
"storage_revision_id": str(storage_revision_id),
|
||||
"generation_contract_sha256": str(generation_contract_sha256),
|
||||
"lineage_sha256": str(lineage_sha256),
|
||||
"records": record_values,
|
||||
}
|
||||
revision_id = _hash(identity)[:24]
|
||||
result = {
|
||||
"revision_id": revision_id,
|
||||
**identity,
|
||||
"created_utc": str(created_utc),
|
||||
"revision_order": f"{created_utc}|{revision_id}",
|
||||
}
|
||||
if branch_cut is not None:
|
||||
result["branch_cut"] = {
|
||||
"selected_revision_id": str(branch_cut.get("selected_revision_id", "")),
|
||||
"after_physical_group": int(branch_cut.get("after_physical_group", 0)),
|
||||
}
|
||||
return result
|
||||
|
||||
|
||||
def validate_group_revision(value: Mapping[str, Any]) -> dict[str, Any]:
|
||||
if not isinstance(value, Mapping):
|
||||
raise BranchProvenanceError("group revision must be an object")
|
||||
if int(value.get("branch_provenance_version", -1)) != BRANCH_PROVENANCE_VERSION:
|
||||
raise BranchProvenanceError("group revision provenance version is unsupported")
|
||||
group_value = value.get("group")
|
||||
if not isinstance(group_value, Mapping):
|
||||
raise BranchProvenanceError("group revision physical group is missing")
|
||||
group = PhysicalGroup(
|
||||
start=int(group_value.get("start", 0)),
|
||||
end=int(group_value.get("end", 0)),
|
||||
physical_group=int(group_value.get("physical_group", 0)),
|
||||
)
|
||||
if group.start < 1 or group.end < group.start or group.physical_group != group.start:
|
||||
raise BranchProvenanceError("group revision physical group is invalid")
|
||||
rebuilt = make_group_revision(
|
||||
parent_revision_id=value.get("parent_revision_id"),
|
||||
group=group,
|
||||
variation_nonce=int(value.get("variation_nonce", -1)),
|
||||
created_utc=str(value.get("created_utc", "")),
|
||||
storage_revision_id=str(value.get("storage_revision_id", "")),
|
||||
generation_contract_sha256=str(value.get("generation_contract_sha256", "")),
|
||||
lineage_sha256=str(value.get("lineage_sha256", "")),
|
||||
records=value.get("records") or [],
|
||||
branch_cut=value.get("branch_cut"),
|
||||
)
|
||||
if str(value.get("revision_id", "")) != rebuilt["revision_id"]:
|
||||
raise BranchProvenanceError("group revision immutable identity is invalid")
|
||||
if str(value.get("seed_identity", "")) != rebuilt["seed_identity"]:
|
||||
raise BranchProvenanceError("group revision seed identity is invalid")
|
||||
rebuilt["revision_order"] = str(
|
||||
value.get("revision_order", rebuilt["revision_order"])
|
||||
)
|
||||
return rebuilt
|
||||
|
||||
|
||||
def resolve_chain(
|
||||
catalog: Mapping[str, Mapping[str, Any]],
|
||||
head_revision_id: str,
|
||||
) -> list[dict[str, Any]]:
|
||||
head = str(head_revision_id)
|
||||
if not head:
|
||||
raise BranchProvenanceError("selected revision ID is empty")
|
||||
reverse: list[dict[str, Any]] = []
|
||||
seen: set[str] = set()
|
||||
current: str | None = head
|
||||
while current is not None:
|
||||
if current in seen:
|
||||
raise BranchProvenanceError("group revision ancestry contains a cycle")
|
||||
seen.add(current)
|
||||
raw = catalog.get(current)
|
||||
if raw is None:
|
||||
raise BranchProvenanceError(
|
||||
f"group revision parent is missing: {current}"
|
||||
)
|
||||
revision = validate_group_revision(raw)
|
||||
reverse.append(revision)
|
||||
parent = revision.get("parent_revision_id")
|
||||
current = None if parent is None else str(parent)
|
||||
chain = list(reversed(reverse))
|
||||
expected_start = 1
|
||||
lineage = str(chain[0].get("lineage_sha256", ""))
|
||||
for revision in chain:
|
||||
group = revision["group"]
|
||||
if int(group["start"]) != expected_start:
|
||||
raise BranchProvenanceError("group revision ancestry is not a contiguous prefix")
|
||||
if str(revision.get("lineage_sha256", "")) != lineage:
|
||||
raise BranchProvenanceError("group revision ancestry crosses sampling lineages")
|
||||
expected_start = int(group["end"]) + 1
|
||||
return chain
|
||||
|
||||
|
||||
def active_revision_map(chain: Iterable[Mapping[str, Any]]) -> dict[str, str]:
|
||||
active: dict[str, str] = {}
|
||||
for revision in chain:
|
||||
validated = validate_group_revision(revision)
|
||||
active[str(validated["group"]["physical_group"])] = validated["revision_id"]
|
||||
return active
|
||||
Reference in New Issue
Block a user