d-robotics 63512da71f
Some checks failed
web-ci / checks (push) Waiting to run
web-ci / checks (pull_request) Has been cancelled
🐛 Preserve confirmed annotation frames and enforce v4 time evidence
2026-10-22 12:54:08 +08:00

2220 lines
132 KiB
Python
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

"""Delivery package operator with v5 final-segment and pose-cropping guarantees."""
from __future__ import annotations
import hashlib
import bisect
import csv
import json
import math
import pathlib
import re
import shutil
import subprocess
import tempfile
from typing import Any, Callable
HelperMap = dict[str, Callable[..., Any]]
_SHA = re.compile(r"^[a-f0-9]{64}$")
def _sha256_file(path: pathlib.Path) -> str:
digest = hashlib.sha256()
with path.open("rb") as handle:
for block in iter(lambda: handle.read(1024 * 1024), b""):
digest.update(block)
return digest.hexdigest()
def _bool(params: dict[str, str], key: str, default: bool = False) -> bool:
value = str(params.get(key, str(default))).strip().lower()
if value in {"1", "true", "yes", "on"}:
return True
if value in {"0", "false", "no", "off"}:
return False
raise RuntimeError(f"{key} must be boolean")
def _source_video_name(item: dict[str, Any]) -> str:
direct = str(item.get("sourceVideo", "")).strip()
if direct:
return direct
annotation = item.get("annotation") if isinstance(item.get("annotation"), dict) else {}
annotated = str(annotation.get("sourceVideo", "")).strip()
if annotated:
return annotated
source = item.get("source") if isinstance(item.get("source"), dict) else {}
named = str(source.get("name", "")).strip()
if named:
return named
return pathlib.PurePosixPath(str(item.get("sourceClipPath") or item.get("clipPath") or "")).name
def _payload_tree(value: Any) -> list[dict[str, Any]]:
items: list[dict[str, Any]] = []
if isinstance(value, dict):
items.append(value)
for key in ("upstreamPayloads", "payloads", "inputs"):
nested = value.get(key)
if isinstance(nested, list):
for child in nested:
items.extend(_payload_tree(child))
elif isinstance(value, list):
for child in value:
items.extend(_payload_tree(child))
return items
def _first_payload(payloads: list[dict[str, Any]], schema: str) -> dict[str, Any] | None:
return next((payload for payload in payloads if payload.get("schemaVersion") == schema), None)
def _payloads_with_full_pose_manifests(
inputs: list[dict[str, Any]],
output: pathlib.Path,
helpers: HelperMap,
) -> list[dict[str, Any]]:
"""Reload externalized pose JSON instead of accepting its shallow summary.
Large JSON artifacts intentionally keep only schema/count metadata in
``artifact.data``. ``payloads_from_inputs`` normally prefers that metadata,
but package needs the complete per-frame pose arrays. Materialize only the
two pose schemas and replace their summaries with the verified JSON object.
"""
payloads = list(helpers["payloads_from_inputs"](inputs))
pose_schemas = {"droboticflow.headpose/v1", "droboticflow.wilor.hand_pose_result/v1"}
materialize = helpers.get("source_path_from_item")
for index, artifact in enumerate(inputs):
if index >= len(payloads) or str(artifact.get("type", "")).strip().lower() != "json":
continue
payload = payloads[index]
if not isinstance(payload, dict) or payload.get("schemaVersion") not in pose_schemas:
continue
has_frames = isinstance(payload.get("frames"), list)
if payload.get("schemaVersion") == "droboticflow.wilor.hand_pose_result/v1":
result = payload.get("result") if isinstance(payload.get("result"), dict) else {}
has_frames = has_frames or isinstance(result.get("frames"), list)
if has_frames:
continue
candidate = pathlib.Path(str(artifact.get("path", "")).strip())
if (not candidate.is_file() or candidate.stat().st_size <= 0) and callable(materialize):
candidate = pathlib.Path(materialize(artifact, str(artifact.get("name") or "pose.json"), output, {}))
if not candidate.is_file() or candidate.stat().st_size <= 0:
continue
try:
loaded = json.loads(candidate.read_text(encoding="utf-8"))
except (OSError, json.JSONDecodeError) as exc:
raise RuntimeError(f"pose manifest is not readable JSON: {candidate.name}") from exc
if not isinstance(loaded, dict) or loaded.get("schemaVersion") != payload.get("schemaVersion"):
raise RuntimeError(f"pose manifest schema does not match artifact summary: {candidate.name}")
payloads[index] = loaded
return payloads
def _pose_timestamp(frame: dict[str, Any]) -> float | None:
for key in ("timestampSeconds", "timestamp", "timeSeconds"):
if key in frame:
try:
return float(frame[key])
except (TypeError, ValueError):
return None
if "timestampMs" in frame:
try:
return float(frame["timestampMs"]) / 1000.0
except (TypeError, ValueError):
return None
return None
def _crop_pose(payload: dict[str, Any], start: float, end: float, kind: str) -> dict[str, Any]:
raw_frames: Any = payload.get("frames")
if kind == "handpose" and not isinstance(raw_frames, list):
result = payload.get("result") if isinstance(payload.get("result"), dict) else {}
raw_frames = result.get("frames")
frames: list[dict[str, Any]] = []
seen: dict[tuple[float, str], str] = {}
for frame in raw_frames if isinstance(raw_frames, list) else []:
if not isinstance(frame, dict):
continue
timestamp = _pose_timestamp(frame)
# Final segments are half-open so a frame at a shared boundary belongs
# to the following segment exactly once.
if timestamp is None or timestamp < start or timestamp >= end:
continue
cropped = dict(frame)
relative = round(timestamp - start, 6)
cropped["timestampSeconds"] = relative
cropped["sourceTimestampSeconds"] = timestamp
cropped.pop("timestampMs", None)
identity = (timestamp, str(cropped.get("frameIndex", cropped.get("sourceFrame", ""))))
encoded = json.dumps(cropped, sort_keys=True, ensure_ascii=False)
if identity in seen:
if seen[identity] != encoded:
raise RuntimeError(f"conflicting duplicate {kind} pose frame at source timestamp {timestamp}")
continue
seen[identity] = encoded
frames.append(cropped)
frames.sort(key=lambda item: (float(item["timestampSeconds"]), str(item.get("frameIndex", item.get("sourceFrame", "")))))
return {
"schemaVersion": f"droboticflow.{kind}.segment/v1",
"enabled": bool(payload.get("enabled", True)),
"segmentStartSourceSeconds": start,
"segmentEndSourceSeconds": end,
"frameCount": len(frames),
"frames": frames,
"provenance": {
key: payload.get(key)
for key in ("schemaVersion", "model", "modelSha256", "serviceImageId", "licenseId", "service", "runtimeEvidence", "source")
if key in payload
},
}
def _pose_frames(payload: dict[str, Any], kind: str) -> list[dict[str, Any]]:
frames = payload.get("frames")
if kind == "handpose" and not isinstance(frames, list):
result = payload.get("result") if isinstance(payload.get("result"), dict) else {}
frames = result.get("frames")
return [frame for frame in frames if isinstance(frame, dict)] if isinstance(frames, list) else []
def _camera_collection_id(value: Any) -> str:
if isinstance(value, dict):
data = value.get("data") if isinstance(value.get("data"), dict) else {}
direct = str(value.get("collectionId") or data.get("collectionId") or "").strip()
if direct:
return direct
value = value.get("sourceVideo") or value.get("name") or value.get("path") or ""
name = pathlib.PurePosixPath(str(value or "").strip()).name
match = re.match(r"(.+)_camera_(?:left|right)_part\d+", name, re.IGNORECASE)
return match.group(1) if match else pathlib.PurePosixPath(name).stem
def _right_video_artifacts(inputs: list[dict[str, Any]]) -> list[dict[str, Any]]:
artifacts: list[dict[str, Any]] = []
for artifact in inputs:
if str(artifact.get("type", "")).strip().lower() != "video":
continue
port = str(artifact.get("portId") or artifact.get("portName") or "").strip()
data = artifact.get("data") if isinstance(artifact.get("data"), dict) else {}
transform_chain = data.get("transformChain") if isinstance(data.get("transformChain"), list) else []
named_right = "camera_right" in str(artifact.get("name") or artifact.get("path") or "").lower()
transformed_right = any(
isinstance(item, dict) and str(item.get("cameraSide", "")).lower() == "right"
for item in transform_chain
)
if (
port in {"rightVideos", "rightRectifiedVideos", "rightSanitizedVideos"}
or str(data.get("cameraSide", "")).lower() == "right"
or named_right
or transformed_right
):
artifacts.append(artifact)
return artifacts
def _matching_right_video(item: dict[str, Any], candidates: list[dict[str, Any]]) -> dict[str, Any] | None:
if not candidates:
return None
collection_id = str(item.get("collectionId") or "").strip() or _camera_collection_id(_source_video_name(item))
matches = [candidate for candidate in candidates if _camera_collection_id(candidate) == collection_id]
if len(matches) == 1:
return matches[0]
if len(candidates) == 1:
return candidates[0]
if not matches:
raise RuntimeError(f"no right-camera video matches collection {collection_id}")
raise RuntimeError(f"multiple right-camera videos match collection {collection_id}")
def _materialize_input_video(
artifact: dict[str, Any],
output: pathlib.Path,
helpers: HelperMap,
) -> pathlib.Path:
materialize = helpers.get("source_path_from_item")
if not callable(materialize):
raise RuntimeError("stereo delivery cannot materialize the right-camera video")
source_ref = helpers.get("source_ref_from_artifact")
source = source_ref(artifact) if callable(source_ref) else artifact.get("source", {})
name = str(artifact.get("name") or "right-camera.mp4").strip()
path = materialize(
{
"source": source if isinstance(source, dict) else {},
"path": str(artifact.get("path", "")),
},
name,
output,
{},
)
resolved = pathlib.Path(path)
if not resolved.is_file() or resolved.stat().st_size <= 0:
raise RuntimeError("right-camera video is unavailable for synchronized cropping")
return resolved
def _materialize_input_file(artifact: dict[str, Any], output: pathlib.Path, helpers: HelperMap) -> pathlib.Path:
materialize = helpers.get("source_path_from_item")
if not callable(materialize):
raise RuntimeError("synchronized delivery cannot materialize a sidecar file")
source_ref = helpers.get("source_ref_from_artifact")
source = source_ref(artifact) if callable(source_ref) else artifact.get("source", {})
name = str(artifact.get("name") or "sidecar.bin").strip()
resolved = pathlib.Path(materialize({"source": source if isinstance(source, dict) else {}, "path": str(artifact.get("path", ""))}, name, output, {}))
if not resolved.is_file() or resolved.stat().st_size <= 0:
raise RuntimeError(f"synchronized delivery sidecar is unavailable: {name}")
return resolved
def _source_part_number(value: Any, camera_side: str) -> str:
text = str(value or "")
match = re.search(rf"_camera_{re.escape(camera_side)}_part(\d+)", text, re.IGNORECASE)
if not match:
raise RuntimeError(f"cannot determine {camera_side} camera part for absolute PTS recovery")
return match.group(1)
def _absolute_pts_sibling_artifact(
collection_id: str,
camera_side: str,
video_name: str,
inputs: list[dict[str, Any]],
) -> dict[str, Any]:
"""Resolve the original absolute PTS next to the BOS capture sidecars.
Historical v5.8 graphs supplied rectification-generated technical PTS that
start at zero. The original PTS object is recovered only from a
credential-free BOS reference in the same collection directory and is
subsequently subjected to the normal row-count and monotonicity checks.
"""
part = _source_part_number(video_name, camera_side)
name = f"{collection_id}_camera_{camera_side}_part{part}_pts.csv"
for artifact in inputs:
payload = artifact.get("payload") if isinstance(artifact.get("payload"), dict) else {}
ref = payload.get("ref") if isinstance(payload.get("ref"), dict) else {}
bucket = str(ref.get("bucket") or "").strip()
key = str(ref.get("key") or "").strip()
connection_id = str(ref.get("connectionId") or "").strip()
if not bucket or not key or not connection_id:
continue
parent = pathlib.PurePosixPath(key).parent.as_posix().strip(".")
target_key = f"{parent}/{name}" if parent else name
return {
"name": name,
"type": "file",
"path": f"bos://{bucket}/{target_key}",
"payload": {
"mode": "ref",
"type": "file",
"ref": {
"provider": str(ref.get("provider") or "BOS"),
"connectionId": connection_id,
"bucket": bucket,
"key": target_key,
"kind": "object",
},
},
"data": {"collectionId": collection_id, "cameraSide": camera_side, "role": "absolutePts"},
}
raise RuntimeError(f"absolute {camera_side} PTS cannot be resolved from the source BOS collection")
def _sidecar_artifacts(inputs: list[dict[str, Any]], ports: set[str]) -> list[dict[str, Any]]:
# Worker input artifacts retain their upstream source port IDs. Accept the
# explicit v5.8 package target names and the corresponding rectification
# source names so a valid edge does not lose its sidecar at runtime.
aliases = {
"leftTimestamps": {"leftRectifiedTimestamps", "timestamps", "videoPts"},
"rightTimestamps": {"rightRectifiedTimestamps", "timestamps", "videoPts"},
}
accepted = set(ports)
for port in ports:
accepted.update(aliases.get(port, set()))
return [artifact for artifact in inputs if str(artifact.get("portId") or artifact.get("portName") or "").strip() in accepted]
def _matching_sidecar(collection_id: str, candidates: list[dict[str, Any]], marker: str = "") -> dict[str, Any]:
filtered = [item for item in candidates if not marker or marker in str(item.get("name") or "").lower()]
matches = [item for item in filtered if _camera_collection_id(item) == collection_id]
if len(matches) == 1:
return matches[0]
if len(filtered) == 1:
return filtered[0]
if not matches:
raise RuntimeError(f"no {marker or 'sidecar'} file matches collection {collection_id}")
raise RuntimeError(f"multiple {marker or 'sidecar'} files match collection {collection_id}")
def _clean_csv_cell(value: Any) -> str:
return str(value or "").strip().strip("\ufeff").strip("\t").strip()
def _read_rows(path: pathlib.Path) -> tuple[list[str], list[list[str]]]:
lines = path.read_text(encoding="utf-8-sig").splitlines()
if not lines:
raise RuntimeError(f"sidecar CSV is empty: {path.name}")
delimiter = "," if "," in lines[0] else "\t"
parsed = list(csv.reader(lines, delimiter=delimiter))
header = [_clean_csv_cell(value) for value in parsed[0]]
rows = [[_clean_csv_cell(value) for value in row] for row in parsed[1:] if any(_clean_csv_cell(value) for value in row)]
return header, rows
def _read_pts(path: pathlib.Path) -> list[int]:
header, rows = _read_rows(path)
normalized = {name.lower(): index for index, name in enumerate(header)}
timestamp_name = next((name for name in ("timestamp_us", "timestampus", "pts_us") if name in normalized), None)
if timestamp_name is None:
raise RuntimeError(f"PTS CSV must contain timestamp_us: {path.name}")
column = normalized[timestamp_name]
values: list[int] = []
for row in rows:
try:
value = int(row[column])
except (IndexError, ValueError) as exc:
raise RuntimeError(f"PTS CSV contains an invalid timestamp_us: {path.name}") from exc
if values and value <= values[-1]:
raise RuntimeError(f"PTS CSV timestamp_us must be strictly increasing: {path.name}")
values.append(value)
if not values:
raise RuntimeError(f"PTS CSV has no frame timestamps: {path.name}")
return values
def _read_imu(path: pathlib.Path) -> list[dict[str, Any]]:
header, rows = _read_rows(path)
indexes = {name.lower(): index for index, name in enumerate(header)}
required = {"timestamp_us", "x", "y", "z", "type"}
if not required.issubset(indexes):
raise RuntimeError(f"IMU CSV must contain timestamp_us,x,y,z,type: {path.name}")
result: list[dict[str, Any]] = []
previous = -1
for row in rows:
try:
timestamp = int(row[indexes["timestamp_us"]])
kind = row[indexes["type"]].lower()
values = [float(row[indexes[key]]) for key in ("x", "y", "z")]
except (IndexError, ValueError) as exc:
raise RuntimeError(f"IMU CSV contains an invalid row: {path.name}") from exc
if kind not in {"accel", "gyro"} or timestamp < previous:
raise RuntimeError(f"IMU CSV type/timestamp ordering is invalid: {path.name}")
previous = timestamp
result.append({"timestamp_us": timestamp, "x": values[0], "y": values[1], "z": values[2], "type": kind})
if not result:
raise RuntimeError(f"IMU CSV has no samples: {path.name}")
return result
def _read_materialized_pts(path: pathlib.Path) -> list[int]:
header, rows = _read_rows(path)
normalized = {name.lower(): index for index, name in enumerate(header)}
timestamp_column = normalized.get("timestamp_ms")
if timestamp_column is None:
raise RuntimeError(f"materialized PTS CSV must contain timestamp_ms: {path.name}")
values: list[int] = []
for row in rows:
try:
value = int(round(float(row[timestamp_column]) * 1000))
except (IndexError, ValueError) as exc:
raise RuntimeError(f"materialized PTS CSV contains an invalid timestamp_ms: {path.name}") from exc
if values and value <= values[-1]:
raise RuntimeError(f"materialized PTS CSV timestamp_ms must be strictly increasing: {path.name}")
values.append(value)
if not values:
raise RuntimeError(f"materialized PTS CSV has no frame timestamps: {path.name}")
return values
def _validate_materialized_imu(path: pathlib.Path, start_us: int, end_us: int, *, allow_empty: bool = False) -> int:
header, rows = _read_rows(path)
indexes = {name.lower(): index for index, name in enumerate(header)}
required = {"timestamp_ms", "clip_time_ms", "x", "y", "z", "type"}
if not required.issubset(indexes):
raise RuntimeError(f"materialized IMU CSV is missing required columns: {path.name}")
previous = -1
seen_types: dict[int, set[str]] = {}
for row in rows:
try:
timestamp_us = int(round(float(row[indexes["timestamp_ms"]]) * 1000))
kind = row[indexes["type"]].lower()
for key in ("x", "y", "z"):
float(row[indexes[key]])
except (IndexError, ValueError) as exc:
raise RuntimeError(f"materialized IMU CSV contains an invalid row: {path.name}") from exc
if timestamp_us < previous or kind not in {"accel", "gyro"}:
raise RuntimeError(f"materialized IMU ordering/type is invalid: {path.name}")
if timestamp_us < start_us or timestamp_us >= end_us:
raise RuntimeError(f"materialized IMU row is outside the synchronized slice window: {path.name}")
previous = timestamp_us
seen_types.setdefault(timestamp_us, set()).add(kind)
if (not rows and not allow_empty) or any(types != {"accel", "gyro"} for types in seen_types.values()):
raise RuntimeError(f"materialized IMU must contain paired accel/gyro samples: {path.name}")
return len(rows)
def _ffprobe_frame_count(path: pathlib.Path) -> int:
completed = subprocess.run(["ffprobe", "-v", "error", "-select_streams", "v:0", "-count_frames", "-show_entries", "stream=nb_read_frames", "-of", "default=nokey=1:noprint_wrappers=1", str(path)], capture_output=True, text=True, check=False)
try:
count = int(completed.stdout.strip())
except ValueError as exc:
raise RuntimeError(f"cannot determine decoded video frame count: {path.name}") from exc
if completed.returncode != 0 or count <= 0:
raise RuntimeError(f"cannot determine decoded video frame count: {path.name}")
return count
def _write_frame_segment(source: pathlib.Path, destination: pathlib.Path, start_frame: int, end_frame: int) -> None:
if shutil.which("ffmpeg") is None or shutil.which("ffprobe") is None:
raise RuntimeError("synchronized delivery requires ffmpeg and ffprobe")
if start_frame < 0 or end_frame <= start_frame:
raise RuntimeError("synchronized video frame range is empty")
destination.parent.mkdir(parents=True, exist_ok=True)
expression = f"trim=start_frame={start_frame}:end_frame={end_frame},setpts=PTS-STARTPTS"
# BOS CSI does not support FFmpeg's faststart trailer rewrite, which
# closes and re-opens the completed MP4 to move its moov atom. A normal
# single-pass MP4 remains fully playable and checksum-stable.
completed = subprocess.run(["ffmpeg", "-nostdin", "-hide_banner", "-loglevel", "error", "-y", "-i", str(source), "-an", "-vf", expression, "-c:v", "libx264", "-preset", "veryfast", "-crf", "23", "-pix_fmt", "yuv420p", str(destination)], capture_output=True, text=True, check=False)
if completed.returncode != 0 or not destination.is_file() or destination.stat().st_size <= 0:
raise RuntimeError(f"synchronized frame-accurate cut failed: {(completed.stderr or completed.stdout).strip()[:800]}")
def _write_pts_slice(path: pathlib.Path, timestamps: list[int], start_index: int, end_index: int) -> dict[str, Any]:
selected = timestamps[start_index:end_index]
if not selected:
raise RuntimeError("synchronized PTS slice is empty")
with path.open("w", encoding="utf-8", newline="") as handle:
writer = csv.writer(handle)
writer.writerow(["frame_index", "timestamp_ms", "clip_time_ms"])
origin = selected[0]
for index, value in enumerate(selected):
writer.writerow([index, round(value / 1000), round((value - origin) / 1000)])
return {"name": path.name, "sha256": _sha256_file(path), "bytes": path.stat().st_size, "rowCount": len(selected), "firstTimestampUs": selected[0], "lastTimestampUs": selected[-1]}
def _write_imu_slice(path: pathlib.Path, rows: list[dict[str, Any]], start_us: int, end_us: int) -> dict[str, Any]:
selected = [row for row in rows if start_us <= int(row["timestamp_us"]) < end_us]
if not selected:
raise RuntimeError("synchronized IMU slice is empty")
by_timestamp: dict[int, set[str]] = {}
for row in selected:
by_timestamp.setdefault(int(row["timestamp_us"]), set()).add(str(row["type"]))
if any(types != {"accel", "gyro"} for types in by_timestamp.values()):
raise RuntimeError("synchronized IMU slice contains an unpaired accel/gyro timestamp")
with path.open("w", encoding="utf-8", newline="") as handle:
writer = csv.writer(handle)
writer.writerow(["timestamp_ms", "clip_time_ms", "x", "y", "z", "type"])
origin = int(selected[0]["timestamp_us"])
for row in selected:
timestamp = int(row["timestamp_us"])
writer.writerow([round(timestamp / 1000), round((timestamp - origin) / 1000), row["x"], row["y"], row["z"], row["type"]])
return {"name": path.name, "sha256": _sha256_file(path), "bytes": path.stat().st_size, "sampleCount": len(selected), "timestampCount": len(by_timestamp), "firstTimestampUs": int(selected[0]["timestamp_us"]), "lastTimestampUs": int(selected[-1]["timestamp_us"])}
def _write_verified_segment(
source: pathlib.Path,
destination: pathlib.Path,
start: float,
end: float,
helpers: HelperMap,
) -> dict[str, Any]:
_write_precise_final_segment(source, destination, start, end)
metrics = helpers["inspect_video_file"](destination)
actual_duration = float(metrics.get("duration") or 0.0)
expected_duration = end - start
if actual_duration <= 0 or abs(actual_duration - expected_duration) > 0.35:
raise RuntimeError(
f"synchronized stereo segment duration mismatch: expected {expected_duration:.3f}s, got {actual_duration:.3f}s"
)
return {
"name": destination.name,
"sha256": _sha256_file(destination),
"bytes": destination.stat().st_size,
"durationSeconds": actual_duration,
}
def _validate_final_acceptance(item: dict[str, Any]) -> dict[str, Any]:
evidence = item.get("finalAcceptance") if isinstance(item.get("finalAcceptance"), dict) else {}
canonical = str(evidence.get("canonical", ""))
digest = str(evidence.get("sha256", "")).lower()
if item.get("finalAcceptanceConfirmed") is not True or not canonical or not _SHA.fullmatch(digest):
raise RuntimeError("v5 package requires verified pre-package acceptance evidence")
if hashlib.sha256(canonical.encode("utf-8")).hexdigest() != digest:
raise RuntimeError("pre-package acceptance evidence SHA-256 does not verify")
if not str(evidence.get("confirmedByUserId", "")).strip():
raise RuntimeError("pre-package acceptance evidence has no confirmer identity")
return evidence
def _write_precise_final_segment(source: pathlib.Path, destination: pathlib.Path, start: float, end: float) -> None:
if shutil.which("ffmpeg") is None:
raise RuntimeError("final package requires ffmpeg for precise segment materialization")
duration = end - start
destination.parent.mkdir(parents=True, exist_ok=True)
completed = subprocess.run(
[
"ffmpeg",
"-nostdin",
"-hide_banner",
"-loglevel",
"error",
"-y",
"-i",
str(source),
"-ss",
f"{start:.6f}",
"-t",
f"{duration:.6f}",
"-map",
"0:v:0",
"-map",
"0:a?",
"-c:v",
"libx264",
"-preset",
"veryfast",
"-crf",
"23",
"-pix_fmt",
"yuv420p",
"-c:a",
"aac",
"-reset_timestamps",
"1",
"-avoid_negative_ts",
"make_zero",
str(destination),
],
stdout=subprocess.PIPE,
stderr=subprocess.PIPE,
text=True,
)
if completed.returncode != 0:
message = (completed.stderr or completed.stdout or "unknown ffmpeg error").strip()
raise RuntimeError(f"precise final segment ffmpeg failed: {message}")
def _materialize_final_mp4(item: dict[str, Any], package_dir: pathlib.Path, helpers: HelperMap) -> pathlib.Path:
name = str(item.get("clipName") or f"{item.get('clipId', 'segment')}.mp4")
destination = package_dir / name
source_path = pathlib.Path(str(item.get("clipPath", "")).strip())
if not source_path.is_file() or source_path.stat().st_size <= 0:
source = item.get("source") if isinstance(item.get("source"), dict) else {}
source_path = helpers["source_path_from_item"](
{"source": source or {"path": str(item.get("clipPath", "")).strip()}},
str(item.get("sourceVideo") or pathlib.PurePosixPath(str(item.get("clipPath", ""))).name or "source.mp4"),
package_dir,
)
if not source_path.is_file() or source_path.stat().st_size <= 0:
raise RuntimeError(f"final segment source video is missing or empty: {source_path}")
start = float(item.get("startSecond", 0.0))
end = float(item.get("endSecond", 0.0))
if not (0 <= start < end):
raise RuntimeError("final segment must contain valid source-relative boundaries")
_write_precise_final_segment(source_path, destination, start, end)
if not destination.is_file() or destination.stat().st_size <= 0:
raise RuntimeError("final segment MP4 was not materialized")
metrics = helpers["inspect_video_file"](destination)
actual_duration = float(metrics.get("duration") or 0.0)
requested_duration = end - start
if actual_duration <= 0 or abs(actual_duration - requested_duration) > 0.35:
raise RuntimeError(f"final segment MP4 duration mismatch: expected {requested_duration:.3f}s, got {actual_duration:.3f}s")
return destination
def _materialize_left_source(item: dict[str, Any], directory: pathlib.Path, helpers: HelperMap) -> pathlib.Path:
source_path = pathlib.Path(str(item.get("clipPath", "")).strip())
if source_path.is_file() and source_path.stat().st_size > 0:
return source_path
source = item.get("source") if isinstance(item.get("source"), dict) else {}
resolved = pathlib.Path(
helpers["source_path_from_item"](
{"source": source or {"path": str(item.get("clipPath", "")).strip()}},
str(item.get("sourceVideo") or pathlib.PurePosixPath(str(item.get("clipPath", ""))).name or "left-camera.mp4"),
directory,
)
)
if not resolved.is_file() or resolved.stat().st_size <= 0:
raise RuntimeError("left-camera video is unavailable for synchronized cropping")
return resolved
def _collect_unique_package_artifacts(
run_id: str,
node_id: str,
packages_root: pathlib.Path,
node_data: dict[str, Any],
binding: Any,
helpers: HelperMap,
) -> list[dict[str, Any]]:
artifacts = helpers["collect_output_artifacts"](run_id, node_id, packages_root, node_data=node_data, output=binding)
seen: set[str] = set()
for artifact in artifacts:
path = pathlib.Path(str(artifact.get("path", "")))
try:
relative = path.relative_to(packages_root).as_posix()
except ValueError:
relative = path.name
suffix = hashlib.sha256(relative.encode("utf-8")).hexdigest()[:12]
base_id = str(artifact.get("id") or f"{run_id}-{node_id}-package-artifact")
artifact["id"] = f"{base_id}-{suffix}"
if artifact["id"] in seen:
raise RuntimeError(f"package artifact id collision for {relative}")
seen.add(artifact["id"])
return artifacts
_PART_INDEX_SCHEMA = "droboticflow.delivery.part-index/v1"
_SOURCE_PART_INDEX_SCHEMA = "droboticflow.delivery.part-index/v2"
_SOURCE_SLICE_SCHEMA = "droboticflow.source-slice-index/v1"
_PART_INDEX_ARTIFACT = "delivery.part-index"
_PART_INDEX_FILE = "part.json"
# Only these review fields leave the platform. Reviewer identity, free-text
# quality comments and unfiltered acceptance statistics stay internal.
_QUALITY_REVIEW_EXPORT_FIELDS = ("taskId", "revision", "decision", "reviewerUserId", "createdAt")
_ACCEPTANCE_EXPORT_FIELDS = (
"confirmed",
"sampled",
"samplingDecision",
"samplingProbability",
"samplingPolicyRevision",
"samplingRandomValue",
"samplingDecidedAt",
"acceptedAt",
"confirmedByUserId",
"processingProfile",
"poseDelivery",
)
def _optional_float(value: Any) -> float | None:
if value is None or isinstance(value, bool):
return None
try:
return float(value)
except (TypeError, ValueError):
return None
def _part_index_capture_record(summary_payload: dict[str, Any], revision_manifest: dict[str, Any]) -> dict[str, Any]:
if isinstance(summary_payload.get("capture"), dict):
return summary_payload["capture"]
if isinstance(revision_manifest.get("capture"), dict):
return revision_manifest["capture"]
return {}
def _part_index_discard_evidence(evidence: dict[str, Any], *, classification_v4: bool = False) -> dict[str, Any]:
# New workflow metadata must not change the bytes of a legacy package.
result = {
"reason": str(evidence.get("reason") or ""),
"reasonLabelId": str(evidence.get("reasonLabelId") or ""),
"reasonName": str(evidence.get("reasonName") or ""),
"note": str(evidence.get("note") or ""),
"discardedByUserId": str(evidence.get("discardedByUserId") or ""),
"discardedAt": str(evidence.get("discardedAt") or ""),
}
if classification_v4:
result.update(
note=str(evidence.get("note") or evidence.get("reasonNote") or ""),
reasonVersion=evidence.get("reasonVersion"),
dictionary=evidence.get("dictionary"),
discardedAt=str(evidence.get("discardedAt") or evidence.get("at") or ""),
)
return result
def _part_index_discarded_slice(
row: dict[str, Any],
source_root: pathlib.Path,
*,
classification_v4: bool = False,
) -> dict[str, Any]:
"""Classify a discarded interval without shipping its media or old text.
History of prior descriptions stays internal: the acceptance contract keeps
it as review evidence, not as part of the external deliverable.
"""
slice_id = str(row.get("sliceId") or "")
declared = str(row.get("deliveryDisposition") or "")
evidence = row.get("discardEvidence") if isinstance(row.get("discardEvidence"), dict) else {}
if not str(evidence.get("reason") or "").strip():
raise RuntimeError(f"discarded slice {slice_id} has no reason evidence")
relative = pathlib.PurePosixPath(str(row.get("directory") or ""))
if relative.is_absolute() or ".." in relative.parts or not relative.parts:
raise RuntimeError("unsafe accepted slice directory")
source_slice = source_root / pathlib.Path(*relative.parts)
if not source_slice.is_dir():
raise RuntimeError("accepted slice manifest contains an unavailable slice directory")
synchronization_path = source_slice / "synchronized-slice.json"
if not synchronization_path.is_file():
raise RuntimeError(f"accepted slice {slice_id} has no synchronized-slice.json")
try:
synchronization = json.loads(synchronization_path.read_text(encoding="utf-8"))
except (json.JSONDecodeError, UnicodeDecodeError) as error:
raise RuntimeError(f"accepted slice {slice_id} synchronized-slice.json is not valid JSON") from error
if not isinstance(synchronization, dict):
raise RuntimeError(f"accepted slice {slice_id} synchronized-slice.json is not an object")
recorded = str(synchronization.get("deliveryDisposition") or declared)
if recorded != declared:
raise RuntimeError(f"accepted slice {slice_id} disposition disagrees with its synchronization evidence")
start = _optional_float(row.get("startSecond")) or 0.0
end = _optional_float(row.get("endSecond")) or 0.0
return {
"sliceId": slice_id,
"sliceName": str(row.get("sliceName") or ""),
"taskSplit": {
"startSecond": start,
"endSecond": end,
"startTimestampUs": int(row["startTimestampUs"]) if row.get("startTimestampUs") is not None else None,
"endTimestampUs": int(row["endTimestampUs"]) if row.get("endTimestampUs") is not None else None,
"semantics": "half-open",
},
"classification": {
"deliveryDisposition": declared,
"discardEvidence": _part_index_discard_evidence(evidence, classification_v4=classification_v4),
},
"segments": [],
}
def _part_index_calibration_refs(inputs: list[dict[str, Any]]) -> list[dict[str, Any]]:
"""Reference calibration honestly instead of copying it into a delivery tree.
The part index records where calibration lives and its checksum; the bytes
stay in the accepted materialization revision that this index pins.
"""
refs: list[dict[str, Any]] = []
seen: set[str] = set()
for artifact in _sidecar_artifacts(inputs, {"calibrations"}):
name = str(artifact.get("name") or "").strip()
if not name or name in seen:
continue
seen.add(name)
path = str(artifact.get("path") or "").strip()
digest = str(artifact.get("sha256") or (artifact.get("metadata") or {}).get("sha256") or "").strip().lower()
if path and not _SHA.match(digest):
try:
digest = _sha256_file(pathlib.Path(path))
except OSError as error:
raise RuntimeError(f"calibration file is unavailable: {name}") from error
if not _SHA.match(digest):
raise RuntimeError(f"calibration file has no verifiable checksum: {name}")
size_bytes = int(artifact.get("sizeBytes") or 0)
if path and not size_bytes:
try:
size_bytes = pathlib.Path(path).stat().st_size
except OSError:
size_bytes = 0
# `path` is a logical delivery-relative location, matching the directory
# form's packages-manifest. An absolute workspace path would leak the
# worker layout into a customer-facing document.
refs.append({"name": name, "path": f"calibration/{name}", "sha256": digest, "bytes": size_bytes})
if not refs:
raise RuntimeError("part index delivery requires camera/IMU calibration files")
return refs
def _emit_part_index(
run_id: str,
node_id: str,
output: pathlib.Path,
node_data: dict[str, Any],
helpers: HelperMap,
payload_bytes: bytes,
) -> list[dict[str, Any]]:
"""Emit the part index as a single file artifact.
The artifact path is the deliverable itself: the worker publishes exactly
this file into the frozen capture delivery destination. The directory is
only a private staging area so a concurrently written node output cannot be
captured by accident. Byte content never carries a build timestamp, so a
retry of the same accepted revision republishes identical bytes.
"""
staging = output / "part-index"
staging.mkdir(parents=True, exist_ok=True)
path = staging / _PART_INDEX_FILE
path.write_bytes(payload_bytes)
return [
helpers["build_artifact"](
run_id,
node_id,
path,
"json",
metadata={"mimeType": "application/json", "sha256": _sha256_file(path)},
output=_output(node_data, helpers, "deliveryPartIndex"),
)
]
def _description_status(actions: list[dict[str, Any]]) -> str:
"""Describe a kept slice without reintroducing the internal annotation state.
``empty_confirmed`` keeps its platform meaning: no description was written
and the submitter confirmed that as a deliberate semantic blank.
"""
if any(not action.get("isInvalid") and str(action.get("description") or "").strip() for action in actions):
return "described"
if actions and all(bool(action.get("isInvalid")) for action in actions):
return "invalid_only"
return "empty_confirmed"
def _v4_tags(selection: Any, kind: str) -> list[str]:
if not isinstance(selection, dict) or selection.get("kind") != kind or not str(selection.get("id") or "").strip() or type(selection.get("version")) is not int or selection["version"] < 1 or not str(selection.get("name") or "").strip():
raise RuntimeError(f"v4 missing frozen {kind} dictionary; confirm historical classification before delivery")
tags = selection.get("tags")
if not isinstance(tags, list) or not tags or any(not isinstance(tag, str) or not tag.strip() or tag != tag.strip() for tag in tags) or len(set(tags)) != len(tags):
raise RuntimeError(f"v4 missing frozen {kind} tags; confirm classification before delivery")
return list(tags)
def _v4_original_sources(manifest, capture_id, part_id, capture_prefix):
source = manifest.get("originalSource")
if not isinstance(source, dict) or source.get("provider") != "BOS" or not str(source.get("bucket") or "").strip():
raise RuntimeError("v4 requires frozen original BOS source selection; workspace paths cannot identify original data")
prefix = str(source.get("prefix") or "")
part_prefix = str(source.get("partPrefix") or "")
if prefix != capture_prefix or part_prefix != prefix + "/" + part_id or source.get("captureUnit") != capture_id + "/" + part_id:
raise RuntimeError("v4 original source identity disagrees with accepted capture/part")
if not prefix or str(pathlib.PurePosixPath(prefix)) != prefix or pathlib.PurePosixPath(prefix).is_absolute() or ".." in pathlib.PurePosixPath(prefix).parts or any(c in prefix for c in ("\\", "\x00")):
raise RuntimeError("unsafe v4 original source prefix")
keys = source.get("objectKeys")
if not isinstance(keys, list) or not keys or any(not isinstance(key, str) for key in keys) or len(set(keys)) != len(keys):
raise RuntimeError("v4 requires an unambiguous original object selection")
files = {}
cap, part = re.escape(capture_id), re.escape(part_id)
patterns = {
"leftVideo": rf"{part}/{cap}_camera_left_{part}(?:_[a-z0-9_]+)?\.(?:mp4|mov|mkv)",
"rightVideo": rf"{part}/{cap}_camera_right_{part}(?:_[a-z0-9_]+)?\.(?:mp4|mov|mkv)",
"leftPts": rf"{part}/{cap}_camera_left_{part}(?:_[a-z0-9_]+)?_pts\.csv",
"rightPts": rf"{part}/{cap}_camera_right_{part}(?:_[a-z0-9_]+)?_pts\.csv",
"imu": rf"{part}/{cap}_imu_{part}\.csv",
"cameraCalibration": rf"{cap}_calibration_camera\.yaml",
"imuCalibration": rf"{cap}_calibration_imu\.yaml",
"metadata": rf"meta_{cap}\.json",
}
for key in keys:
if not key.startswith(prefix + "/") or str(pathlib.PurePosixPath(key)) != key or ".." in pathlib.PurePosixPath(key).parts or any(c in key for c in ("\\", "\x00")):
raise RuntimeError("unsafe v4 original source object")
relative = key[len(prefix) + 1:]
if "/" in relative and not relative.startswith(part_id + "/"):
raise RuntimeError("v4 original selection contains another part")
for role, pattern in patterns.items():
if re.fullmatch(pattern, relative, re.IGNORECASE):
if role in files: raise RuntimeError(f"ambiguous v4 original {role} selection")
files[role] = {"path": relative}
missing = sorted(set(patterns) - files.keys())
if missing: raise RuntimeError("v4 missing original files: " + ", ".join(missing))
return {"provider": "BOS", "bucket": source["bucket"], "prefix": prefix, "partPrefix": part_prefix,
"snapshotFingerprint": str(source.get("snapshotFingerprint") or ""), "files": files}
def _v4_number(value, label):
if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value):
raise RuntimeError(f"v4 missing or invalid {label}")
return float(value)
def _v4_timestamp(value, label):
if type(value) is not int or value <= 0: raise RuntimeError(f"v4 missing or invalid {label}")
return value
def _v4_consumer_payload(payload, manifest, source_root):
"""Project immutable accepted facts into a self-contained consumer contract.
No dictionary lookup, source media reads, transcoding or BOS writes here.
Hardware PTS are authoritative; media seconds are explicitly named and never
used to manufacture missing hardware timestamps.
"""
if not isinstance(manifest, dict): raise RuntimeError("v4 requires accepted source manifest")
original = _v4_original_sources(manifest, payload["capture"]["captureId"], payload["partId"], payload["capture"]["prefix"])
payload["originalSource"] = original
payload["consumerContract"] = "droboticflow.classification-consumer/v1"
payload["timeBases"] = {"taskSplitSeconds": "original_left_video", "segmentSeconds": "slice_left_video",
"segmentPartSeconds": "original_left_video", "timestampUs": "original_hardware_pts",
"interval": "half-open", "frameRanges": "zero-based-half-open"}
payload["pathBases"] = {"sources": "original_capture", "sourceMetadata": "original_capture", "calibration": "original_capture"}
# Workspace sources are private transport references, not the original files.
payload["sources"] = {kind: original["files"][kind] for kind in ("leftVideo", "rightVideo", "leftPts", "rightPts", "imu")}
payload["sourceMetadata"]["path"] = original["files"]["metadata"]["path"]
for item in payload["calibration"]:
# Bind by actual calibration kind, not input ordering.
kind = "imuCalibration" if "imu" in item["name"].lower() else "cameraCalibration" if "camera" in item["name"].lower() else ""
if not kind: raise RuntimeError("v4 unknown calibration kind")
item["path"] = original["files"][kind]["path"]
rows = {str(row["sliceId"]): row for row in manifest["items"]}
if len(rows) != len(manifest["items"]): raise RuntimeError("v4 duplicate slice identities")
for item in payload["slices"] + payload["discardedSlices"]:
split = item["taskSplit"]
start, end = (_v4_number(split[k], k) for k in ("startSecond", "endSecond"))
first, last = (_v4_timestamp(split[k], k) for k in ("startTimestampUs", "endTimestampUs"))
if start < 0 or end <= start or last <= first: raise RuntimeError("v4 invalid accepted slice range")
row = rows[item["sliceId"]]
sync = json.loads((source_root / row["directory"] / "synchronized-slice.json").read_text())
seconds, stamps = sync.get("boundarySeconds"), sync.get("boundaryTimestampUs")
# A continuous annotation is not proof of its relation to media seconds.
# Require the accepted revision's mapping for kept and discarded ranges;
# never infer hardware PTS from duration, cadence, or action endpoints.
if not isinstance(seconds, list) or not isinstance(stamps, list) or len(seconds) < 2 or len(seconds) != len(stamps):
raise RuntimeError("v4 missing or invalid hardware boundary mapping")
seconds = [_v4_number(value, "boundary") for value in seconds]
stamps = [_v4_timestamp(value, "boundary timestamp") for value in stamps]
if (abs(seconds[0]) > 1e-7 or abs(seconds[-1] - (end-start)) > 1e-7 or
stamps[0] != first or stamps[-1] != last or
any(a >= b for a, b in zip(seconds, seconds[1:])) or
any(a >= b for a, b in zip(stamps, stamps[1:]))):
raise RuntimeError("v4 invalid hardware boundary mapping")
window = sync.get("window")
if (not isinstance(window, dict) or window.get("semantics") != "half-open" or
_v4_timestamp(window.get("startTimestampUs"), "synchronization window start") != first or
_v4_timestamp(window.get("endTimestampUs"), "synchronization window end") != last):
raise RuntimeError("v4 boundary mapping disagrees with frozen synchronization window")
if item["classification"]["deliveryDisposition"] == "discard":
item["sliceName"] = ""
evidence = item["classification"]["discardEvidence"]
selected = evidence.get("dictionary")
if selected is not None:
if (not isinstance(selected, dict) or selected.get("kind") != "discard_reason" or
not selected.get("id") or not selected.get("name") or
type(selected.get("version")) is not int or selected["version"] < 1):
raise RuntimeError("v4 invalid frozen discard dictionary")
for alias, field in (("reasonLabelId", "id"), ("reasonName", "name"), ("reasonVersion", "version")):
if evidence.get(alias) not in (None, "", 0, selected[field]):
raise RuntimeError("v4 discard reason disagrees with frozen dictionary")
evidence[alias] = selected[field]
continue
parent_tags = _v4_tags(item["classification"].get("dictionary"), "slice")
item["classification"]["tags"] = parent_tags
def timestamp(second):
hits = [stamps[i] for i, value in enumerate(seconds) if abs(value - second) < 1e-7]
if len(hits) != 1: raise RuntimeError("v4 action boundary has no original PTS mapping")
return hits[0]
actions = []
for action in item["segments"]:
a = _v4_number(action.get("clipStartMs"), "action clipStartMs") / 1000
b = _v4_number(action.get("clipEndMs"), "action clipEndMs") / 1000
if a < -1e-7 or b <= a or b > end-start+1e-7: raise RuntimeError("v4 action escapes its parent slice")
ta, tb = (_v4_timestamp(action.get(k), k) for k in ("startTimestampUs", "endTimestampUs"))
if not first <= ta < tb <= last: raise RuntimeError("v4 action timestamps escape its parent slice")
if timestamp(a) != ta or timestamp(b) != tb: raise RuntimeError("v4 action seconds disagree with original PTS")
action.update(startSecond=a, endSecond=b, partStartSecond=start+a, partEndSecond=start+b)
own = action.get("dictionary")
action["tags"] = _v4_tags(own, "action") if own is not None else list(parent_tags)
action["tagSource"] = "action" if own is not None else "slice"
actions.append(action)
actions.sort(key=lambda a: a["startSecond"])
complete, previous = [], 0.0
def gap(a,b):
ta,tb=timestamp(a),timestamp(b)
return {"id":f"{item['sliceId']}:gap:{ta}:{tb}", "description":"", "isInvalid":False,
"contentKind":"gap_placeholder", "startSecond":a,"endSecond":b,
"clipStartMs":a*1000,"clipEndMs":b*1000,"partStartSecond":start+a,"partEndSecond":start+b,
"startTimestampUs":ta,"endTimestampUs":tb,"tags":list(parent_tags),"tagSource":"slice"}
for action in actions:
if action["startSecond"] < previous-1e-7: raise RuntimeError("v4 overlapping actions")
if action["startSecond"] > previous+1e-7: complete.append(gap(previous,action["startSecond"]))
complete.append(action);previous=action["endSecond"]
if previous < end-start-1e-7: complete.append(gap(previous,end-start))
if not complete: raise RuntimeError("v4 kept slice has no classified action coverage")
previous_stamp = first
for action in complete:
if action["startTimestampUs"] != previous_stamp or action["endTimestampUs"] <= previous_stamp:
raise RuntimeError("v4 action PTS coverage is discontinuous")
previous_stamp = action["endTimestampUs"]
if previous_stamp != last: raise RuntimeError("v4 action PTS coverage is incomplete")
item["segments"] = complete
counts = {kind:sum(a["contentKind"]==kind for a in complete) for kind in ("annotated","gap_placeholder","invalid_marked")}
item["classification"]["contentCounts"] = counts
item["classification"]["descriptionStatus"] = _description_status(complete)
if not counts["annotated"] and counts["invalid_marked"] and counts["gap_placeholder"]: item["classification"]["descriptionStatus"]="invalid_and_blank"
item["synchronization"]["rightBoundarySeconds"] = sync.get("rightBoundarySeconds", [])
def _emit_part_index_directory(run_id, node_id, output, node_data, helpers, payload, internal_audit=None, revision_manifest=None, source_root=None):
"""Use the established immutable publisher for versioned customer JSON.
V3 retains its historical sibling review file; v4 stores that audit in a
separate internal artifact before publishing the customer directory.
Legacy single-file publishers deliberately accept only v1/v2. A directory
artifact preserves their ownership/conditional-publication protocol without
teaching an old worker to misinterpret a new single-file schema.
"""
v4 = internal_audit is not None
capture = dict(payload["capture"])
prefix = pathlib.PurePosixPath(str(capture.get("prefix") or ""))
part_id = prefix.name
capture_id = prefix.parent.name
recorded = str(capture.get("captureId") or "")
if not re.fullmatch(r"part\d{4,}", part_id) or recorded not in {capture_id, capture_id + "/" + part_id}:
raise RuntimeError("v3 capture identity disagrees with the original part prefix")
if prefix.is_absolute() or ".." in prefix.parts or len(prefix.parts) < 3:
raise RuntimeError("unsafe v3 capture identity prefix")
capture.update(captureId=capture_id, prefix=str(prefix.parent))
payload.update(schemaVersion="droboticflow.delivery.part-index/v4" if v4 else "droboticflow.delivery.part-index/v3", capture=capture, partId=part_id)
payload["pathBases"] = {"sourceMetadata": "original_capture", "calibration": "original_capture", "sources": "workspace"}
payload["sourceMetadata"] = {"path": f"meta_{capture_id}.json"}
history = {
"schemaVersion": "droboticflow.delivery.review-history/v1", "captureId": capture_id,
"partId": part_id, "revision": payload["revision"],
"qualityReviews": payload["acceptance"].pop("qualityReviews", []),
}
payload["reviewHistory"] = {"path": "review-history.json", "pathBase": "part_package"}
if not v4:
payload["acceptance"]["finalAcceptance"].pop("confirmedByUserId", None)
for item in payload["calibration"]:
if pathlib.PurePosixPath(item["name"]).name != item["name"] or "\\" in item["name"]:
raise RuntimeError("unsafe calibration filename")
item["path"] = item["name"]
for item in payload["slices"] + payload["discardedSlices"]:
classification = item["classification"]
for key in ("taskLabel", "taskLabelId"):
if not str(classification.get(key) or "").strip():
classification.pop(key, None)
classification.get("discardEvidence", {}).pop("discardedByUserId", None)
item.get("synchronization", {}).pop("calibration", None)
for action in item["segments"]:
action.pop("status", None)
action["contentKind"] = "invalid_marked" if action["isInvalid"] else "described" if action["description"].strip() else "gap_placeholder"
if classification["deliveryDisposition"] == "keep":
counts = {kind: sum(action["contentKind"] == kind for action in item["segments"]) for kind in ("described", "invalid_marked", "gap_placeholder")}
classification["contentCounts"] = counts
if not counts["described"] and counts["invalid_marked"] and counts["gap_placeholder"]:
classification["descriptionStatus"] = "invalid_and_blank"
if v4:
if not isinstance(internal_audit.get("trace"), list):
raise RuntimeError("DELIVERY_JSON_V4 requires complete internal trace input")
if _output(node_data, helpers, "deliveryAudit") is None:
raise RuntimeError("DELIVERY_JSON_V4 requires an internal deliveryAudit output")
audit = {
"schemaVersion": "droboticflow.delivery.review-history/v2",
"captureId": capture_id, "partId": part_id, "revision": payload["revision"],
"acceptance": payload.pop("acceptance"), "lineage": payload.pop("lineage"),
"qualityReviews": internal_audit.get("qualityReviews", []),
"trace": internal_audit.get("trace", []),
"acceptedMaterializations": internal_audit.get("acceptedMaterializations", []),
}
audit["acceptance"]["finalAcceptance"] = internal_audit.get("finalAcceptance", {})
payload.pop("reviewHistory", None)
payload["capture"] = {"captureId": capture_id, "prefix": str(prefix.parent)}
for item in payload["slices"] + payload["discardedSlices"]:
classification = item["classification"]
# Blank descriptions retain the independently selected base class.
if classification.get("dictionary") is None:
classification.pop("dictionary", None)
evidence = classification.get("discardEvidence", {})
evidence.pop("discardedAt", None)
if evidence.get("dictionary") is None:
evidence.pop("dictionary", None)
counts = classification.get("contentCounts")
if counts is not None:
counts["annotated"] = counts.pop("described")
for action in item["segments"]:
if action["contentKind"] == "described": action["contentKind"] = "annotated"
for key in ("source", "confidence", "phrases", "labelId"):
action.pop(key, None)
if action.get("dictionary") is None: action.pop("dictionary", None)
audit["materializedSources"] = payload.get("sources", {})
_v4_consumer_payload(payload, revision_manifest, source_root)
body = (json.dumps(payload, ensure_ascii=False, sort_keys=True, indent=2) + "\n").encode("utf8")
audit["partSha256"] = hashlib.sha256(body).hexdigest()
if len(json.dumps(audit, ensure_ascii=False, indent=2).encode("utf8")) > 8 * 1024 * 1024:
raise RuntimeError("internal delivery audit exceeds 8 MiB; refusing incomplete export")
staging = pathlib.Path(tempfile.mkdtemp(prefix="part-index-v4-", dir=output))
(staging / "part.json").write_bytes(body)
# A sibling artifact stays in the internal run, never in the customer tree.
audit_artifact = helpers["write_json_artifact"](run_id, node_id, output, "review-history.json", audit, output=_output(node_data, helpers, "deliveryAudit"))
directory = helpers["build_virtual_artifact"](
run_id, node_id, "delivery.directory.index", str(staging), "file", 0,
data={"schemaVersion": "droboticflow.directory-index/v1", "presentation": "collection", "datasetType": "directory", "dataSource": "FILESYSTEM", "rootPath": str(staging), "sliceCount": len(payload["slices"]), "classificationOnly": True},
output=_output(node_data, helpers, "deliveryDirectory"))
return [directory, audit_artifact]
staging = pathlib.Path(tempfile.mkdtemp(prefix="part-index-v3-", dir=output))
for name, document in (("part.json", payload), ("review-history.json", history)):
(staging / name).write_text(json.dumps(document, ensure_ascii=False, sort_keys=True, indent=2) + "\n", encoding="utf8")
return [helpers["build_virtual_artifact"](
run_id, node_id, "delivery.directory.index", str(staging), "file", 0,
data={"schemaVersion": "droboticflow.directory-index/v1", "presentation": "collection", "datasetType": "directory", "dataSource": "FILESYSTEM", "rootPath": str(staging), "sliceCount": len(payload["slices"])},
output=_output(node_data, helpers, "deliveryDirectory"),
)]
def _part_index_slice(
row: dict[str, Any],
index: int,
source_slice: pathlib.Path,
calibration: list[dict[str, Any]],
pose_policy: dict[str, Any],
*,
classification_v4: bool = False,
) -> dict[str, Any]:
declared = str(row.get("deliveryDisposition") or "")
slice_id = str(row.get("sliceId") or f"slice-{index + 1:06d}")
start = _optional_float(row.get("startSecond")) or 0.0
end = _optional_float(row.get("endSecond")) or 0.0
annotation_path = source_slice / "annotation.json"
if not annotation_path.is_file():
raise RuntimeError(f"accepted slice {slice_id} has no annotation.json")
try:
annotation = json.loads(annotation_path.read_text(encoding="utf-8"))
except (json.JSONDecodeError, UnicodeDecodeError) as error:
raise RuntimeError(f"accepted slice {slice_id} annotation.json is not valid JSON") from error
if not isinstance(annotation, dict):
raise RuntimeError(f"accepted slice {slice_id} annotation.json is not an object")
raw_actions = annotation.get("actions")
if raw_actions is None:
raw_actions = annotation.get("descriptions")
if raw_actions is None:
raw_actions = []
if not isinstance(raw_actions, list):
raise RuntimeError(f"accepted slice {slice_id} annotation actions are not a list")
actions: list[dict[str, Any]] = []
for action in raw_actions:
if not isinstance(action, dict):
raise RuntimeError(f"accepted slice {slice_id} has a malformed action segment")
start_us = action.get("startTimestampUs")
end_us = action.get("endTimestampUs")
actions.append({
"id": str(action.get("id") or ""),
"description": str(action.get("description") or ""),
"status": str(action.get("status") or ""),
"isInvalid": bool(action.get("isInvalid", False)),
"startTimestampUs": int(start_us) if start_us is not None else None,
"endTimestampUs": int(end_us) if end_us is not None else None,
"startSecond": _optional_float(action.get("clipStartMs")) / 1000.0 if _optional_float(action.get("clipStartMs")) is not None else None,
"endSecond": _optional_float(action.get("clipEndMs")) / 1000.0 if _optional_float(action.get("clipEndMs")) is not None else None,
"clipStartMs": _optional_float(action.get("clipStartMs")),
"clipEndMs": _optional_float(action.get("clipEndMs")),
"labelId": str(action.get("descriptionTemplateId") or ""),
**({"dictionary": action.get("dictionary")} if classification_v4 else {}),
"phrases": [str(item) for item in action.get("phrases", [])] if isinstance(action.get("phrases"), list) else [],
"source": str(action.get("source") or ""),
"confidence": _optional_float(action.get("confidence")),
})
synchronization_path = source_slice / "synchronized-slice.json"
if not synchronization_path.is_file():
raise RuntimeError(f"accepted slice {slice_id} has no synchronized-slice.json")
try:
synchronization = json.loads(synchronization_path.read_text(encoding="utf-8"))
except (json.JSONDecodeError, UnicodeDecodeError) as error:
raise RuntimeError(f"accepted slice {slice_id} synchronized-slice.json is not valid JSON") from error
if not isinstance(synchronization, dict):
raise RuntimeError(f"accepted slice {slice_id} synchronized-slice.json is not an object")
# A disposition that disagrees with the pinned review revision must fail
# closed instead of silently exporting the wrong classification.
recorded = str(synchronization.get("deliveryDisposition") or declared)
if recorded != declared:
raise RuntimeError(f"accepted slice {slice_id} disposition disagrees with its synchronization evidence")
entry: dict[str, Any] = {
"sliceId": slice_id,
"sliceName": str(row.get("sliceName") or ""),
"taskSplit": {
"startSecond": start,
"endSecond": end,
"startTimestampUs": int(row["startTimestampUs"]) if row.get("startTimestampUs") is not None else None,
"endTimestampUs": int(row["endTimestampUs"]) if row.get("endTimestampUs") is not None else None,
"semantics": "half-open",
},
"classification": {
"deliveryDisposition": declared,
"taskLabel": str(synchronization.get("taskLabel") or ""),
"taskLabelId": str(synchronization.get("taskLabelId") or ""),
**({"dictionary": synchronization.get("dictionary")} if classification_v4 else {}),
"descriptionStatus": _description_status(actions),
},
"segments": actions,
"synchronization": {
"maxStereoAlignmentErrorUs": synchronization.get("maxStereoAlignmentErrorUs"),
"boundaryContract": str(synchronization.get("boundaryContract") or ""),
"boundaryTimestampUs": [int(value) for value in synchronization.get("boundaryTimestampUs", [])] if isinstance(synchronization.get("boundaryTimestampUs"), list) else [],
"calibration": [
{"name": item["name"], "path": item["path"], "sha256": item["sha256"], "bytes": item["bytes"]}
for item in calibration
],
},
}
if declared == "discard":
evidence = row.get("discardEvidence") if isinstance(row.get("discardEvidence"), dict) else {}
if not str(evidence.get("reason") or "").strip():
raise RuntimeError(f"discarded slice {slice_id} has no reason evidence")
# Discard classification is exported deliberately: downstream packaging
# must know why an interval is excluded.
entry["classification"]["discardEvidence"] = _part_index_discard_evidence(evidence, classification_v4=classification_v4)
# Pose frames deliberately stay out of the index: the customer contract for
# this mode is the split information, and embedded per-frame pose would
# make a multi-megabyte part.json out of a kilobyte index. The per-slice
# poseDelivery decision below tells downstream which segments carry pose
# so it can resolve frames from the pinned materialization revision.
entry["classification"]["poseDelivery"] = {
"headpose": "include" if pose_policy.get("headpose") == "include" else "exclude",
"handpose": "include" if pose_policy.get("handpose") == "include" else "exclude",
}
return entry
def _build_part_index(
revision_manifest: dict[str, Any],
coverage: dict[str, Any],
kept_slices: list[dict[str, Any]],
source_root: pathlib.Path,
calibration: list[dict[str, Any]],
pose_policy: dict[str, Any],
summary_payload: dict[str, Any],
final_acceptance: dict[str, Any],
capture_record: dict[str, Any],
lineage: dict[str, Any],
discarded_slices: list[dict[str, Any]],
*,
classification_v4: bool = False,
) -> tuple[dict[str, Any], bytes]:
slices: list[dict[str, Any]] = []
for index, row in enumerate(kept_slices):
if not isinstance(row, dict):
raise RuntimeError("invalid accepted slice entry")
relative = pathlib.PurePosixPath(str(row.get("directory") or ""))
if relative.is_absolute() or ".." in relative.parts or not relative.parts:
raise RuntimeError("unsafe accepted slice directory")
source_slice = source_root / pathlib.Path(*relative.parts)
if not source_slice.is_dir():
raise RuntimeError("accepted slice manifest contains an unavailable slice directory")
slices.append(_part_index_slice(row, index, source_slice, calibration, pose_policy, classification_v4=classification_v4))
quality_reviews = summary_payload.get("qualityReviews") if isinstance(summary_payload.get("qualityReviews"), list) else []
exported_reviews = [
{key: review[key] for key in _QUALITY_REVIEW_EXPORT_FIELDS if key in review}
for review in quality_reviews
if isinstance(review, dict)
]
payload: dict[str, Any] = {
"schemaVersion": _PART_INDEX_SCHEMA,
"datasetType": "fanyu-accepted-slice-part-index",
# The worker publishes this file unchanged into the part's frozen
# delivery destination and needs stable routing facts, not a filename
# convention it has to re-derive.
"delivery": {
"kind": "part_index",
"fileName": _PART_INDEX_FILE,
"artifactName": _PART_INDEX_ARTIFACT,
},
"capture": capture_record,
"revision": revision_manifest.get("revision"),
"coverage": coverage,
"slices": slices,
"discardedSlices": [
_part_index_discarded_slice(row, source_root, classification_v4=classification_v4)
for row in discarded_slices
if isinstance(row, dict)
],
"deliveryClassification": {
"keptSliceCount": len(slices),
"discardedSliceCount": len(discarded_slices),
"keptDurationSeconds": sum(float(item["taskSplit"]["endSecond"]) - float(item["taskSplit"]["startSecond"]) for item in slices),
"discardedDurationSeconds": sum(
(_optional_float(row.get("endSecond")) or 0.0) - (_optional_float(row.get("startSecond")) or 0.0)
for row in discarded_slices
if isinstance(row, dict)
),
},
"calibration": calibration,
"poseDelivery": pose_policy,
"acceptance": {
"sampling": {
"sampled": bool(final_acceptance.get("sampled", True)),
"decision": str(final_acceptance.get("samplingDecision") or "selected"),
"probability": final_acceptance.get("samplingProbability"),
"policyRevision": final_acceptance.get("samplingPolicyRevision"),
"randomValue": final_acceptance.get("samplingRandomValue"),
"decidedAt": final_acceptance.get("samplingDecidedAt"),
},
"finalAcceptance": {key: final_acceptance[key] for key in _ACCEPTANCE_EXPORT_FIELDS if key in final_acceptance},
"qualityReviews": exported_reviews,
},
"lineage": lineage,
}
body = (json.dumps(payload, ensure_ascii=False, indent=2, sort_keys=True) + "\n").encode("utf-8")
return payload, body
def _copy_calibrations(inputs: list[dict[str, Any]], packages_root: pathlib.Path, output: pathlib.Path, helpers: HelperMap) -> list[dict[str, Any]]:
destination = packages_root / "calibration"
result: list[dict[str, Any]] = []
seen: set[str] = set()
for artifact in _sidecar_artifacts(inputs, {"calibrations"}):
name = str(artifact.get("name") or "").strip()
if not name or name in seen:
continue
seen.add(name)
source = _materialize_input_file(artifact, output / "_inputs", helpers)
destination.mkdir(parents=True, exist_ok=True)
target = destination / name
shutil.copy2(source, target)
result.append({"name": name, "path": f"calibration/{name}", "sha256": _sha256_file(target), "bytes": target.stat().st_size})
if not result:
raise RuntimeError("synchronized delivery requires camera/IMU calibration files")
return result
def _synchronized_segment(
item: dict[str, Any],
clip_id: str,
package_dir: pathlib.Path,
output: pathlib.Path,
start: float,
end: float,
inputs: list[dict[str, Any]],
right_videos: list[dict[str, Any]],
helpers: HelperMap,
) -> tuple[pathlib.Path, dict[str, Any], dict[str, Any]]:
collection_id = str(item.get("collectionId") or "").strip() or _camera_collection_id(_source_video_name(item))
right_artifact = _matching_right_video(item, right_videos)
if right_artifact is None:
raise RuntimeError(f"accepted segment {clip_id} has no matching right-camera video")
left_pts_artifact = _matching_sidecar(collection_id, _sidecar_artifacts(inputs, {"leftTimestamps"}), "left")
right_pts_artifact = _matching_sidecar(collection_id, _sidecar_artifacts(inputs, {"rightTimestamps"}), "right")
imu_artifact = _matching_sidecar(collection_id, _sidecar_artifacts(inputs, {"imu"}), "imu")
left_pts_path = _materialize_input_file(left_pts_artifact, output / "_inputs", helpers)
right_pts_path = _materialize_input_file(right_pts_artifact, output / "_inputs", helpers)
imu_path = _materialize_input_file(imu_artifact, output / "_inputs", helpers)
left_pts = _read_pts(left_pts_path)
right_pts = _read_pts(right_pts_path)
imu_rows = _read_imu(imu_path)
left_source = _materialize_left_source(item, output / "_inputs", helpers)
right_source = _materialize_input_video(right_artifact, output / "_inputs", helpers)
imu_first, imu_last = int(imu_rows[0]["timestamp_us"]), int(imu_rows[-1]["timestamp_us"])
if max(left_pts[0], right_pts[0], imu_first) > min(left_pts[-1], right_pts[-1], imu_last):
left_pts_artifact = _absolute_pts_sibling_artifact(collection_id, "left", str(item.get("clipPath") or item.get("clipName") or left_source.name), inputs)
right_pts_artifact = _absolute_pts_sibling_artifact(collection_id, "right", str(right_artifact.get("name") or right_source.name), inputs)
left_pts_path = _materialize_input_file(left_pts_artifact, output / "_inputs", helpers)
right_pts_path = _materialize_input_file(right_pts_artifact, output / "_inputs", helpers)
left_pts = _read_pts(left_pts_path)
right_pts = _read_pts(right_pts_path)
if _ffprobe_frame_count(left_source) != len(left_pts):
raise RuntimeError("left-camera decoded frame count does not match left PTS rows")
if _ffprobe_frame_count(right_source) != len(right_pts):
raise RuntimeError("right-camera decoded frame count does not match right PTS rows")
common_start = max(left_pts[0], right_pts[0], imu_first)
common_end = min(left_pts[-1], right_pts[-1], imu_last)
target_start_us = common_start + round(start * 1_000_000)
target_end_us = common_start + round(end * 1_000_000)
if target_start_us < common_start or target_end_us > common_end or target_end_us <= target_start_us:
raise RuntimeError("final segment is outside the common left/right/IMU hardware timestamp range")
left_start, left_end = bisect.bisect_left(left_pts, target_start_us), bisect.bisect_left(left_pts, target_end_us)
right_start, right_end = bisect.bisect_left(right_pts, target_start_us), bisect.bisect_left(right_pts, target_end_us)
left_destination = package_dir / str(item.get("clipName") or f"{clip_id}_left.mp4")
right_destination = package_dir / f"{clip_id}_right.mp4"
_write_frame_segment(left_source, left_destination, left_start, left_end)
_write_frame_segment(right_source, right_destination, right_start, right_end)
if _ffprobe_frame_count(left_destination) != left_end - left_start or _ffprobe_frame_count(right_destination) != right_end - right_start:
raise RuntimeError("synchronized output frame count does not match sliced PTS rows")
left_pts_manifest = _write_pts_slice(package_dir / f"{clip_id}_left_pts.csv", left_pts, left_start, left_end)
right_pts_manifest = _write_pts_slice(package_dir / f"{clip_id}_right_pts.csv", right_pts, right_start, right_end)
left_pts_manifest["source"] = {"name": left_pts_path.name, "sha256": _sha256_file(left_pts_path)}
right_pts_manifest["source"] = {"name": right_pts_path.name, "sha256": _sha256_file(right_pts_path)}
imu_manifest = _write_imu_slice(package_dir / f"{clip_id}_imu.csv", imu_rows, target_start_us, target_end_us)
left_video = {"name": left_destination.name, "sha256": _sha256_file(left_destination), "bytes": left_destination.stat().st_size, "cameraSide": "left", "frameCount": left_end - left_start}
right_video = {"name": right_destination.name, "sha256": _sha256_file(right_destination), "bytes": right_destination.stat().st_size, "cameraSide": "right", "frameCount": right_end - right_start, "sourceVideo": str(right_artifact.get("name") or right_source.name)}
alignment_values = [left_pts[left_start], right_pts[right_start], int(imu_manifest["firstTimestampUs"]), left_pts[left_end - 1], right_pts[right_end - 1], int(imu_manifest["lastTimestampUs"])]
max_alignment_error_us = max(abs(value - target_start_us) for value in alignment_values[:3])
synchronized = {
"schemaVersion": "droboticflow.synchronized-slice/v1",
"collectionId": collection_id,
"window": {"startTimestampUs": target_start_us, "endTimestampUs": target_end_us, "semantics": "half-open"},
"commonRange": {"startTimestampUs": common_start, "endTimestampUs": common_end},
"left": {"video": left_video, "pts": left_pts_manifest},
"right": {"video": right_video, "pts": right_pts_manifest},
"imu": imu_manifest,
"maxStartAlignmentErrorUs": max_alignment_error_us,
}
return left_destination, right_video, synchronized
def _timestamped_annotation(annotation: dict[str, Any], synchronized: dict[str, Any] | None) -> dict[str, Any]:
"""Bind accepted JSON descriptions to the authoritative hardware-time window."""
result = json.loads(json.dumps(annotation, ensure_ascii=False)) if annotation else {}
if synchronized is None:
return result
window = synchronized.get("window") if isinstance(synchronized.get("window"), dict) else {}
start_us = int(window.get("startTimestampUs") or 0)
end_us = int(window.get("endTimestampUs") or 0)
if start_us <= 0 or end_us <= start_us:
raise RuntimeError("timestamped annotation requires a valid synchronized hardware-time window")
source_schema = str(result.get("schemaVersion") or "").strip()
description_contract = isinstance(result.get("descriptions"), list)
result["schemaVersion"] = (
"droboticflow.timestamped-description/v1"
if description_contract
else "droboticflow.timestamped-annotation/v1"
)
if source_schema:
result["sourceSchemaVersion"] = source_schema
result["timebase"] = {
"kind": "absolute_hardware",
"unit": "us",
"startTimestampUs": start_us,
"endTimestampUs": end_us,
"startTimestampMs": start_us / 1000.0,
"endTimestampMs": end_us / 1000.0,
"semantics": "half-open",
}
actions = (
result.get("descriptions")
if description_contract
else result.get("actions") if isinstance(result.get("actions"), list) else []
)
unified = result.get("boundaryContract") == "hardware-frame-v1"
boundary_ids = set(synchronized.get("boundaryTimestampUs") or [])
cursor = start_us
if unified and (not actions or start_us not in boundary_ids or end_us not in boundary_ids):
raise RuntimeError("unified annotation requires continuous descriptions and shared boundaries")
for action in actions:
if not isinstance(action, dict):
continue
clip_start_seconds = float(action.get("start") or float(action.get("clipStartMs") or 0.0) / 1000.0)
clip_end_seconds = float(action.get("end") or float(action.get("clipEndMs") or 0.0) / 1000.0)
if clip_start_seconds < 0 or clip_end_seconds <= clip_start_seconds:
raise RuntimeError("timestamped annotation contains an invalid clip-relative action range")
if unified:
action_start_us = action.get("startTimestampUs")
action_end_us = action.get("endTimestampUs")
if (type(action_start_us) is not int or type(action_end_us) is not int
or action_start_us not in boundary_ids or action_end_us not in boundary_ids
or action_start_us != cursor):
raise RuntimeError("unified annotation boundaries must be consecutive hardware frame boundaries")
cursor = action_end_us
else:
action_start_us = start_us + round(clip_start_seconds * 1_000_000)
action_end_us = start_us + round(clip_end_seconds * 1_000_000)
if action_start_us < start_us or action_end_us > end_us or action_end_us <= action_start_us:
raise RuntimeError("timestamped annotation action is outside the synchronized half-open window")
action["clipStartMs"] = clip_start_seconds * 1000.0
action["clipEndMs"] = clip_end_seconds * 1000.0
action["startTimestampUs"] = action_start_us
action["endTimestampUs"] = action_end_us
action["startTimestampMs"] = action_start_us / 1000.0
action["endTimestampMs"] = action_end_us / 1000.0
if unified and cursor != end_us:
raise RuntimeError("unified annotation does not cover the complete slice")
if unified and description_contract:
result["actions"] = actions
return result
def _run_fanyu_v5(run_id: str, node_id: str, output_dir: Any, node_data: dict[str, Any], inputs: list[dict[str, Any]], helpers: HelperMap) -> list[dict[str, Any]]:
output = pathlib.Path(output_dir)
output.mkdir(parents=True, exist_ok=True)
params = helpers["hyperparams"](node_data)
require_headpose = _bool(params, "REQUIRE_HEADPOSE", False)
require_handpose = _bool(params, "REQUIRE_HANDPOSE", False)
require_stereo_delivery = _bool(params, "REQUIRE_STEREO_DELIVERY", False)
pose_free = _bool(params, "POSE_FREE", False)
require_final_acceptance = _bool(params, "REQUIRE_FINAL_ACCEPTANCE", False)
generate_segment_mp4 = _bool(params, "GENERATE_SEGMENT_MP4", False)
synchronized_sidecars = _bool(params, "SYNCHRONIZED_SIDECARS", False)
allow_pose_exclusion = _bool(params, "ALLOW_POSE_EXCLUSION", False)
payloads = _payload_tree(_payloads_with_full_pose_manifests(inputs, output, helpers))
headpose = _first_payload(payloads, "droboticflow.headpose/v1")
handpose = _first_payload(payloads, "droboticflow.wilor.hand_pose_result/v1")
if pose_free and (headpose is not None or handpose is not None):
raise RuntimeError("pose-free v5 package rejects HeadPose and HandPose payloads")
if require_headpose and not allow_pose_exclusion and (headpose is None or not headpose.get("enabled") or not isinstance(headpose.get("frames"), list)):
raise RuntimeError("package requires a real Headpose manifest with frames")
if require_handpose and not allow_pose_exclusion and (
handpose is None
or handpose.get("enabled") is False
or not _pose_frames(handpose, "handpose")
):
raise RuntimeError("package requires a real WiLoR HandPose manifest with frames")
right_videos = _right_video_artifacts(inputs)
if require_stereo_delivery and not right_videos:
raise RuntimeError("stereo delivery requires a right-camera rectified video")
accepted = next((payload for payload in payloads if isinstance(payload.get("items"), list) and ("annotationCount" in payload or payload.get("schemaVersion") == "droboticflow.annotation.accepted-partition/v1")), None)
if accepted is None:
raise RuntimeError("package requires an accepted annotation partition")
accepted_items = [item for item in accepted.get("items", []) if isinstance(item, dict)]
if require_stereo_delivery:
# Historical v5.7 workers could accidentally turn the HeadPose rendered
# evidence video into a human task with clipId ``<nil>_final_001`` and
# no camera collection. Stereo delivery must contain only real Qwen
# clips that can be paired to a right-camera collection.
accepted_items = [
item
for item in accepted_items
if str(item.get("collectionId") or "").strip() not in {"", "<nil>"}
and "<nil>" not in str(item.get("clipId") or "")
]
if not accepted_items:
raise RuntimeError("stereo delivery has no accepted Qwen clip with a camera collection")
package_items: list[dict[str, Any]] = []
binding = helpers["output_binding"](node_data)
calibration_refs = _copy_calibrations(inputs, output / "packages", output, helpers) if synchronized_sidecars else []
package_pose_policy: dict[str, Any] | None = None
for index, item in enumerate(accepted_items):
acceptance_evidence: dict[str, Any] = {}
if require_final_acceptance:
acceptance_evidence = _validate_final_acceptance(item)
pose_policy = acceptance_evidence.get("poseDelivery") if isinstance(acceptance_evidence.get("poseDelivery"), dict) else {}
if allow_pose_exclusion:
if pose_policy.get("headpose") not in {"include", "exclude"} or pose_policy.get("handpose") not in {"include", "exclude"}:
raise RuntimeError("v5.8 final acceptance must decide HeadPose and HandPose inclusion")
if package_pose_policy is None:
package_pose_policy = pose_policy
elif package_pose_policy != pose_policy:
raise RuntimeError("v5.8 package items contain conflicting aggregate pose delivery decisions")
include_headpose = not allow_pose_exclusion or pose_policy.get("headpose") == "include"
include_handpose = not allow_pose_exclusion or pose_policy.get("handpose") == "include"
clip_id = str(item.get("clipId") or f"segment-{index + 1:04d}").strip()
package_dir = output / "packages" / f"{clip_id}_package"
package_dir.mkdir(parents=True, exist_ok=True)
start = float(item.get("sourceStartSecond", item.get("startSecond", 0.0)))
end = float(item.get("sourceEndSecond", item.get("endSecond", 0.0)))
if not (0 <= start < end):
raise RuntimeError("accepted package item has invalid final source boundaries")
# 虚拟切片条目没有物理中间片段:无论是否显式要求 MP4,
# 都必须按源视频区间在打包阶段精确物化最终交付 MP4。
synchronized_manifest = None
right_video_manifest = None
if synchronized_sidecars:
video_path, right_video_manifest, synchronized_manifest = _synchronized_segment(item, clip_id, package_dir, output, start, end, inputs, right_videos, helpers)
elif generate_segment_mp4 or item.get("finalSegment") is True or item.get("virtualCut") is True:
video_path = _materialize_final_mp4(item, package_dir, helpers)
else:
source = pathlib.Path(str(item.get("clipPath", "")).strip())
if not source.is_file() or source.stat().st_size <= 0:
raise RuntimeError("legacy package input clip is unavailable")
video_path = package_dir / (str(item.get("clipName") or source.name))
shutil.copy2(source, video_path)
annotation = item.get("annotation") if isinstance(item.get("annotation"), dict) else {}
headpose_segment = _crop_pose(headpose, start, end, "headpose") if include_headpose and headpose else None
handpose_segment = _crop_pose(handpose, start, end, "handpose") if include_handpose and handpose and handpose.get("enabled", True) else None
if require_headpose and include_headpose and (headpose_segment is None or headpose_segment["frameCount"] <= 0):
raise RuntimeError("required Headpose has no frame inside the final half-open segment interval")
if require_handpose and include_handpose and (handpose_segment is None or handpose_segment["frameCount"] <= 0):
raise RuntimeError("required HandPose has no frame inside the final half-open segment interval")
right_video = None if synchronized_sidecars else _matching_right_video(item, right_videos)
if not synchronized_sidecars and right_video is not None:
right_source = _materialize_input_video(right_video, output, helpers)
right_destination = package_dir / f"{clip_id}_right.mp4"
right_video_manifest = _write_verified_segment(right_source, right_destination, start, end, helpers)
right_video_manifest["cameraSide"] = "right"
right_video_manifest["sourceVideo"] = str(right_video.get("name") or right_source.name)
right_data = right_video.get("data") if isinstance(right_video.get("data"), dict) else {}
right_video_manifest["transformChain"] = (
right_data.get("transformChain") if isinstance(right_data.get("transformChain"), list) else []
)
elif not synchronized_sidecars and require_stereo_delivery:
raise RuntimeError(f"accepted segment {clip_id} has no matching right-camera video")
annotation = _timestamped_annotation(annotation, synchronized_manifest)
helpers["write_json_artifact"](run_id, node_id, package_dir, "semantic.json", annotation, output=binding)
if synchronized_manifest is not None:
synchronized_manifest["calibration"] = calibration_refs
helpers["write_json_artifact"](run_id, node_id, package_dir, "synchronized-slice.json", synchronized_manifest, output=binding)
segment_manifest = {
"schemaVersion": "droboticflow.delivery.segment/v2",
"clipId": clip_id,
"video": {"name": video_path.name, "sha256": _sha256_file(video_path), "bytes": video_path.stat().st_size},
"sourceRangeSeconds": {"start": start, "end": end},
"clipRelativeRangeSeconds": {"start": float(item.get("startSecond", 0.0)), "end": float(item.get("endSecond", 0.0))},
"semantic": {
"file": "semantic.json",
"actionCount": len(annotation.get("descriptions", annotation.get("actions", []))),
},
"transformChain": item.get("transformChain", []) if isinstance(item.get("transformChain"), list) else [],
"finalAcceptance": item.get("finalAcceptance") if require_final_acceptance else None,
"poseDelivery": pose_policy if allow_pose_exclusion else None,
"synchronizedSlice": {"file": "synchronized-slice.json", "schemaVersion": "droboticflow.synchronized-slice/v1"} if synchronized_manifest is not None else None,
"calibration": calibration_refs,
}
segment_manifest["videos"] = {
"left": {**segment_manifest["video"], "cameraSide": "left"},
**({"right": right_video_manifest} if right_video_manifest else {}),
}
if headpose_segment is not None:
helpers["write_json_artifact"](run_id, node_id, package_dir, "headpose.json", headpose_segment, output=binding)
segment_manifest["headpose"] = {"file": "headpose.json", "frameCount": headpose_segment["frameCount"]}
if handpose_segment is not None:
helpers["write_json_artifact"](run_id, node_id, package_dir, "handpose.json", handpose_segment, output=binding)
segment_manifest["handpose"] = {"file": "handpose.json", "frameCount": handpose_segment["frameCount"]}
helpers["write_json_artifact"](run_id, node_id, package_dir, "segment.json", segment_manifest, output=binding)
source_video = _source_video_name(item)
quality = {"clip_id": clip_id, "source_video": source_video, **(item.get("quality", {}) if isinstance(item.get("quality"), dict) else {})}
package_items.append({"packageName": package_dir.name, "clipId": clip_id, "clipName": video_path.name, "rightClipName": right_video_manifest["name"] if right_video_manifest else "", "sourceVideo": source_video, "sourceRightVideo": right_video_manifest["sourceVideo"] if right_video_manifest else "", "stereo": right_video_manifest is not None, "storagePath": str(package_dir), "startSecond": start, "endSecond": end, "clipDuration": end - start, "duration": end - start, "fileCount": len([path for path in package_dir.iterdir() if path.is_file()]), "quality": quality, "annotation": annotation, "segmentManifest": segment_manifest})
if not package_items:
raise RuntimeError("package produced zero final segment packages")
manifest = {"schemaVersion": "droboticflow.delivery.manifest/v4" if synchronized_sidecars else "droboticflow.delivery.manifest/v3", "datasetType": "fanyu-v5-final-segments", "packageCount": len(package_items), "stereoDelivery": all(item["stereo"] for item in package_items), "headposeIncluded": headpose is not None and (not allow_pose_exclusion or (package_pose_policy or {}).get("headpose") == "include"), "handposeIncluded": handpose is not None and handpose.get("enabled", True) and (not allow_pose_exclusion or (package_pose_policy or {}).get("handpose") == "include"), "poseDelivery": package_pose_policy, "audioIncluded": False if synchronized_sidecars else None, "calibration": calibration_refs, "items": package_items, "trainingEnabled": False}
artifacts = [helpers["write_json_artifact"](run_id, node_id, output, "packages-manifest.json", manifest, output=binding)]
artifacts.extend(_collect_unique_package_artifacts(run_id, node_id, output / "packages", node_data, binding, helpers))
return artifacts
def _run_legacy(run_id: str, node_id: str, output_dir: Any, node_data: dict[str, Any], inputs: list[dict[str, Any]], helpers: HelperMap) -> list[dict[str, Any]]:
"""The pre-v5 contract, intentionally retained byte-for-byte in shape."""
payloads = helpers["payloads_from_inputs"](inputs)
params = helpers["hyperparams"](node_data)
require_headpose = _bool(params, "REQUIRE_HEADPOSE", False)
headpose = _first_payload(payloads, "droboticflow.headpose/v1")
handpose = _first_payload(payloads, "droboticflow.wilor.hand_pose_result/v1")
if require_headpose and (headpose is None or not headpose.get("enabled")):
raise RuntimeError("成品打包需要必选的 droboticflow.headpose/v1 结果")
headpose_enabled = bool(headpose and headpose.get("enabled"))
handpose_enabled = bool(handpose and handpose.get("enabled", True))
payload = helpers["first_payload_with_keys"](inputs, "annotationCount", "items")
if payload is None:
payload = helpers["first_payload_with_keys"](inputs, "clipCount", "items")
if payload is None:
raise RuntimeError("成品打包需要上游标注或目标裁剪结果输入")
output = pathlib.Path(output_dir)
clip_artifacts = {str(item.get("name", "")).strip(): item for item in inputs if str(item.get("name", "")).strip().lower().endswith(".mp4")}
archive_sources = payload.get("archiveSources", {}) if isinstance(payload.get("archiveSources"), dict) else {}
packages: list[dict[str, Any]] = []
binding = helpers["output_binding"](node_data)
for item in payload.get("items", []):
if not isinstance(item, dict):
continue
clip_name = str(item.get("clipName", "")).strip()
clip_id = str(item.get("clipId", "")).strip() or pathlib.Path(clip_name).stem
package_dir = output / "packages" / f"{clip_id}_package"
package_dir.mkdir(parents=True, exist_ok=True)
artifact = clip_artifacts.get(clip_name)
clip_path: pathlib.Path | None = None
if artifact is not None:
try:
clip_path = helpers["source_path_from_item"]({"source": helpers["source_ref_from_artifact"](artifact), "path": artifact.get("path", "")}, clip_name, output, archive_sources)
except RuntimeError:
clip_path = None
if clip_path is None:
direct = str(item.get("clipPath", "")).strip()
if direct and pathlib.Path(direct).exists():
clip_path = pathlib.Path(direct)
if clip_path is None:
clip_path = helpers["materialize_clip_from_source"](item, output, archive_sources)
if clip_path is not None and clip_path.exists():
shutil.copy2(clip_path, package_dir / clip_name)
quality = {"clip_id": clip_id, "source_video": item.get("sourceVideo", ""), **(item.get("quality", {}) if isinstance(item.get("quality"), dict) else {})}
annotation = item.get("annotation") if isinstance(item.get("annotation"), dict) else {}
if not annotation and isinstance(item.get("detections"), list):
annotation = {"type": "target_detections", "detectionMode": item.get("detectionMode", payload.get("detectionMode", "")), "targetLabels": item.get("targetLabels", payload.get("targetLabels", [])), "detections": item.get("detections", []), "detectionCount": item.get("detectionCount", 0), "maxConfidence": item.get("maxConfidence", 0)}
config = helpers["package_config_payload"](item, payload)
config["deliveryItems"] = {"headpose": {"enabled": bool(headpose and headpose.get("enabled")), "frameCount": headpose.get("frameCount", 0) if headpose else 0}, "handpose": {"enabled": bool(handpose and handpose.get("enabled", True)), "status": handpose.get("status", "missing") if handpose else "missing"}}
helpers["write_json_artifact"](run_id, node_id, package_dir, f"{clip_id}_quality.json", quality, output=binding)
if headpose_enabled:
helpers["write_json_artifact"](run_id, node_id, package_dir, f"{clip_id}_headpose.json", headpose, output=binding)
if handpose_enabled:
helpers["write_json_artifact"](run_id, node_id, package_dir, f"{clip_id}_handpose.json", handpose, output=binding)
helpers["write_json_artifact"](run_id, node_id, package_dir, f"{clip_id}_annotation.json", annotation, output=binding)
helpers["write_json_artifact"](run_id, node_id, package_dir, f"{clip_id}_config.json", config, output=binding)
package_files = [candidate for candidate in package_dir.rglob("*") if candidate.is_file()]
packages.append({"packageName": package_dir.name, "clipId": clip_id, "clipName": clip_name, "sourceVideo": item.get("sourceVideo", ""), "clipDuration": item.get("duration", 0), "duration": item.get("duration", 0), "startSecond": item.get("startSecond"), "endSecond": item.get("endSecond"), "collectionId": item.get("collectionId", ""), "meta": item.get("meta", {}), "source": item.get("source", {}) if isinstance(item.get("source"), dict) else {}, "fileCount": len(package_files), "pipelineTags": ["quality_v1", "slicing_v1", "annotation_v1", "headpose_v1", *(["handpose_v1"] if handpose_enabled else [])], "storagePath": str(package_dir), "quality": quality, "annotation": annotation, "deliveryItems": config["deliveryItems"]})
manifest = {"datasetType": "x-platform-packages", "packageCount": len(packages), "deliveryItems": {"headpose": {"enabled": bool(headpose and headpose.get("enabled")), "schemaVersion": headpose.get("schemaVersion") if headpose else ""}, "handpose": {"enabled": bool(handpose and handpose.get("enabled", True)), "schemaVersion": handpose.get("schemaVersion") if handpose else ""}}, "items": packages}
artifacts = [helpers["write_json_artifact"](run_id, node_id, output, "packages-manifest.json", manifest, output=binding)]
artifacts.extend(helpers["collect_output_artifacts"](run_id, node_id, output / "packages", node_data=node_data, output=binding))
return artifacts
def _run_existing_contract(run_id: str, node_id: str, output_dir: Any, node_data: dict[str, Any], inputs: list[dict[str, Any]], helpers: HelperMap) -> list[dict[str, Any]]:
params = helpers["hyperparams"](node_data)
if not _bool(params, "REQUIRE_FINAL_ACCEPTANCE", False) and not _bool(params, "GENERATE_SEGMENT_MP4", False):
return _run_legacy(run_id, node_id, output_dir, node_data, inputs, helpers)
return _run_fanyu_v5(run_id, node_id, output_dir, node_data, inputs, helpers)
def _output(node_data: dict[str, Any], helpers: HelperMap, name: str) -> dict[str, Any] | None:
del helpers
for output in node_data.get("outputs", []) if isinstance(node_data.get("outputs"), list) else []:
if isinstance(output, dict) and name in {str(output.get("id", "")).strip(), str(output.get("name", "")).strip()}:
return output
return None
def _port(artifact: dict[str, Any]) -> str:
return str(artifact.get("portId") or artifact.get("portName") or "").strip()
def _materialize_annotation_payload(artifact: dict[str, Any], output: pathlib.Path, helpers: HelperMap) -> dict[str, Any]:
data = artifact.get("data") if isinstance(artifact.get("data"), dict) else {}
if isinstance(data.get("items"), list):
return data
materialize = helpers.get("source_path_from_item")
source_ref = helpers.get("source_ref_from_artifact")
if not callable(materialize):
raise RuntimeError("成品打包无法物化 annotations 引用")
source = source_ref(artifact) if callable(source_ref) else {}
path = materialize({"path": str(artifact.get("path", "")), "source": source if isinstance(source, dict) else {}}, str(artifact.get("name", "annotations.json")), output, {})
decoded = json.loads(pathlib.Path(path).read_text(encoding="utf-8"))
if not isinstance(decoded, dict) or not isinstance(decoded.get("items"), list):
raise RuntimeError("annotations 引用不是可打包的 accepted annotation collection")
return decoded
def _source_index_files(source_root: pathlib.Path, manifest: dict[str, Any], verify_bytes: bool) -> dict[str, pathlib.Path]:
"""Only the fixed source version belonging to this run may be consumed.
JSON-only export retains the already verified hashes without rereading whole
videos. Physical export verifies every source byte before decoding it.
"""
fingerprint = str(manifest.get("sourceFingerprint") or "")
run_id = str(manifest.get("runId") or "")
if not _SHA.fullmatch(fingerprint) or not run_id or len(source_root.parents) < 4:
raise RuntimeError("invalid source-index identity")
run_root = source_root.parents[3]
if run_root.name != run_id or run_root.parent.name != "runs" or run_root.parent.parent.name != "system":
raise RuntimeError("source-index revision is outside its run")
result = {}
sources = manifest.get("sources") or {}
if set(sources) != {"leftVideo", "rightVideo", "leftPts", "rightPts", "imu"}:
raise RuntimeError("source-index requires five pinned sources")
for kind, source in sources.items():
suffix = ".mp4" if kind.endswith("Video") else ".csv"
expected = run_root / "annotation-sources" / fingerprint / (kind + suffix)
path = pathlib.Path(str(source.get("path") or ""))
if path != expected or path.resolve() != expected.absolute() or not path.is_file() or path.is_symlink():
raise RuntimeError("unsafe or unavailable pinned source")
if path.stat().st_size != source.get("bytes") or not _SHA.fullmatch(str(source.get("sha256") or "")):
raise RuntimeError("pinned source metadata mismatch")
if verify_bytes and _sha256_file(path) != source["sha256"]:
raise RuntimeError("pinned source checksum mismatch")
result[kind] = path
for item in manifest.get("items", []):
directory = str(item.get("directory") or "")
if not re.fullmatch(r"slices/slice-\d{6}", directory):
raise RuntimeError("unsafe source-index slice directory")
for kind, name in (("annotation", "annotation.json"), ("synchronization", "synchronized-slice.json")):
file = (item.get("files") or {}).get(kind) or {}
path = source_root / directory / name
if file.get("name") != name or path.is_symlink() or path.resolve().parent != (source_root / directory).absolute() or _sha256_file(path) != file.get("sha256"):
raise RuntimeError("source-index evidence checksum mismatch")
return result
def _source_index_physical_export(source_root: pathlib.Path, manifest: dict[str, Any], kept: list[dict[str, Any]], output: pathlib.Path) -> pathlib.Path:
sources = _source_index_files(source_root, manifest, True)
target_root = pathlib.Path(tempfile.mkdtemp(prefix="source-index-export-", dir=output))
pts = {side: _read_pts(sources[side + "Pts"]) for side in ("left", "right")}
for item in kept:
directory = target_root / item["directory"]
directory.mkdir(parents=True)
start_us, end_us = int(item["startTimestampUs"]), int(item["endTimestampUs"])
for name in ("annotation.json", "synchronized-slice.json"):
shutil.copy2(source_root / item["directory"] / name, directory / name)
for side in ("left", "right"):
first, end = item["sourceFrames"][side]
expected = [bisect.bisect_left(pts[side], start_us), bisect.bisect_left(pts[side], end_us)]
if [first, end] != expected or end <= first:
raise RuntimeError("source-index frame range disagrees with hardware timestamps")
duration_us = round(float(manifest["sourceDurations"][side]) * 1_000_000)
count = len(pts[side])
expression = f"trim=start_frame={first}:end_frame={end},settb=1/1000000,setpts=N*{duration_us}/{count}"
command = ["ffmpeg", "-nostdin", "-hide_banner", "-loglevel", "error", "-y", "-threads", "2", "-i", str(sources[side + "Video"]), "-an", "-vf", expression,
"-c:v", "libx264", "-threads", "2", "-preset", "ultrafast", "-crf", "23", "-pix_fmt", "yuv420p", "-enc_time_base", "1:1000000", "-video_track_timescale", "1000000", "-fps_mode", "passthrough", "-bsf:v", f"setts=pts=PTS:dts=DTS:duration={duration_us}/{count}", str(directory / (side + ".mp4"))]
result = subprocess.run(command, capture_output=True, text=True, timeout=3600)
if result.returncode:
raise RuntimeError("source-index physical media export failed")
with (directory / (side + "_pts.csv")).open("w", encoding="utf8", newline="") as handle:
writer = csv.writer(handle, lineterminator="\n")
writer.writerow(["frame_index", "timestamp_ms", "clip_time_ms"])
for index, timestamp in enumerate(pts[side][first:end]):
writer.writerow([index, f"{timestamp // 1000}.{timestamp % 1000:03d}", f"{(timestamp-start_us) // 1000}.{(timestamp-start_us) % 1000:03d}"])
# One streaming pass, including skipped intervals; never hold millions of
# IMU dictionaries in RAM or reread the CSV separately for every cut.
ordered = sorted(kept, key=lambda item: int(item["startTimestampUs"]))
starts = [int(item["startTimestampUs"]) for item in ordered]
active, handle, writer = -1, None, None
counts = [0] * len(ordered)
try:
with sources["imu"].open(encoding="utf-8-sig", newline="") as source:
header = source.readline()
delimiter = "\t" if header.count("\t") > header.count(",") else ","
names = [name.strip().lower() for name in next(csv.reader([header], delimiter=delimiter))]
reader = csv.DictReader(source, fieldnames=names, delimiter=delimiter)
for row in reader:
timestamp = int(row.get("timestamp_us", row.get("timestampus", "")))
index = bisect.bisect_right(starts, timestamp) - 1
if index < 0 or timestamp >= int(ordered[index]["endTimestampUs"]):
continue
if active != index:
if handle:
handle.close()
handle = (target_root / ordered[index]["directory"] / "imu.csv").open("w", encoding="utf8", newline="")
writer = csv.writer(handle, lineterminator="\n")
writer.writerow(["timestamp_ms", "clip_time_ms", "x", "y", "z", "type"])
active = index
relative = timestamp - starts[index]
writer.writerow([f"{timestamp // 1000}.{timestamp % 1000:03d}", f"{relative // 1000}.{relative % 1000:03d}", row["x"].strip(), row["y"].strip(), row["z"].strip(), row["type"].strip().lower()])
counts[index] += 1
finally:
if handle:
handle.close()
for item, count in zip(ordered, counts):
sync = json.loads((source_root / item["directory"] / "synchronized-slice.json").read_text())
if count != int(sync["imu"]["sampleCount"]):
raise RuntimeError("source-index IMU reconstruction mismatch")
# A short kept slice may legitimately hold no IMU samples; keep the
# per-slice file layout with a header-only CSV.
if count == 0:
with (target_root / item["directory"] / "imu.csv").open("w", encoding="utf8", newline="") as empty:
csv.writer(empty, lineterminator="\n").writerow(["timestamp_ms", "clip_time_ms", "x", "y", "z", "type"])
return target_root
def _run_accepted_slice_directory(
run_id: str,
node_id: str,
output_dir: Any,
node_data: dict[str, Any],
inputs: list[dict[str, Any]],
helpers: HelperMap,
) -> list[dict[str, Any]]:
output = pathlib.Path(output_dir)
output.mkdir(parents=True, exist_ok=True)
directory_artifact = next((item for item in inputs if _port(item) == "acceptedSliceDirectory"), None)
if directory_artifact is None:
raise RuntimeError("accepted slice package requires acceptedSliceDirectory")
source_root = pathlib.Path(str(directory_artifact.get("path") or "").strip())
if not source_root.is_dir():
raise RuntimeError("acceptedSliceDirectory is unavailable")
revision_manifest_path = source_root / "revision-manifest.json"
if not revision_manifest_path.is_file():
raise RuntimeError("acceptedSliceDirectory has no revision-manifest.json")
revision_manifest = json.loads(revision_manifest_path.read_text(encoding="utf-8"))
revision_schema = revision_manifest.get("schemaVersion")
source_index = revision_schema == _SOURCE_SLICE_SCHEMA
if revision_schema not in {"droboticflow.slice-materialization/v1", "droboticflow.slice-materialization/v2", "droboticflow.slice-materialization/v3", _SOURCE_SLICE_SCHEMA}:
raise RuntimeError("acceptedSliceDirectory has an unsupported revision manifest")
coverage = revision_manifest.get("coverage") if isinstance(revision_manifest.get("coverage"), dict) else {}
disposition_contract = revision_schema == "droboticflow.slice-materialization/v3" or source_index
coverage_required = revision_schema in {"droboticflow.slice-materialization/v2", "droboticflow.slice-materialization/v3"} or source_index
if coverage_required and (
coverage.get("mode") != "full_common_range"
or coverage.get("contiguous") is not True
or int(coverage.get("gapMicroseconds", -1)) != 0
or int(coverage.get("overlapMicroseconds", -1)) != 0
):
raise RuntimeError("acceptedSliceDirectory does not prove gap-free full-video coverage")
summary_artifact = next((item for item in inputs if _port(item) == "acceptanceSummary"), None)
summary_payload = summary_artifact.get("data") if isinstance((summary_artifact or {}).get("data"), dict) else {}
if summary_artifact is not None and not isinstance(summary_payload.get("finalAcceptance"), dict):
summary_path = _materialize_input_file(summary_artifact, output / "_acceptance", helpers)
if summary_path.stat().st_size > 8 * 1024 * 1024:
raise RuntimeError("acceptance summary exceeds 8 MiB")
summary_payload = json.loads(summary_path.read_text(encoding="utf8"))
if not isinstance(summary_payload, dict): raise RuntimeError("invalid acceptance summary reference")
final_acceptance = summary_payload.get("finalAcceptance") if isinstance(summary_payload.get("finalAcceptance"), dict) else {}
capture_record = _part_index_capture_record(summary_payload, revision_manifest)
all_slices = revision_manifest.get("items", [])
if not isinstance(all_slices, list) or not all_slices:
raise RuntimeError("accepted slice manifest has no review evidence")
kept_slices, discarded_slices = [], []
for row in all_slices:
if not isinstance(row, dict):
raise RuntimeError("invalid accepted slice entry")
disposition = row.get("deliveryDisposition", "keep" if not disposition_contract else None)
if disposition not in {"keep", "discard"} or (disposition == "discard" and not disposition_contract):
raise RuntimeError("unsupported or missing slice delivery disposition")
if disposition == "discard":
if not str((row.get("discardEvidence") or {}).get("reason") or "").strip():
raise RuntimeError("discarded slice has no reason evidence")
discarded_slices.append(row)
else:
kept_slices.append(row)
params = helpers["hyperparams"](node_data) if callable(helpers.get("hyperparams")) else {}
classification_v4 = _bool(params, "DELIVERY_JSON_V4", False)
if classification_v4 and not coverage_required:
raise RuntimeError("DELIVERY_JSON_V4 requires verified full-video coverage")
if disposition_contract or classification_v4:
pins = summary_payload.get("acceptedMaterializations", [])
expected_sha = _sha256_file(revision_manifest_path)
if summary_payload.get("decision") != "approved" or final_acceptance.get("confirmed") is not True or not any(
p.get("artifactId") == directory_artifact.get("id") and p.get("revision") == revision_manifest.get("revision") and p.get("manifestSha256") == expected_sha
for p in pins if isinstance(p, dict)
):
raise RuntimeError("slice dispositions are not pinned to the accepted manifest revision")
if int(coverage.get("sliceCount", -1)) != len(all_slices):
raise RuntimeError("review coverage slice count mismatch")
if disposition_contract and not kept_slices and not _bool(params, "DELIVERY_JSON_V4", False):
if any(p.get("key") == "PROCESSING_PROFILE" and p.get("value") == "raw_human" for p in node_data.get("hyperparams", [])) and (summary_payload.get("processingProfile") != "raw_human" or final_acceptance.get("processingProfile") != "raw_human"):
raise RuntimeError("raw-human package requires matching accepted task profile")
# Internal evidence only: deliberately no deliveryDirectory output and
# no customer destination directory/empty archive is produced.
summary = {"schemaVersion": "droboticflow.delivery-summary/v2", "outcome": "no_deliverables", "message": "无可交付片段", "sliceCount": 0, "discardedSliceCount": len(discarded_slices), "revision": revision_manifest.get("revision")}
return [helpers["write_json_artifact"](run_id, node_id, output, "no-deliverables.json", summary, output=_output(node_data, helpers, "deliverySummary"))]
pose_policy = final_acceptance.get("poseDelivery") if isinstance(final_acceptance.get("poseDelivery"), dict) else {}
raw_human = any(p.get("key") == "PROCESSING_PROFILE" and p.get("value") == "raw_human" for p in node_data.get("hyperparams", []))
if raw_human:
if summary_payload.get("processingProfile") != "raw_human" or final_acceptance.get("processingProfile") != "raw_human":
raise RuntimeError("raw-human package requires matching accepted task profile")
pose_policy = {"headpose": "not_generated", "handpose": "not_generated"}
elif pose_policy.get("headpose") not in {"include", "exclude"} or pose_policy.get("handpose") not in {"include", "exclude"}:
raise RuntimeError("accepted slice package requires HeadPose/HandPose include or exclude decisions")
payloads = _payload_tree(_payloads_with_full_pose_manifests(inputs, output, helpers))
headpose = _first_payload(payloads, "droboticflow.headpose/v1")
handpose = _first_payload(payloads, "droboticflow.wilor.hand_pose_result/v1")
if _bool(params, "PART_INDEX_DELIVERY", False):
if source_index and not _bool(params, "SOURCE_INDEX_DELIVERY", False):
raise RuntimeError("source-index JSON delivery requires explicit SOURCE_INDEX_DELIVERY approval; use directory delivery to preserve physical discard exclusion")
calibration_refs = _part_index_calibration_refs(inputs)
lineage = {"acceptedSliceDirectoryArtifactId": directory_artifact.get("id"), "humanItemId": revision_manifest.get("humanItemId"), "taskId": revision_manifest.get("taskId"), "sourceRunId": revision_manifest.get("runId")}
payload, body = _build_part_index(revision_manifest, coverage, kept_slices, source_root, calibration_refs, pose_policy, summary_payload, final_acceptance, capture_record, lineage, discarded_slices, classification_v4=classification_v4)
if source_index:
_source_index_files(source_root, revision_manifest, False)
payload["schemaVersion"] = _SOURCE_PART_INDEX_SCHEMA
payload["sourceIndexSchema"] = _SOURCE_SLICE_SCHEMA
payload["sourceDurations"] = revision_manifest["sourceDurations"]
payload["sourceFrameCounts"] = revision_manifest["sourceFrameCounts"]
payload["sources"] = {kind: {"workspaceKey": f"system/runs/{revision_manifest['runId']}/annotation-sources/{revision_manifest['sourceFingerprint']}/{kind}{'.mp4' if kind.endswith('Video') else '.csv'}", "sha256": value["sha256"], "bytes": value["bytes"]} for kind, value in revision_manifest["sources"].items()}
frames = {item["sliceId"]: item["sourceFrames"] for item in revision_manifest["items"]}
for item in payload["slices"] + payload["discardedSlices"]:
item["sourceFrames"] = frames[item["sliceId"]]
body = (json.dumps(payload, ensure_ascii=False, sort_keys=True, separators=(",", ":")) + "\n").encode("utf8")
if _bool(params, "DELIVERY_JSON_V4", False):
return _emit_part_index_directory(run_id, node_id, output, node_data, helpers, payload, summary_payload, revision_manifest, source_root)
if _bool(params, "DELIVERY_JSON_V3", False):
return _emit_part_index_directory(run_id, node_id, output, node_data, helpers, payload)
return _emit_part_index(run_id, node_id, output, node_data, helpers, body)
if source_index:
source_root = _source_index_physical_export(source_root, revision_manifest, kept_slices, output)
delivery_root = pathlib.Path(tempfile.mkdtemp(prefix="delivery-", dir=output)) if disposition_contract else output / "delivery"
clips_root = delivery_root / "clips"
clips_root.mkdir(parents=True, exist_ok=True)
calibration = _copy_calibrations(inputs, delivery_root, output, helpers)
package_items: list[dict[str, Any]] = []
for raw in kept_slices:
if not isinstance(raw, dict):
continue
slice_id = str(raw.get("sliceId") or "").strip()
relative = pathlib.PurePosixPath(str(raw.get("directory") or ""))
if disposition_contract and (relative.is_absolute() or ".." in relative.parts or not relative.parts):
raise RuntimeError("unsafe accepted slice directory")
source_slice = source_root / pathlib.Path(*relative.parts)
if not slice_id or not source_slice.is_dir():
raise RuntimeError("accepted slice manifest contains an unavailable slice directory")
target_slice = clips_root / slice_id
if not disposition_contract:
shutil.copytree(source_slice, target_slice, dirs_exist_ok=True)
start = float(raw.get("startSecond") or 0.0)
end = float(raw.get("endSecond") or 0.0)
start_us = int(raw.get("startTimestampUs") or 0)
end_us = int(raw.get("endTimestampUs") or 0)
required_files = ["left.mp4", "right.mp4", "left_pts.csv", "right_pts.csv", "imu.csv", "annotation.json", "synchronized-slice.json"]
if disposition_contract:
target_slice.mkdir(parents=True, exist_ok=False)
for name in required_files:
source = source_slice / name
if not source.is_file() or source.is_symlink():
raise RuntimeError(f"accepted slice {slice_id} is missing a safe required file: {name}")
shutil.copy2(source, target_slice / name)
missing_files = [name for name in required_files if not (target_slice / name).is_file()]
if missing_files:
raise RuntimeError(f"accepted slice {slice_id} is missing required files: {', '.join(missing_files)}")
left_pts = _read_materialized_pts(target_slice / "left_pts.csv")
right_pts = _read_materialized_pts(target_slice / "right_pts.csv")
if _ffprobe_frame_count(target_slice / "left.mp4") != len(left_pts):
raise RuntimeError(f"accepted slice {slice_id} left video/PTS frame count mismatch")
if _ffprobe_frame_count(target_slice / "right.mp4") != len(right_pts):
raise RuntimeError(f"accepted slice {slice_id} right video/PTS frame count mismatch")
synchronized_path = target_slice / "synchronized-slice.json"
synchronized = json.loads(synchronized_path.read_text(encoding="utf-8"))
# Only source-index evidence with a verified zero sample count may
# produce a header-only IMU CSV; legacy physical slices stay strict.
allow_empty_imu = source_index and synchronized["imu"]["sampleCount"] == 0
_validate_materialized_imu(target_slice / "imu.csv", start_us, end_us, allow_empty=allow_empty_imu)
declared_files = raw.get("files") if isinstance(raw.get("files"), dict) else {}
for declared in declared_files.values():
if not isinstance(declared, dict):
continue
name = str(declared.get("name") or "").strip()
expected_sha = str(declared.get("sha256") or "").strip()
if name and expected_sha and (target_slice / name).is_file() and _sha256_file(target_slice / name) != expected_sha:
raise RuntimeError(f"accepted slice {slice_id} checksum mismatch: {name}")
if pose_policy.get("headpose") == "include":
cropped = _crop_pose(headpose, start, end, "headpose") if headpose else None
if cropped is None or cropped.get("frameCount", 0) <= 0:
raise RuntimeError(f"HeadPose has no frames for accepted slice {slice_id}")
(target_slice / "headpose.json").write_text(json.dumps(cropped, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
else:
(target_slice / "headpose.json").unlink(missing_ok=True)
if pose_policy.get("handpose") == "include":
cropped = _crop_pose(handpose, start, end, "handpose") if handpose else None
if cropped is None or cropped.get("frameCount", 0) <= 0:
raise RuntimeError(f"HandPose has no frames for accepted slice {slice_id}")
(target_slice / "handpose.json").write_text(json.dumps(cropped, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
else:
(target_slice / "handpose.json").unlink(missing_ok=True)
if source_index:
synchronized.pop("sourceIndexSchema", None)
synchronized.pop("sourceMediaOffsets", None)
synchronized["calibration"] = [
{"name": item["name"], "path": item["path"], "sha256": item["sha256"]}
for item in calibration
]
synchronized_path.write_text(json.dumps(synchronized, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
files = []
for path in sorted(target_slice.iterdir()):
if path.is_file():
files.append({"name": path.name, "sha256": _sha256_file(path), "bytes": path.stat().st_size})
package_items.append({"sliceId": slice_id, "directory": f"clips/{slice_id}", "startSecond": start, "endSecond": end, "startTimestampUs": raw.get("startTimestampUs"), "endTimestampUs": raw.get("endTimestampUs"), "files": files})
if coverage_required and not disposition_contract and int(coverage.get("sliceCount", 0)) != len(package_items):
raise RuntimeError("acceptedSliceDirectory coverage slice count does not match its materialized items")
if disposition_contract:
# Processing coverage was checked above using every review slice. The
# public manifest describes only delivered intervals, not discard notes.
coverage = {"mode": "selected_accepted_intervals", "sliceCount": len(package_items), "durationSeconds": sum(float(x["endSecond"])-float(x["startSecond"]) for x in package_items), "intervals": [{"sliceId": x["sliceId"], "startTimestampUs": x["startTimestampUs"], "endTimestampUs": x["endTimestampUs"]} for x in package_items]}
sampling = {
"sampled": bool(final_acceptance.get("sampled", True)),
"decision": str(final_acceptance.get("samplingDecision") or "selected"),
"probability": final_acceptance.get("samplingProbability"),
"policyRevision": final_acceptance.get("samplingPolicyRevision"),
"randomValue": final_acceptance.get("samplingRandomValue"),
"decidedAt": final_acceptance.get("samplingDecidedAt"),
}
quality_reviews = summary_payload.get("qualityReviews") if isinstance(summary_payload.get("qualityReviews"), list) else []
if disposition_contract:
quality_reviews = [{k:r[k] for k in ("taskId","revision","decision","reviewerUserId","createdAt") if k in r} for r in quality_reviews if isinstance(r,dict)]
capture_manifest = {"schemaVersion": "droboticflow.capture-delivery/v1", "capture": capture_record, "revision": revision_manifest.get("revision"), "coverage": coverage, "sliceCount": len(package_items), "lineage": {"acceptedSliceDirectoryArtifactId": directory_artifact.get("id"), "humanItemId": revision_manifest.get("humanItemId"), "taskId": revision_manifest.get("taskId"), "sourceRunId": revision_manifest.get("runId")}}
public_acceptance = final_acceptance
if disposition_contract:
public_acceptance = {k:final_acceptance[k] for k in ("confirmed","sampled","samplingDecision","samplingProbability","samplingPolicyRevision","samplingRandomValue","samplingDecidedAt","acceptedAt","confirmedByUserId","processingProfile","poseDelivery") if k in final_acceptance}
evidence_payloads = {
"capture-manifest.json": capture_manifest,
"quality-review.json": {"schemaVersion": "droboticflow.capture-quality-review/v1", "reviews": quality_reviews},
"acceptance-record.json": {"schemaVersion": "droboticflow.capture-acceptance/v1", "finalAcceptance": public_acceptance},
"sampling-evidence.json": {"schemaVersion": "droboticflow.capture-sampling/v1", **sampling},
}
root_evidence = []
for name, payload in evidence_payloads.items():
path = delivery_root / name
path.write_text(json.dumps(payload, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
root_evidence.append({"name": name, "sha256": _sha256_file(path), "bytes": path.stat().st_size})
manifest = {"schemaVersion": "droboticflow.delivery.manifest/v5", "datasetType": "fanyu-accepted-slice-directories", "capture": capture_record, "revision": revision_manifest.get("revision"), "sliceCount": len(package_items), "coverage": coverage, "acceptanceSampling": sampling, "poseDelivery": pose_policy, "calibration": calibration, "rootEvidence": root_evidence, "lineage": {"acceptedSliceDirectoryArtifactId": directory_artifact.get("id"), "humanItemId": revision_manifest.get("humanItemId"), "taskId": revision_manifest.get("taskId"), "sourceRunId": revision_manifest.get("runId")}, "items": package_items}
if raw_human:
manifest["processingProfile"] = "raw_human"
manifest["processing"] = {"undistortion": "not_applied", "faceAnonymization": "not_applied", "qwen": "not_generated", "headpose": "not_generated", "handpose": "not_generated"}
if disposition_contract:
manifest["schemaVersion"] = "droboticflow.delivery.manifest/v6"
manifest_binding = _output(node_data, helpers, "deliveryManifest")
directory_binding = _output(node_data, helpers, "deliveryDirectory")
result = [helpers["write_json_artifact"](run_id, node_id, delivery_root, "packages-manifest.json", manifest, output=manifest_binding)]
result.append(helpers["build_virtual_artifact"](run_id, node_id, "delivery.directory.index", str(delivery_root), "file", 0, data={"schemaVersion": "droboticflow.directory-index/v1", "presentation": "collection", "datasetType": "directory", "dataSource": "FILESYSTEM", "rootPath": str(delivery_root), "sliceCount": len(package_items), "coverage": coverage}, output=directory_binding))
result.append(helpers["write_json_artifact"](run_id, node_id, output, "delivery-summary.json", {"sliceCount": len(package_items), "coverage": coverage, "acceptanceSampling": sampling, "poseDelivery": pose_policy, "calibrationCount": len(calibration)}, output=_output(node_data, helpers, "deliverySummary")))
return result
def _run_multiport(
run_id: str,
node_id: str,
output_dir: Any,
node_data: dict[str, Any],
inputs: list[dict[str, Any]],
helpers: HelperMap,
) -> list[dict[str, Any]]:
output = pathlib.Path(output_dir)
if any(_port(item) == "acceptedSliceDirectory" for item in inputs):
return _run_accepted_slice_directory(run_id, node_id, output_dir, node_data, inputs, helpers)
approved = [
item
for item in inputs
if _port(item) == "approvedVideos" or (not _port(item) and str(item.get("type", "")) == "video")
]
annotation_artifact = next((item for item in inputs if _port(item) == "annotations"), None)
if not approved or annotation_artifact is None:
# A newly published package image must still execute historical graphs
# that supply one legacy annotations/manifest input.
return _run_existing_contract(run_id, node_id, output_dir, node_data, inputs, helpers)
accepted = _materialize_annotation_payload(annotation_artifact, output, helpers)
# Existing precise Fanyu packager owns ffmpeg cutting and acceptance
# validation. Feed it a local technical adapter only; business outputs are
# rebound below by their real media/file role.
context_inputs = [item for item in inputs if item not in approved and item is not annotation_artifact]
generated = _run_fanyu_v5(
run_id,
node_id,
output,
node_data,
[{"name": "accepted-annotations-index.json", "data": accepted}, *approved, *context_inputs],
helpers,
)
packages_root = output / "packages"
package_binding = _output(node_data, helpers, "packageDirectory")
result: list[dict[str, Any]] = []
if package_binding is not None:
package_count = len([path for path in packages_root.iterdir() if path.is_dir() and path.name.endswith("_package")])
result.append(
helpers["build_virtual_artifact"](
run_id,
node_id,
"delivery-package-directory.index",
str(packages_root),
"file",
0,
data={
"schemaVersion": "droboticflow.directory-index/v1",
"presentation": "collection",
"datasetType": "directory",
"dataSource": "FILESYSTEM",
"rootPath": str(packages_root),
"packageCount": package_count,
},
output=package_binding,
)
)
for artifact in generated:
name = str(artifact.get("name", "")).lower()
artifact_path = pathlib.Path(str(artifact.get("path", "")))
try:
relative_path = artifact_path.relative_to(packages_root).as_posix().lower()
except ValueError:
relative_path = artifact_path.name.lower()
binding = None
if name == "packages-manifest.json":
binding = package_binding
elif name.endswith(".mp4"):
binding = (
_output(node_data, helpers, "finalRightVideos")
if name.endswith("_right.mp4")
else _output(node_data, helpers, "finalLeftVideos")
) or _output(node_data, helpers, "finalVideos")
elif name.endswith("_left_pts.csv"):
binding = _output(node_data, helpers, "leftTimestampFiles")
elif name.endswith("_right_pts.csv"):
binding = _output(node_data, helpers, "rightTimestampFiles")
elif name.endswith("_imu.csv"):
binding = _output(node_data, helpers, "imuFiles")
elif name == "semantic.json" or name.endswith("_annotation.json"):
binding = _output(node_data, helpers, "timestampedAnnotationFiles") or _output(node_data, helpers, "semanticFiles")
elif name == "synchronized-slice.json":
binding = _output(node_data, helpers, "synchronizationFiles")
elif relative_path.startswith("calibration/"):
binding = _output(node_data, helpers, "calibrationFiles")
elif name == "segment.json" or name.endswith("_segment.json"):
binding = _output(node_data, helpers, "segmentFiles")
elif name == "headpose.json" or name.endswith("_headpose.json"):
binding = _output(node_data, helpers, "headposeFiles")
elif name == "handpose.json" or name.endswith("_handpose.json"):
binding = _output(node_data, helpers, "handposeFiles")
if binding is None:
continue
artifact["portId"] = str(binding.get("id", ""))
artifact["portName"] = str(binding.get("name", ""))
result.append(artifact)
manifest_path = output / "packages-manifest.json"
manifest = json.loads(manifest_path.read_text(encoding="utf-8")) if manifest_path.exists() else {}
params = helpers["hyperparams"](node_data)
summary = {"packageCount": int(manifest.get("packageCount", 0) or 0), "trainingEnabled": False, "poseFree": _bool(params, "POSE_FREE", False), "stereoDelivery": bool(manifest.get("stereoDelivery")), "headposeIncluded": bool(manifest.get("headposeIncluded")), "handposeIncluded": bool(manifest.get("handposeIncluded")), "finalAcceptanceRequired": _bool(params, "REQUIRE_FINAL_ACCEPTANCE", False)}
result.append(helpers["write_json_artifact"](run_id, node_id, output, "delivery-summary.json", summary, output=_output(node_data, helpers, "deliverySummary")))
return result
def run(run_id: str, node_id: str, output_dir: Any, node_data: dict[str, Any], inputs: list[dict[str, Any]], helpers: HelperMap) -> list[dict[str, Any]]:
params = helpers["hyperparams"](node_data) if callable(helpers.get("hyperparams")) else {}
if _bool(params, "DELIVERY_JSON_V4", False) and (not _bool(params, "PART_INDEX_DELIVERY", False) or _bool(params, "DELIVERY_JSON_V3", False)):
raise RuntimeError("DELIVERY_JSON_V4 requires PART_INDEX_DELIVERY and cannot combine with DELIVERY_JSON_V3")
if _bool(params, "DELIVERY_JSON_V3", False) and not _bool(params, "PART_INDEX_DELIVERY", False):
raise RuntimeError("DELIVERY_JSON_V3 requires PART_INDEX_DELIVERY")
# A part-index delivery intentionally has no directory port; it must still
# reach the accepted-slice path instead of the legacy inline contract.
if (
_output(node_data, helpers, "packageDirectory") is not None
or _output(node_data, helpers, "deliveryDirectory") is not None
or _output(node_data, helpers, "deliveryPartIndex") is not None
):
return _run_multiport(run_id, node_id, output_dir, node_data, inputs, helpers)
return _run_existing_contract(run_id, node_id, output_dir, node_data, inputs, helpers)