Merge pull request #11 from tihado/issue-1-harden-pipeline-foundation

README.md

@@ -18,6 +18,16 @@ uv run gradio app.py
 
 The app runs at `http://127.0.0.1:7860` by default.
 
+The pipeline runs in mock mode by default. To be explicit in scripts, call
+`run_pipeline(..., mock=True)` or set:
+
+```bash
+POZIFY_MOCK_MODE=1 uv run python app.py
+```
+
+Setting `POZIFY_MOCK_MODE=0` currently raises `NotImplementedError` until real model-backed
+steps are added.
+
 ## Pipeline
 
 ```text
@@ -64,6 +74,7 @@ docs/
 
 Each analysis run creates a folder under `runs/<run_id>/`:
 
+- `manifest.json`
 - `user_profile.json`
 - `video_manifest.json`
 - `pose_sequence.json`
@@ -76,6 +87,10 @@ Each analysis run creates a folder under `runs/<run_id>/`:
 - `verification.json`
 - `final_report.json`
 
+`manifest.json` indexes the generated artifacts in pipeline order and records whether the run used
+mock mode. JSON artifacts are validated before they are written, including required fields, supported
+enum values, score ranges, frame/timestamp ordering, and final report shape.
+
 `annotated_video.mp4` is not implemented yet. The mocked renderer currently returns the original input video path and writes `annotated_video_placeholder.json`.
 
 ## Replacing Mock Steps
@@ -95,6 +110,10 @@ Recommended replacement order:
 ## Development Checks
 
 ```bash
+uv run python -m unittest discover -s tests
 python3 -m py_compile app.py src/pozify/*.py src/pozify/steps/*.py
 uv run python -c "import app; from pozify.pipeline import run_pipeline; print('ok')"
 ```
+
+The unit tests run the full mocked pipeline with no video input and with a small fixture path, then
+assert deterministic top-level keys for each JSON artifact.

src/pozify/artifacts.py

@@ -4,12 +4,13 @@ import json
 from pathlib import Path
 from typing import Any
 
-from pozify.contracts import to_dict
+from pozify.contracts import to_dict, validate_contract
 
 
-def write_json(run_dir: Path, filename: str, payload: Any) -> Path:
+def write_json(run_dir: Path, filename: str, payload: Any, *, validate: bool = True) -> Path:
     run_dir.mkdir(parents=True, exist_ok=True)
+    if validate:
+        validate_contract(filename, payload)
     path = run_dir / filename
     path.write_text(json.dumps(to_dict(payload), ensure_ascii=False, indent=2), encoding="utf-8")
     return path
-

src/pozify/contracts.py

@@ -6,6 +6,16 @@ from typing import Any, Literal
 
 Exercise = Literal["squat", "push_up", "shoulder_press", "unknown"]
 
+EXERCISES = {"squat", "push_up", "shoulder_press", "unknown"}
+INTENDED_EXERCISES = EXERCISES | {"auto"}
+GOALS = {"strength", "hypertrophy", "endurance", "mobility", "beginner_practice"}
+EXPERIENCE_LEVELS = {"beginner", "intermediate"}
+EQUIPMENT = {"bodyweight", "dumbbell", "barbell", "unknown"}
+
+
+class ContractValidationError(ValueError):
+    """Raised when a pipeline artifact does not match its JSON contract."""
+
 
 @dataclass(frozen=True)
 class UserProfile:
@@ -142,3 +152,377 @@ def to_dict(value: Any) -> Any:
         return {key: to_dict(item) for key, item in value.items()}
     return value
 
+
+def validate_contract(name: str, value: Any) -> None:
+    payload = to_dict(value)
+    validators = {
+        "user_profile.json": _validate_user_profile,
+        "video_manifest.json": _validate_video_manifest,
+        "pose_sequence.json": _validate_pose_sequence,
+        "exercise_classification.json": _validate_exercise_classification,
+        "reps.json": _validate_reps,
+        "rep_analysis.json": _validate_rep_analysis,
+        "variation.json": _validate_variation,
+        "issue_markers.json": _validate_issue_markers,
+        "coach_summary.json": _validate_coach_summary,
+        "verification.json": _validate_verification,
+        "final_report.json": _validate_final_report,
+        "manifest.json": _validate_run_manifest,
+    }
+    try:
+        validator = validators[name]
+    except KeyError as exc:
+        raise ContractValidationError(f"Unknown contract: {name}") from exc
+    validator(payload, name)
+
+
+def _require_mapping(value: Any, path: str) -> dict[str, Any]:
+    if not isinstance(value, dict):
+        raise ContractValidationError(f"{path} must be an object")
+    return value
+
+
+def _require_fields(payload: dict[str, Any], required: set[str], path: str) -> None:
+    missing = sorted(required - payload.keys())
+    if missing:
+        raise ContractValidationError(f"{path} missing required field(s): {', '.join(missing)}")
+
+
+def _require_type(value: Any, expected_type: type | tuple[type, ...], path: str) -> None:
+    if not isinstance(value, expected_type):
+        raise ContractValidationError(f"{path} has invalid type")
+
+
+def _require_bool(value: Any, path: str) -> None:
+    if not isinstance(value, bool):
+        raise ContractValidationError(f"{path} must be a boolean")
+
+
+def _require_number(value: Any, path: str, *, minimum: float | None = None) -> None:
+    if isinstance(value, bool) or not isinstance(value, int | float):
+        raise ContractValidationError(f"{path} must be a number")
+    if minimum is not None and value < minimum:
+        raise ContractValidationError(f"{path} must be >= {minimum}")
+
+
+def _require_int(value: Any, path: str, *, minimum: int | None = None) -> None:
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise ContractValidationError(f"{path} must be an integer")
+    if minimum is not None and value < minimum:
+        raise ContractValidationError(f"{path} must be >= {minimum}")
+
+
+def _require_score(value: Any, path: str) -> None:
+    _require_number(value, path)
+    if value < 0 or value > 1:
+        raise ContractValidationError(f"{path} must be between 0 and 1")
+
+
+def _require_enum(value: Any, allowed: set[str], path: str) -> None:
+    if value not in allowed:
+        raise ContractValidationError(f"{path} has invalid enum value: {value!r}")
+
+
+def _require_string_list(value: Any, path: str) -> None:
+    _require_type(value, list, path)
+    for index, item in enumerate(value):
+        _require_type(item, str, f"{path}[{index}]")
+
+
+def _require_time_range(start_frame: Any, end_frame: Any, start_sec: Any, end_sec: Any, path: str) -> None:
+    _require_int(start_frame, f"{path}.start_frame", minimum=0)
+    _require_int(end_frame, f"{path}.end_frame", minimum=0)
+    _require_number(start_sec, f"{path}.start_sec", minimum=0)
+    _require_number(end_sec, f"{path}.end_sec", minimum=0)
+    if start_frame > end_frame:
+        raise ContractValidationError(f"{path} frame range must be ordered")
+    if start_sec > end_sec:
+        raise ContractValidationError(f"{path} timestamp range must be ordered")
+
+
+def _validate_user_profile(value: Any, path: str) -> None:
+    payload = _require_mapping(value, path)
+    _require_fields(
+        payload,
+        {
+            "goal",
+            "experience_level",
+            "intended_exercise",
+            "intended_variation",
+            "known_limitations",
+            "equipment",
+        },
+        path,
+    )
+    _require_enum(payload["goal"], GOALS, f"{path}.goal")
+    _require_enum(payload["experience_level"], EXPERIENCE_LEVELS, f"{path}.experience_level")
+    _require_enum(payload["intended_exercise"], INTENDED_EXERCISES, f"{path}.intended_exercise")
+    if payload["intended_variation"] is not None:
+        _require_type(payload["intended_variation"], str, f"{path}.intended_variation")
+    _require_string_list(payload["known_limitations"], f"{path}.known_limitations")
+    _require_enum(payload["equipment"], EQUIPMENT, f"{path}.equipment")
+
+
+def _validate_video_manifest(value: Any, path: str) -> None:
+    payload = _require_mapping(value, path)
+    _require_fields(
+        payload,
+        {
+            "video_path",
+            "fps",
+            "duration_sec",
+            "total_frames",
+            "sampled_frames",
+            "quality_warnings",
+            "analysis_allowed",
+        },
+        path,
+    )
+    if payload["video_path"] is not None:
+        _require_type(payload["video_path"], str, f"{path}.video_path")
+    _require_number(payload["fps"], f"{path}.fps", minimum=0)
+    _require_number(payload["duration_sec"], f"{path}.duration_sec", minimum=0)
+    _require_int(payload["total_frames"], f"{path}.total_frames", minimum=0)
+    _require_int(payload["sampled_frames"], f"{path}.sampled_frames", minimum=0)
+    if payload["sampled_frames"] > payload["total_frames"]:
+        raise ContractValidationError(f"{path}.sampled_frames must be <= total_frames")
+    _require_string_list(payload["quality_warnings"], f"{path}.quality_warnings")
+    _require_bool(payload["analysis_allowed"], f"{path}.analysis_allowed")
+
+
+def _validate_pose_sequence(value: Any, path: str) -> None:
+    payload = _require_mapping(value, path)
+    _require_fields(payload, {"frames", "normalized", "smoothing_method", "pose_valid_ratio"}, path)
+    _require_type(payload["frames"], list, f"{path}.frames")
+    previous_frame = -1
+    previous_timestamp = -1.0
+    for index, frame_value in enumerate(payload["frames"]):
+        frame_path = f"{path}.frames[{index}]"
+        frame = _require_mapping(frame_value, frame_path)
+        _require_fields(
+            frame,
+            {"frame_index", "timestamp_sec", "landmarks", "world_landmarks", "pose_quality"},
+            frame_path,
+        )
+        _require_int(frame["frame_index"], f"{frame_path}.frame_index", minimum=0)
+        _require_number(frame["timestamp_sec"], f"{frame_path}.timestamp_sec", minimum=0)
+        if frame["frame_index"] < previous_frame:
+            raise ContractValidationError(f"{frame_path}.frame_index must be ordered")
+        if frame["timestamp_sec"] < previous_timestamp:
+            raise ContractValidationError(f"{frame_path}.timestamp_sec must be ordered")
+        previous_frame = frame["frame_index"]
+        previous_timestamp = frame["timestamp_sec"]
+        _require_mapping(frame["landmarks"], f"{frame_path}.landmarks")
+        _require_mapping(frame["world_landmarks"], f"{frame_path}.world_landmarks")
+        _require_mapping(frame["pose_quality"], f"{frame_path}.pose_quality")
+    _require_bool(payload["normalized"], f"{path}.normalized")
+    _require_type(payload["smoothing_method"], str, f"{path}.smoothing_method")
+    _require_score(payload["pose_valid_ratio"], f"{path}.pose_valid_ratio")
+
+
+def _validate_exercise_classification(value: Any, path: str) -> None:
+    payload = _require_mapping(value, path)
+    _require_fields(payload, {"exercise", "confidence", "window_predictions", "fallback_required"}, path)
+    _require_enum(payload["exercise"], EXERCISES, f"{path}.exercise")
+    _require_score(payload["confidence"], f"{path}.confidence")
+    _require_type(payload["window_predictions"], list, f"{path}.window_predictions")
+    for index, prediction_value in enumerate(payload["window_predictions"]):
+        prediction_path = f"{path}.window_predictions[{index}]"
+        prediction = _require_mapping(prediction_value, prediction_path)
+        _require_fields(prediction, {"start_sec", "end_sec", "label", "confidence"}, prediction_path)
+        _require_number(prediction["start_sec"], f"{prediction_path}.start_sec", minimum=0)
+        _require_number(prediction["end_sec"], f"{prediction_path}.end_sec", minimum=0)
+        if prediction["start_sec"] > prediction["end_sec"]:
+            raise ContractValidationError(f"{prediction_path} timestamps must be ordered")
+        _require_enum(prediction["label"], EXERCISES, f"{prediction_path}.label")
+        _require_score(prediction["confidence"], f"{prediction_path}.confidence")
+    _require_bool(payload["fallback_required"], f"{path}.fallback_required")
+
+
+def _validate_rep(rep_value: Any, path: str) -> None:
+    rep = _require_mapping(rep_value, path)
+    _require_fields(
+        rep,
+        {"rep_id", "start_frame", "mid_frame", "end_frame", "start_sec", "mid_sec", "end_sec"},
+        path,
+    )
+    _require_int(rep["rep_id"], f"{path}.rep_id", minimum=1)
+    _require_time_range(rep["start_frame"], rep["end_frame"], rep["start_sec"], rep["end_sec"], path)
+    _require_int(rep["mid_frame"], f"{path}.mid_frame", minimum=0)
+    _require_number(rep["mid_sec"], f"{path}.mid_sec", minimum=0)
+    if not rep["start_frame"] <= rep["mid_frame"] <= rep["end_frame"]:
+        raise ContractValidationError(f"{path}.mid_frame must be inside rep frame range")
+    if not rep["start_sec"] <= rep["mid_sec"] <= rep["end_sec"]:
+        raise ContractValidationError(f"{path}.mid_sec must be inside rep timestamp range")
+
+
+def _validate_reps(value: Any, path: str) -> None:
+    payload = _require_mapping(value, path)
+    _require_fields(payload, {"exercise", "reps", "partial_reps"}, path)
+    _require_enum(payload["exercise"], EXERCISES, f"{path}.exercise")
+    _require_type(payload["reps"], list, f"{path}.reps")
+    for index, rep in enumerate(payload["reps"]):
+        _validate_rep(rep, f"{path}.reps[{index}]")
+    _require_type(payload["partial_reps"], list, f"{path}.partial_reps")
+
+
+def _validate_rep_analysis(value: Any, path: str) -> None:
+    payload = _require_mapping(value, path)
+    _require_fields(payload, {"exercise", "items", "aggregate_metrics"}, path)
+    _require_enum(payload["exercise"], EXERCISES, f"{path}.exercise")
+    _require_type(payload["items"], list, f"{path}.items")
+    for index, item_value in enumerate(payload["items"]):
+        item_path = f"{path}.items[{index}]"
+        item = _require_mapping(item_value, item_path)
+        _require_fields(
+            item,
+            {
+                "rep_id",
+                "duration_sec",
+                "range_of_motion_score",
+                "stability_score",
+                "symmetry_score",
+                "metrics",
+                "variation_hints",
+            },
+            item_path,
+        )
+        _require_int(item["rep_id"], f"{item_path}.rep_id", minimum=1)
+        _require_number(item["duration_sec"], f"{item_path}.duration_sec", minimum=0)
+        _require_score(item["range_of_motion_score"], f"{item_path}.range_of_motion_score")
+        _require_score(item["stability_score"], f"{item_path}.stability_score")
+        _require_score(item["symmetry_score"], f"{item_path}.symmetry_score")
+        _require_mapping(item["metrics"], f"{item_path}.metrics")
+        _require_string_list(item["variation_hints"], f"{item_path}.variation_hints")
+    _require_mapping(payload["aggregate_metrics"], f"{path}.aggregate_metrics")
+
+
+def _validate_variation(value: Any, path: str) -> None:
+    payload = _require_mapping(value, path)
+    _require_fields(payload, {"exercise", "detected_variation", "variation_confidence", "not_issues"}, path)
+    _require_enum(payload["exercise"], EXERCISES, f"{path}.exercise")
+    _require_type(payload["detected_variation"], str, f"{path}.detected_variation")
+    _require_score(payload["variation_confidence"], f"{path}.variation_confidence")
+    _require_string_list(payload["not_issues"], f"{path}.not_issues")
+
+
+def _validate_issue_markers(value: Any, path: str) -> None:
+    payload = _require_mapping(value, path)
+    _require_fields(payload, {"issues"}, path)
+    _require_type(payload["issues"], list, f"{path}.issues")
+    for index, issue_value in enumerate(payload["issues"]):
+        issue_path = f"{path}.issues[{index}]"
+        issue = _require_mapping(issue_value, issue_path)
+        _require_fields(
+            issue,
+            {
+                "rep_id",
+                "issue",
+                "severity",
+                "start_frame",
+                "end_frame",
+                "start_sec",
+                "end_sec",
+                "affected_joints",
+                "evidence",
+            },
+            issue_path,
+        )
+        _require_int(issue["rep_id"], f"{issue_path}.rep_id", minimum=1)
+        _require_type(issue["issue"], str, f"{issue_path}.issue")
+        _require_score(issue["severity"], f"{issue_path}.severity")
+        _require_time_range(
+            issue["start_frame"],
+            issue["end_frame"],
+            issue["start_sec"],
+            issue["end_sec"],
+            issue_path,
+        )
+        _require_string_list(issue["affected_joints"], f"{issue_path}.affected_joints")
+        _require_mapping(issue["evidence"], f"{issue_path}.evidence")
+
+
+def _validate_coach_summary(value: Any, path: str) -> None:
+    payload = _require_mapping(value, path)
+    _require_fields(
+        payload,
+        {
+            "summary",
+            "what_went_well",
+            "main_findings",
+            "variation_explanation",
+            "top_fixes",
+            "next_session_plan",
+            "confidence_notes",
+        },
+        path,
+    )
+    _require_type(payload["summary"], str, f"{path}.summary")
+    _require_string_list(payload["what_went_well"], f"{path}.what_went_well")
+    _require_string_list(payload["main_findings"], f"{path}.main_findings")
+    _require_type(payload["variation_explanation"], str, f"{path}.variation_explanation")
+    _require_string_list(payload["top_fixes"], f"{path}.top_fixes")
+    _require_string_list(payload["next_session_plan"], f"{path}.next_session_plan")
+    _require_string_list(payload["confidence_notes"], f"{path}.confidence_notes")
+
+
+def _validate_verification(value: Any, path: str) -> None:
+    payload = _require_mapping(value, path)
+    _require_fields(payload, {"passed", "checks", "notes"}, path)
+    _require_bool(payload["passed"], f"{path}.passed")
+    checks = _require_mapping(payload["checks"], f"{path}.checks")
+    for key, value in checks.items():
+        _require_type(key, str, f"{path}.checks key")
+        _require_bool(value, f"{path}.checks.{key}")
+    _require_string_list(payload["notes"], f"{path}.notes")
+
+
+def _validate_final_report(value: Any, path: str) -> None:
+    payload = _require_mapping(value, path)
+    _require_fields(
+        payload,
+        {
+            "run_id",
+            "profile",
+            "video_manifest",
+            "exercise",
+            "reps",
+            "rep_analysis",
+            "variation",
+            "issue_markers",
+            "coach_summary",
+            "verification",
+            "artifacts",
+        },
+        path,
+    )
+    _require_type(payload["run_id"], str, f"{path}.run_id")
+    _validate_user_profile(payload["profile"], f"{path}.profile")
+    _validate_video_manifest(payload["video_manifest"], f"{path}.video_manifest")
+    _validate_exercise_classification(payload["exercise"], f"{path}.exercise")
+    _validate_reps(payload["reps"], f"{path}.reps")
+    _validate_rep_analysis(payload["rep_analysis"], f"{path}.rep_analysis")
+    _validate_variation(payload["variation"], f"{path}.variation")
+    _validate_issue_markers(payload["issue_markers"], f"{path}.issue_markers")
+    _validate_coach_summary(payload["coach_summary"], f"{path}.coach_summary")
+    _validate_verification(payload["verification"], f"{path}.verification")
+    artifacts = _require_mapping(payload["artifacts"], f"{path}.artifacts")
+    _require_fields(artifacts, {"run_dir", "annotated_video_path"}, f"{path}.artifacts")
+    _require_type(artifacts["run_dir"], str, f"{path}.artifacts.run_dir")
+    if artifacts["annotated_video_path"] is not None:
+        _require_type(artifacts["annotated_video_path"], str, f"{path}.artifacts.annotated_video_path")
+
+
+def _validate_run_manifest(value: Any, path: str) -> None:
+    payload = _require_mapping(value, path)
+    _require_fields(payload, {"run_id", "mock_mode", "artifacts"}, path)
+    _require_type(payload["run_id"], str, f"{path}.run_id")
+    _require_bool(payload["mock_mode"], f"{path}.mock_mode")
+    _require_type(payload["artifacts"], list, f"{path}.artifacts")
+    for index, artifact_value in enumerate(payload["artifacts"]):
+        artifact_path = f"{path}.artifacts[{index}]"
+        artifact = _require_mapping(artifact_value, artifact_path)
+        _require_fields(artifact, {"name", "path", "contract"}, artifact_path)
+        _require_type(artifact["name"], str, f"{artifact_path}.name")
+        _require_type(artifact["path"], str, f"{artifact_path}.path")
+        _require_type(artifact["contract"], str, f"{artifact_path}.contract")

src/pozify/pipeline.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 from datetime import datetime, timezone
+import os
 from pathlib import Path
 from typing import Any
 from uuid import uuid4
@@ -25,9 +26,34 @@ from pozify.steps import (
 RUNS_DIR = Path("runs")
 
 
-def run_pipeline(video_path: str | None, profile_input: dict[str, Any]) -> dict[str, Any]:
+def _env_mock_mode() -> bool:
+    value = os.getenv("POZIFY_MOCK_MODE", "1").strip().lower()
+    return value not in {"0", "false", "no", "off"}
+
+
+def run_pipeline(
+    video_path: str | None,
+    profile_input: dict[str, Any],
+    *,
+    mock: bool | None = None,
+) -> dict[str, Any]:
+    mock_mode = _env_mock_mode() if mock is None else mock
+    if not mock_mode:
+        raise NotImplementedError("Only mock pipeline implementations are available right now.")
+
     run_id = f"{datetime.now(timezone.utc).strftime('%Y%m%dT%H%M%SZ')}-{uuid4().hex[:8]}"
     run_dir = RUNS_DIR / run_id
+    artifact_index: list[dict[str, str]] = []
+
+    def write_artifact(filename: str, payload: Any) -> None:
+        path = write_json(run_dir, filename, payload)
+        artifact_index.append(
+            {
+                "name": filename,
+                "path": str(path),
+                "contract": filename,
+            }
+        )
 
     profile = UserProfile(
         goal=profile_input["goal"],
@@ -37,37 +63,44 @@ def run_pipeline(video_path: str | None, profile_input: dict[str, Any]) -> dict[
         known_limitations=profile_input.get("known_limitations", []),
         equipment=profile_input.get("equipment", "unknown"),
     )
-    write_json(run_dir, "user_profile.json", profile)
+    write_artifact("user_profile.json", profile)
 
     manifest = video_qc.run(video_path)
-    write_json(run_dir, "video_manifest.json", manifest)
+    write_artifact("video_manifest.json", manifest)
 
     pose_sequence = pose_landmarker.run(manifest)
     cleaned_pose_sequence = pose_cleaning.run(pose_sequence)
-    write_json(run_dir, "pose_sequence.json", cleaned_pose_sequence)
+    write_artifact("pose_sequence.json", cleaned_pose_sequence)
 
     classification = exercise_classifier.run(cleaned_pose_sequence, profile)
-    write_json(run_dir, "exercise_classification.json", classification)
+    write_artifact("exercise_classification.json", classification)
 
     reps = rep_counter.run(classification, cleaned_pose_sequence)
-    write_json(run_dir, "reps.json", reps)
+    write_artifact("reps.json", reps)
 
     analysis = rep_analysis.run(classification, reps, cleaned_pose_sequence)
-    write_json(run_dir, "rep_analysis.json", analysis)
+    write_artifact("rep_analysis.json", analysis)
 
     variation = variation_detector.run(classification, analysis, profile)
-    write_json(run_dir, "variation.json", variation)
+    write_artifact("variation.json", variation)
 
     issues = issue_marker.run(classification, reps, analysis, variation)
-    write_json(run_dir, "issue_markers.json", issues)
+    write_artifact("issue_markers.json", issues)
 
     annotated_video_path = annotated_renderer.run(manifest, issues, run_dir)
+    artifact_index.append(
+        {
+            "name": "annotated_video_placeholder.json",
+            "path": str(run_dir / "annotated_video_placeholder.json"),
+            "contract": "renderer_placeholder",
+        }
+    )
 
     summary = coach_summary.run(profile, classification, reps, analysis, variation, issues)
-    write_json(run_dir, "coach_summary.json", summary)
+    write_artifact("coach_summary.json", summary)
 
     verification = verifier.run(summary, issues, variation)
-    write_json(run_dir, "verification.json", verification)
+    write_artifact("verification.json", verification)
 
     final_report = {
         "run_id": run_id,
@@ -85,12 +118,19 @@ def run_pipeline(video_path: str | None, profile_input: dict[str, Any]) -> dict[
             "annotated_video_path": annotated_video_path,
         },
     }
-    write_json(run_dir, "final_report.json", final_report)
+    write_artifact("final_report.json", final_report)
+
+    run_manifest = {
+        "run_id": run_id,
+        "mock_mode": mock_mode,
+        "artifacts": artifact_index,
+    }
+    write_json(run_dir, "manifest.json", run_manifest)
 
     return {
         "run_id": run_id,
         "run_dir": str(run_dir),
         "annotated_video_path": annotated_video_path,
+        "manifest_path": str(run_dir / "manifest.json"),
         "final_report": final_report,
     }
-

tests/test_pipeline_contracts.py

@@ -0,0 +1,165 @@
+from __future__ import annotations
+
+import json
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
+
+from pozify import pipeline
+from pozify.contracts import ContractValidationError, UserProfile, validate_contract
+
+
+PROFILE_INPUT = {
+    "goal": "beginner_practice",
+    "experience_level": "beginner",
+    "intended_exercise": "auto",
+    "intended_variation": None,
+    "known_limitations": [],
+    "equipment": "bodyweight",
+}
+
+EXPECTED_ARTIFACT_KEYS = {
+    "user_profile.json": [
+        "equipment",
+        "experience_level",
+        "goal",
+        "intended_exercise",
+        "intended_variation",
+        "known_limitations",
+    ],
+    "video_manifest.json": [
+        "analysis_allowed",
+        "duration_sec",
+        "fps",
+        "quality_warnings",
+        "sampled_frames",
+        "total_frames",
+        "video_path",
+    ],
+    "pose_sequence.json": ["frames", "normalized", "pose_valid_ratio", "smoothing_method"],
+    "exercise_classification.json": [
+        "confidence",
+        "exercise",
+        "fallback_required",
+        "window_predictions",
+    ],
+    "reps.json": ["exercise", "partial_reps", "reps"],
+    "rep_analysis.json": ["aggregate_metrics", "exercise", "items"],
+    "variation.json": ["detected_variation", "exercise", "not_issues", "variation_confidence"],
+    "issue_markers.json": ["issues"],
+    "coach_summary.json": [
+        "confidence_notes",
+        "main_findings",
+        "next_session_plan",
+        "summary",
+        "top_fixes",
+        "variation_explanation",
+        "what_went_well",
+    ],
+    "verification.json": ["checks", "notes", "passed"],
+    "final_report.json": [
+        "artifacts",
+        "coach_summary",
+        "exercise",
+        "issue_markers",
+        "profile",
+        "rep_analysis",
+        "reps",
+        "run_id",
+        "variation",
+        "verification",
+        "video_manifest",
+    ],
+    "manifest.json": ["artifacts", "mock_mode", "run_id"],
+}
+
+
+class PipelineContractTests(unittest.TestCase):
+    def setUp(self) -> None:
+        self.temp_dir = tempfile.TemporaryDirectory()
+        self.original_runs_dir = pipeline.RUNS_DIR
+        pipeline.RUNS_DIR = Path(self.temp_dir.name) / "runs"
+
+    def tearDown(self) -> None:
+        pipeline.RUNS_DIR = self.original_runs_dir
+        self.temp_dir.cleanup()
+
+    def _assert_pipeline_artifacts(self, result: dict[str, object]) -> None:
+        run_dir = Path(str(result["run_dir"]))
+        manifest_path = run_dir / "manifest.json"
+        self.assertTrue(manifest_path.exists())
+
+        for artifact_name, keys in EXPECTED_ARTIFACT_KEYS.items():
+            artifact_path = run_dir / artifact_name
+            self.assertTrue(artifact_path.exists(), artifact_name)
+            payload = json.loads(artifact_path.read_text(encoding="utf-8"))
+            self.assertEqual(sorted(payload.keys()), keys, artifact_name)
+
+        manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+        self.assertTrue(manifest["mock_mode"])
+        self.assertEqual(
+            [artifact["name"] for artifact in manifest["artifacts"]],
+            [
+                "user_profile.json",
+                "video_manifest.json",
+                "pose_sequence.json",
+                "exercise_classification.json",
+                "reps.json",
+                "rep_analysis.json",
+                "variation.json",
+                "issue_markers.json",
+                "annotated_video_placeholder.json",
+                "coach_summary.json",
+                "verification.json",
+                "final_report.json",
+            ],
+        )
+
+    def test_pipeline_runs_end_to_end_without_video(self) -> None:
+        result = pipeline.run_pipeline(video_path=None, profile_input=PROFILE_INPUT, mock=True)
+
+        self._assert_pipeline_artifacts(result)
+        report = result["final_report"]
+        self.assertEqual(report["exercise"]["exercise"], "push_up")
+        self.assertEqual(report["video_manifest"]["quality_warnings"], ["no_video_uploaded_mock_mode"])
+
+    def test_pipeline_runs_end_to_end_with_fixture_video_path(self) -> None:
+        fixture = Path(__file__).parent / "fixtures" / "sample.mp4"
+        result = pipeline.run_pipeline(video_path=str(fixture), profile_input=PROFILE_INPUT, mock=True)
+
+        self._assert_pipeline_artifacts(result)
+        report = result["final_report"]
+        self.assertEqual(report["video_manifest"]["video_path"], str(fixture))
+        self.assertEqual(report["video_manifest"]["quality_warnings"], [])
+
+    def test_contract_validation_rejects_missing_required_field(self) -> None:
+        payload = {
+            "goal": "beginner_practice",
+            "experience_level": "beginner",
+            "intended_exercise": "auto",
+            "intended_variation": None,
+            "known_limitations": [],
+        }
+
+        with self.assertRaisesRegex(ContractValidationError, "missing required"):
+            validate_contract("user_profile.json", payload)
+
+    def test_contract_validation_rejects_invalid_enum_value(self) -> None:
+        profile = UserProfile(
+            goal="beginner_practice",
+            experience_level="expert",
+            intended_exercise="auto",
+            intended_variation=None,
+            known_limitations=[],
+            equipment="bodyweight",
+        )
+
+        with self.assertRaisesRegex(ContractValidationError, "invalid enum"):
+            validate_contract("user_profile.json", profile)
+
+
+if __name__ == "__main__":
+    unittest.main()