step one

internal/api/admin/datasets.go

@@ -0,0 +1,206 @@
+// Package admin implements dataset-management HTTP endpoints used by the
+// stratoflights operator console.
+//
+// Endpoints:
+//
+//	GET    /api/v1/admin/datasets        list stored epochs
+//	POST   /api/v1/admin/datasets        trigger a download
+//	DELETE /api/v1/admin/datasets/{epoch} delete a stored epoch
+//	GET    /api/v1/admin/jobs            list all jobs
+//	GET    /api/v1/admin/jobs/{id}       fetch one job
+//	DELETE /api/v1/admin/jobs/{id}       cancel a running job
+package admin
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"time"
+
+	"go.uber.org/zap"
+
+	"predictor-refactored/internal/datasets"
+)
+
+// Handler serves all /api/v1/admin/* endpoints.
+type Handler struct {
+	mgr *datasets.Manager
+	log *zap.Logger
+}
+
+// New wires an admin handler.
+func New(mgr *datasets.Manager, log *zap.Logger) *Handler {
+	if log == nil {
+		log = zap.NewNop()
+	}
+	return &Handler{mgr: mgr, log: log}
+}
+
+// Register installs admin routes on mux. Routes are mounted under
+// /api/v1/admin/...
+func (h *Handler) Register(mux *http.ServeMux) {
+	mux.HandleFunc("GET /api/v1/admin/datasets", h.listDatasets)
+	mux.HandleFunc("POST /api/v1/admin/datasets", h.triggerDownload)
+	mux.HandleFunc("DELETE /api/v1/admin/datasets/{epoch}", h.deleteDataset)
+	mux.HandleFunc("GET /api/v1/admin/jobs", h.listJobs)
+	mux.HandleFunc("GET /api/v1/admin/jobs/{id}", h.getJob)
+	mux.HandleFunc("DELETE /api/v1/admin/jobs/{id}", h.cancelJob)
+}
+
+// listDatasets handles GET /api/v1/admin/datasets.
+func (h *Handler) listDatasets(w http.ResponseWriter, _ *http.Request) {
+	epochs, err := h.mgr.ListEpochs()
+	if err != nil {
+		writeError(w, http.StatusInternalServerError, err.Error())
+		return
+	}
+	active := ""
+	if a := h.mgr.Active(); a != nil {
+		active = a.Epoch().UTC().Format(time.RFC3339)
+	}
+	out := struct {
+		Source         string   `json:"source"`
+		Active         string   `json:"active,omitempty"`
+		Epochs         []string `json:"epochs"`
+	}{
+		Source: h.mgr.Source(),
+		Active: active,
+	}
+	for _, e := range epochs {
+		out.Epochs = append(out.Epochs, e.UTC().Format(time.RFC3339))
+	}
+	writeJSON(w, http.StatusOK, out)
+}
+
+// triggerDownload handles POST /api/v1/admin/datasets.
+//
+// Body: {"epoch": "2026-03-28T06:00:00Z"} OR {"latest": true}.
+func (h *Handler) triggerDownload(w http.ResponseWriter, r *http.Request) {
+	var body struct {
+		Epoch  string `json:"epoch,omitempty"`
+		Latest bool   `json:"latest,omitempty"`
+	}
+	if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
+		writeError(w, http.StatusBadRequest, "invalid body: "+err.Error())
+		return
+	}
+	if !body.Latest && body.Epoch == "" {
+		writeError(w, http.StatusBadRequest, "specify either epoch or latest=true")
+		return
+	}
+
+	var epoch time.Time
+	if body.Latest {
+		ctx, cancel := context.WithTimeout(r.Context(), 30*time.Second)
+		defer cancel()
+		jobID, err := h.mgr.Refresh(ctx, 0)
+		if err != nil {
+			writeError(w, http.StatusInternalServerError, err.Error())
+			return
+		}
+		writeJSON(w, http.StatusAccepted, map[string]string{"job_id": jobID})
+		return
+	}
+
+	var err error
+	epoch, err = time.Parse(time.RFC3339, body.Epoch)
+	if err != nil {
+		writeError(w, http.StatusBadRequest, "invalid epoch: "+err.Error())
+		return
+	}
+	jobID := h.mgr.Download(epoch)
+	writeJSON(w, http.StatusAccepted, map[string]string{"job_id": jobID})
+}
+
+// deleteDataset handles DELETE /api/v1/admin/datasets/{epoch}.
+func (h *Handler) deleteDataset(w http.ResponseWriter, r *http.Request) {
+	rawEpoch := r.PathValue("epoch")
+	epoch, err := time.Parse(time.RFC3339, rawEpoch)
+	if err != nil {
+		writeError(w, http.StatusBadRequest, "invalid epoch: "+err.Error())
+		return
+	}
+	if err := h.mgr.RemoveEpoch(epoch); err != nil {
+		writeError(w, http.StatusInternalServerError, err.Error())
+		return
+	}
+	w.WriteHeader(http.StatusNoContent)
+}
+
+// listJobs handles GET /api/v1/admin/jobs.
+func (h *Handler) listJobs(w http.ResponseWriter, _ *http.Request) {
+	jobs := h.mgr.ListJobs()
+	out := make([]jobDTO, 0, len(jobs))
+	for _, j := range jobs {
+		out = append(out, toDTO(j))
+	}
+	writeJSON(w, http.StatusOK, out)
+}
+
+// getJob handles GET /api/v1/admin/jobs/{id}.
+func (h *Handler) getJob(w http.ResponseWriter, r *http.Request) {
+	id := r.PathValue("id")
+	job, ok := h.mgr.GetJob(id)
+	if !ok {
+		writeError(w, http.StatusNotFound, "job not found")
+		return
+	}
+	writeJSON(w, http.StatusOK, toDTO(job))
+}
+
+// cancelJob handles DELETE /api/v1/admin/jobs/{id}.
+func (h *Handler) cancelJob(w http.ResponseWriter, r *http.Request) {
+	id := r.PathValue("id")
+	if !h.mgr.CancelJob(id) {
+		writeError(w, http.StatusConflict, "job not found or already terminal")
+		return
+	}
+	w.WriteHeader(http.StatusNoContent)
+}
+
+type jobDTO struct {
+	ID        string  `json:"id"`
+	Source    string  `json:"source"`
+	Epoch     string  `json:"epoch"`
+	Status    string  `json:"status"`
+	StartedAt string  `json:"started_at"`
+	EndedAt   string  `json:"ended_at,omitempty"`
+	Err       string  `json:"error,omitempty"`
+	Total     int     `json:"total_units"`
+	Done      int     `json:"done_units"`
+	Bytes     int64   `json:"bytes"`
+}
+
+func toDTO(j datasets.JobInfo) jobDTO {
+	dto := jobDTO{
+		ID:        j.ID,
+		Source:    j.Source,
+		Epoch:     j.Epoch.UTC().Format(time.RFC3339),
+		Status:    string(j.Status),
+		StartedAt: j.StartedAt.UTC().Format(time.RFC3339),
+		Err:       j.Err,
+		Total:     j.Total,
+		Done:      j.Done,
+		Bytes:     j.Bytes,
+	}
+	if j.EndedAt != nil {
+		dto.EndedAt = j.EndedAt.UTC().Format(time.RFC3339)
+	}
+	return dto
+}
+
+func writeJSON(w http.ResponseWriter, status int, body any) {
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(status)
+	_ = json.NewEncoder(w).Encode(body)
+}
+
+func writeError(w http.ResponseWriter, status int, description string) {
+	writeJSON(w, status, map[string]any{
+		"error": map[string]string{
+			"type":        http.StatusText(status),
+			"description": description,
+		},
+	})
+}
+

internal/api/middleware/cors.go

@@ -0,0 +1,20 @@
+package middleware
+
+import "net/http"
+
+// CORS wraps next with permissive CORS headers and short-circuits OPTIONS preflight.
+//
+// This service is meant to sit behind an authenticated gateway, so we set
+// "Access-Control-Allow-Origin: *". Tighten this if you deploy elsewhere.
+func CORS(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Access-Control-Allow-Origin", "*")
+		w.Header().Set("Access-Control-Allow-Methods", "GET, POST, DELETE, OPTIONS")
+		w.Header().Set("Access-Control-Allow-Headers", "Content-Type")
+		if r.Method == http.MethodOptions {
+			w.WriteHeader(http.StatusNoContent)
+			return
+		}
+		next.ServeHTTP(w, r)
+	})
+}

internal/api/middleware/log.go

@@ -0,0 +1,51 @@
+// Package middleware contains HTTP and ogen middleware used by the API layer.
+package middleware
+
+import (
+	"net/http"
+	"time"
+
+	"github.com/ogen-go/ogen/middleware"
+	"go.uber.org/zap"
+)
+
+// OgenLogging is an ogen middleware that logs request duration and outcome.
+func OgenLogging(log *zap.Logger) middleware.Middleware {
+	return func(req middleware.Request, next func(req middleware.Request) (middleware.Response, error)) (middleware.Response, error) {
+		lg := log.With(zap.String("op", req.OperationID))
+		start := time.Now()
+		resp, err := next(req)
+		dur := time.Since(start)
+		if err != nil {
+			lg.Error("request failed", zap.Duration("duration", dur), zap.Error(err))
+		} else {
+			lg.Info("request completed", zap.Duration("duration", dur))
+		}
+		return resp, err
+	}
+}
+
+// statusRecorder captures the response status for HTTPLogging.
+type statusRecorder struct {
+	http.ResponseWriter
+	status int
+}
+
+func (r *statusRecorder) WriteHeader(code int) {
+	r.status = code
+	r.ResponseWriter.WriteHeader(code)
+}
+
+// HTTPLogging wraps the given http.Handler with a per-request log line.
+func HTTPLogging(log *zap.Logger, next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		start := time.Now()
+		rec := &statusRecorder{ResponseWriter: w, status: 200}
+		next.ServeHTTP(rec, r)
+		log.Info("http",
+			zap.String("method", r.Method),
+			zap.String("path", r.URL.Path),
+			zap.Int("status", rec.status),
+			zap.Duration("duration", time.Since(start)))
+	})
+}

internal/api/tawhiri/handler.go

@@ -0,0 +1,252 @@
+// Package tawhiri implements the legacy Tawhiri-compatible HTTP endpoint
+// (GET /api/v1/prediction). The request/response shapes match the original
+// Cambridge University Spaceflight predictor for drop-in compatibility.
+//
+// Internally the handler builds an engine.Profile from query parameters and
+// dispatches it through the same engine path as the new v2 endpoint.
+package tawhiri
+
+import (
+	"context"
+	"errors"
+	"net/http"
+	"time"
+
+	"go.uber.org/zap"
+
+	"predictor-refactored/internal/datasets"
+	"predictor-refactored/internal/elevation"
+	"predictor-refactored/internal/engine"
+	"predictor-refactored/internal/metrics"
+	api "predictor-refactored/pkg/rest"
+)
+
+// Handler implements api.Handler (the ogen-generated interface for
+// performPrediction and readinessCheck).
+type Handler struct {
+	mgr     *datasets.Manager
+	elev    *elevation.Dataset
+	metrics metrics.Sink
+	log     *zap.Logger
+}
+
+// New wires a Handler.
+func New(mgr *datasets.Manager, elev *elevation.Dataset, sink metrics.Sink, log *zap.Logger) *Handler {
+	if log == nil {
+		log = zap.NewNop()
+	}
+	if sink == nil {
+		sink = metrics.Noop()
+	}
+	return &Handler{mgr: mgr, elev: elev, metrics: sink, log: log}
+}
+
+// Compile-time check that Handler satisfies api.Handler.
+var _ api.Handler = (*Handler)(nil)
+
+// PerformPrediction runs the Tawhiri-style prediction.
+func (h *Handler) PerformPrediction(ctx context.Context, params api.PerformPredictionParams) (*api.PredictionResponse, error) {
+	field := h.mgr.Active()
+	if field == nil {
+		return nil, newError(http.StatusServiceUnavailable, "no dataset loaded, service is starting up")
+	}
+
+	// Parameters with Tawhiri defaults.
+	profileKind := "standard_profile"
+	if v, ok := params.Profile.Get(); ok {
+		profileKind = string(v)
+	}
+	ascentRate := 5.0
+	if v, ok := params.AscentRate.Get(); ok {
+		ascentRate = v
+	}
+	burstAltitude := 28000.0
+	if v, ok := params.BurstAltitude.Get(); ok {
+		burstAltitude = v
+	}
+	descentRate := 5.0
+	if v, ok := params.DescentRate.Get(); ok {
+		descentRate = v
+	}
+	launchAlt := 0.0
+	if v, ok := params.LaunchAltitude.Get(); ok {
+		launchAlt = v
+	}
+
+	lng := params.LaunchLongitude
+	if lng < 0 {
+		lng += 360
+	}
+
+	launchTime := float64(params.LaunchDatetime.Unix())
+	warnings := &engine.Warnings{}
+
+	// Build the profile.
+	var stageNames []string
+	var prof engine.Profile
+	switch profileKind {
+	case "standard_profile":
+		stageNames = []string{"ascent", "descent"}
+		prof = engine.Profile{
+			Direction: engine.Forward,
+			Stages: []*engine.Propagator{
+				{
+					Name: "ascent",
+					Step: 60,
+					Model: engine.Sum(
+						engine.ConstantRate(ascentRate),
+						engine.WindTransport(field, warnings),
+					),
+					Constraints: []engine.Constraint{engine.MaxAltitude{Limit: burstAltitude, On: engine.ActionStop}},
+				},
+				{
+					Name: "descent",
+					Step: 60,
+					Model: engine.Sum(
+						engine.ParachuteDescent(descentRate),
+						engine.WindTransport(field, warnings),
+					),
+					Constraints: descentConstraints(h.elev),
+				},
+			},
+		}
+	case "float_profile":
+		floatAlt := 25000.0
+		if v, ok := params.FloatAltitude.Get(); ok {
+			floatAlt = v
+		}
+		stopTime := params.LaunchDatetime.Add(24 * time.Hour)
+		if v, ok := params.StopDatetime.Get(); ok {
+			stopTime = v
+		}
+		stageNames = []string{"ascent", "float"}
+		prof = engine.Profile{
+			Direction: engine.Forward,
+			Stages: []*engine.Propagator{
+				{
+					Name: "ascent",
+					Step: 60,
+					Model: engine.Sum(
+						engine.ConstantRate(ascentRate),
+						engine.WindTransport(field, warnings),
+					),
+					Constraints: []engine.Constraint{engine.MaxAltitude{Limit: floatAlt, On: engine.ActionStop}},
+				},
+				{
+					Name:        "float",
+					Step:        60,
+					Model:       engine.WindTransport(field, warnings),
+					Constraints: []engine.Constraint{engine.MaxTime{Limit: float64(stopTime.Unix()), On: engine.ActionStop}},
+				},
+			},
+		}
+	default:
+		return nil, newError(http.StatusBadRequest, "unknown profile: "+profileKind)
+	}
+
+	started := time.Now().UTC()
+	results := prof.Run(launchTime, engine.State{Lat: params.LaunchLatitude, Lng: lng, Altitude: launchAlt})
+	completed := time.Now().UTC()
+	h.metrics.Prediction(profileKind, completed.Sub(started), nil)
+
+	resp := &api.PredictionResponse{
+		Metadata: api.PredictionResponseMetadata{
+			StartDatetime:    started,
+			CompleteDatetime: completed,
+		},
+	}
+
+	for i, r := range results {
+		stageName := "ascent"
+		if i < len(stageNames) {
+			stageName = stageNames[i]
+		}
+		stageEnum := api.PredictionResponsePredictionItemStageAscent
+		switch stageName {
+		case "descent":
+			stageEnum = api.PredictionResponsePredictionItemStageDescent
+		case "float":
+			stageEnum = api.PredictionResponsePredictionItemStageFloat
+		}
+		traj := make([]api.PredictionResponsePredictionItemTrajectoryItem, 0, len(r.Points))
+		for _, pt := range r.Points {
+			ptLng := pt.Lng
+			if ptLng > 180 {
+				ptLng -= 360
+			}
+			traj = append(traj, api.PredictionResponsePredictionItemTrajectoryItem{
+				Datetime:  time.Unix(int64(pt.Time), 0).UTC(),
+				Latitude:  pt.Lat,
+				Longitude: ptLng,
+				Altitude:  pt.Altitude,
+			})
+		}
+		resp.Prediction = append(resp.Prediction, api.PredictionResponsePredictionItem{
+			Stage:      stageEnum,
+			Trajectory: traj,
+		})
+	}
+
+	resp.Request = api.NewOptPredictionResponseRequest(api.PredictionResponseRequest{
+		Dataset:         api.NewOptString(field.Epoch().Format("2006-01-02T15:04:05Z")),
+		LaunchLatitude:  api.NewOptFloat64(params.LaunchLatitude),
+		LaunchLongitude: api.NewOptFloat64(params.LaunchLongitude),
+		LaunchDatetime:  api.NewOptString(params.LaunchDatetime.Format(time.RFC3339)),
+		LaunchAltitude:  params.LaunchAltitude,
+	})
+
+	if warns := warnings.ToMap(); len(warns) > 0 {
+		resp.Warnings = api.NewOptPredictionResponseWarnings(api.PredictionResponseWarnings{})
+	}
+
+	h.log.Info("prediction complete",
+		zap.String("profile", profileKind),
+		zap.Int("stages", len(results)),
+		zap.Duration("elapsed", completed.Sub(started)))
+
+	return resp, nil
+}
+
+// descentConstraints returns the descent termination set: TerrainContact if an
+// elevation dataset is loaded, MinAltitude(0) otherwise.
+func descentConstraints(elev *elevation.Dataset) []engine.Constraint {
+	if elev != nil {
+		return []engine.Constraint{engine.TerrainContact{Provider: elev, On: engine.ActionStop}}
+	}
+	return []engine.Constraint{engine.MinAltitude{Limit: 0, On: engine.ActionStop}}
+}
+
+// ReadinessCheck reports whether a dataset is currently loaded.
+func (h *Handler) ReadinessCheck(_ context.Context) (*api.ReadinessResponse, error) {
+	resp := &api.ReadinessResponse{}
+	if field := h.mgr.Active(); field != nil {
+		resp.Status = api.ReadinessResponseStatusOk
+		resp.DatasetTime = api.NewOptDateTime(field.Epoch())
+	} else {
+		resp.Status = api.ReadinessResponseStatusNotReady
+		resp.ErrorMessage = api.NewOptString("no dataset loaded")
+	}
+	return resp, nil
+}
+
+// NewError implements the ogen Handler interface for unhandled errors.
+func (h *Handler) NewError(_ context.Context, err error) *api.ErrorStatusCode {
+	var statusErr *api.ErrorStatusCode
+	if errors.As(err, &statusErr) {
+		return statusErr
+	}
+	h.log.Error("unhandled error", zap.Error(err))
+	return newError(http.StatusInternalServerError, err.Error())
+}
+
+func newError(status int, description string) *api.ErrorStatusCode {
+	return &api.ErrorStatusCode{
+		StatusCode: status,
+		Response: api.Error{
+			Error: api.ErrorError{
+				Type:        http.StatusText(status),
+				Description: description,
+			},
+		},
+	}
+}

internal/api/transport.go

@@ -0,0 +1,109 @@
+// Package api wires together every HTTP-facing component of the service:
+//
+//   - Tawhiri-compatible v1 endpoints generated from the OpenAPI spec (ogen);
+//   - The new v2 prediction endpoint;
+//   - Dataset and job admin endpoints under /api/v1/admin/;
+//   - Optional Prometheus-format metrics endpoint.
+package api
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+	"time"
+
+	"go.uber.org/zap"
+
+	"predictor-refactored/internal/api/admin"
+	"predictor-refactored/internal/api/middleware"
+	"predictor-refactored/internal/api/tawhiri"
+	v2 "predictor-refactored/internal/api/v2"
+	"predictor-refactored/internal/datasets"
+	"predictor-refactored/internal/elevation"
+	"predictor-refactored/internal/metrics"
+	apirest "predictor-refactored/pkg/rest"
+)
+
+// Server is the top-level HTTP server.
+type Server struct {
+	port int
+	mux  *http.ServeMux
+	log  *zap.Logger
+}
+
+// Deps are the runtime dependencies the API layer needs.
+type Deps struct {
+	Manager   *datasets.Manager
+	Elevation *elevation.Dataset
+	Metrics   metrics.Sink
+	MetricsHandler http.Handler // optional; mounted at MetricsPath when non-nil
+	MetricsPath    string
+	Log       *zap.Logger
+}
+
+// New wires the HTTP server. The returned Server is not yet started.
+func New(port int, d Deps) (*Server, error) {
+	if d.Log == nil {
+		d.Log = zap.NewNop()
+	}
+	if d.Metrics == nil {
+		d.Metrics = metrics.Noop()
+	}
+
+	mux := http.NewServeMux()
+
+	// ogen-generated server handles the Tawhiri-compat surface
+	// (GET /api/v1/prediction and GET /ready).
+	tw := tawhiri.New(d.Manager, d.Elevation, d.Metrics, d.Log)
+	ogenSrv, err := apirest.NewServer(tw, apirest.WithMiddleware(middleware.OgenLogging(d.Log)))
+	if err != nil {
+		return nil, fmt.Errorf("create ogen server: %w", err)
+	}
+
+	// New primary prediction endpoint.
+	v2h := v2.New(d.Manager, d.Elevation, d.Metrics, d.Log)
+	mux.Handle("/api/v2/prediction", v2h)
+
+	// Admin endpoints.
+	adminH := admin.New(d.Manager, d.Log)
+	adminH.Register(mux)
+
+	// Metrics endpoint.
+	if d.MetricsHandler != nil && d.MetricsPath != "" {
+		mux.Handle(d.MetricsPath, d.MetricsHandler)
+	}
+
+	// Fallback to the ogen-generated routes (v1 + ready) for anything else.
+	mux.Handle("/", ogenSrv)
+
+	return &Server{
+		port: port,
+		mux:  mux,
+		log:  d.Log,
+	}, nil
+}
+
+// Run starts the HTTP server and blocks until it returns.
+//
+// The handler chain is: CORS → request logger → mux.
+func (s *Server) Run(ctx context.Context) error {
+	srv := &http.Server{
+		Addr:    fmt.Sprintf(":%d", s.port),
+		Handler: middleware.CORS(middleware.HTTPLogging(s.log, s.mux)),
+	}
+
+	errCh := make(chan error, 1)
+	go func() {
+		s.log.Info("HTTP server starting", zap.Int("port", s.port))
+		errCh <- srv.ListenAndServe()
+	}()
+
+	select {
+	case err := <-errCh:
+		return err
+	case <-ctx.Done():
+		shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+		defer cancel()
+		return srv.Shutdown(shutdownCtx)
+	}
+}

internal/api/v2/handler.go

@@ -0,0 +1,173 @@
+package v2
+
+import (
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"time"
+
+	"go.uber.org/zap"
+
+	"predictor-refactored/internal/datasets"
+	"predictor-refactored/internal/elevation"
+	"predictor-refactored/internal/engine"
+	"predictor-refactored/internal/metrics"
+)
+
+// Handler serves POST /api/v2/prediction.
+type Handler struct {
+	mgr     *datasets.Manager
+	elev    *elevation.Dataset
+	metrics metrics.Sink
+	log     *zap.Logger
+}
+
+// New wires a v2 Handler.
+func New(mgr *datasets.Manager, elev *elevation.Dataset, sink metrics.Sink, log *zap.Logger) *Handler {
+	if log == nil {
+		log = zap.NewNop()
+	}
+	if sink == nil {
+		sink = metrics.Noop()
+	}
+	return &Handler{mgr: mgr, elev: elev, metrics: sink, log: log}
+}
+
+func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		writeError(w, http.StatusMethodNotAllowed, "use POST")
+		return
+	}
+
+	var req PredictionRequest
+	dec := json.NewDecoder(r.Body)
+	dec.DisallowUnknownFields()
+	if err := dec.Decode(&req); err != nil {
+		writeError(w, http.StatusBadRequest, "invalid request body: "+err.Error())
+		return
+	}
+
+	if err := validateRequest(req); err != nil {
+		writeError(w, http.StatusBadRequest, err.Error())
+		return
+	}
+
+	field := h.mgr.Active()
+	if field == nil {
+		writeError(w, http.StatusServiceUnavailable, "no dataset loaded, service is starting up")
+		return
+	}
+
+	// Normalize longitude to [0, 360) for internal use.
+	lng := req.Launch.Longitude
+	if lng < 0 {
+		lng += 360
+	}
+
+	warnings := &engine.Warnings{}
+	var terrain engine.TerrainProvider
+	if h.elev != nil {
+		terrain = h.elev
+	}
+
+	prof, err := buildProfile(req, field, terrain, warnings)
+	if err != nil {
+		writeError(w, http.StatusBadRequest, err.Error())
+		return
+	}
+
+	started := time.Now().UTC()
+	results := prof.Run(float64(req.Launch.Time.Unix()), engine.State{
+		Lat:      req.Launch.Latitude,
+		Lng:      lng,
+		Altitude: req.Launch.Altitude,
+	})
+	completed := time.Now().UTC()
+	h.metrics.Prediction("v2", completed.Sub(started), nil)
+
+	resp := PredictionResponse{
+		Stages:      make([]StageResult, 0, len(results)),
+		StartedAt:   started,
+		CompletedAt: completed,
+		Dataset: DatasetInfo{
+			Source: field.Source(),
+			Epoch:  field.Epoch(),
+		},
+	}
+	for _, r := range results {
+		stage := StageResult{
+			Name:    r.Propagator,
+			Outcome: outcomeString(r.Outcome),
+		}
+		if r.Constraint != nil {
+			stage.Constraint = r.Constraint.Name()
+		}
+		stage.Trajectory = make([]TrajectoryPoint, len(r.Points))
+		for i, pt := range r.Points {
+			ptLng := pt.Lng
+			if ptLng > 180 {
+				ptLng -= 360
+			}
+			stage.Trajectory[i] = TrajectoryPoint{
+				Time:      time.Unix(int64(pt.Time), 0).UTC(),
+				Latitude:  pt.Lat,
+				Longitude: ptLng,
+				Altitude:  pt.Altitude,
+			}
+		}
+		resp.Stages = append(resp.Stages, stage)
+	}
+	if warns := warnings.ToMap(); len(warns) > 0 {
+		resp.Warnings = warns
+	}
+
+	h.log.Info("v2 prediction complete",
+		zap.Int("stages", len(results)),
+		zap.Duration("elapsed", completed.Sub(started)))
+	writeJSON(w, http.StatusOK, resp)
+}
+
+func validateRequest(req PredictionRequest) error {
+	if req.Launch.Latitude < -90 || req.Launch.Latitude > 90 {
+		return fmt.Errorf("launch.latitude must be in [-90, 90]")
+	}
+	if req.Launch.Longitude < -180 || req.Launch.Longitude >= 360 {
+		return fmt.Errorf("launch.longitude must be in [-180, 360)")
+	}
+	if len(req.Profile) == 0 {
+		return fmt.Errorf("profile must contain at least one stage")
+	}
+	for i, s := range req.Profile {
+		if s.Name == "" {
+			return fmt.Errorf("profile[%d].name is required", i)
+		}
+		if s.Model.Type == "" {
+			return fmt.Errorf("profile[%d].model.type is required", i)
+		}
+	}
+	return nil
+}
+
+func outcomeString(o engine.Outcome) string {
+	switch o {
+	case engine.OutcomeStopped:
+		return "stopped"
+	case engine.OutcomeFallback:
+		return "fallback"
+	default:
+		return "continued"
+	}
+}
+
+func writeError(w http.ResponseWriter, status int, description string) {
+	writeJSON(w, status, ErrorResponse{Error: ErrorBody{
+		Type:        http.StatusText(status),
+		Description: description,
+	}})
+}
+
+func writeJSON(w http.ResponseWriter, status int, body any) {
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(status)
+	_ = json.NewEncoder(w).Encode(body)
+}

internal/api/v2/profile.go

@@ -0,0 +1,145 @@
+package v2
+
+import (
+	"fmt"
+
+	"predictor-refactored/internal/engine"
+	"predictor-refactored/internal/weather"
+)
+
+// buildProfile translates a PredictionRequest into an engine.Profile.
+//
+// elev may be nil when no terrain dataset is loaded; TerrainContact constraints
+// will return an error in that case.
+func buildProfile(req PredictionRequest, field weather.WindField, elev engine.TerrainProvider, warnings *engine.Warnings) (engine.Profile, error) {
+	if len(req.Profile) == 0 {
+		return engine.Profile{}, fmt.Errorf("profile must contain at least one stage")
+	}
+
+	step := req.Options.StepSeconds
+	if step == 0 {
+		step = 60
+	}
+	tol := req.Options.Tolerance
+	if tol == 0 {
+		tol = 0.01
+	}
+
+	dir := engine.Forward
+	switch req.Direction {
+	case "", "forward":
+		dir = engine.Forward
+	case "reverse":
+		dir = engine.Reverse
+	default:
+		return engine.Profile{}, fmt.Errorf("unknown direction %q", req.Direction)
+	}
+
+	props := make([]*engine.Propagator, len(req.Profile))
+	for i, stage := range req.Profile {
+		model, err := buildModel(stage.Model, field, warnings)
+		if err != nil {
+			return engine.Profile{}, fmt.Errorf("stage %q: %w", stage.Name, err)
+		}
+		constraints, err := buildConstraints(stage.Constraints, elev)
+		if err != nil {
+			return engine.Profile{}, fmt.Errorf("stage %q: %w", stage.Name, err)
+		}
+		props[i] = &engine.Propagator{
+			Name:        stage.Name,
+			Step:        step,
+			Model:       model,
+			Constraints: constraints,
+			Tolerance:   tol,
+		}
+	}
+
+	// Wire fallbacks once all stages exist.
+	for i, stage := range req.Profile {
+		if stage.FallbackIndex == nil {
+			continue
+		}
+		idx := *stage.FallbackIndex
+		if idx < 0 || idx >= len(props) {
+			return engine.Profile{}, fmt.Errorf("stage %q: fallback_index %d out of range", stage.Name, idx)
+		}
+		props[i].Fallback = props[idx]
+	}
+
+	return engine.Profile{Stages: props, Direction: dir}, nil
+}
+
+func buildModel(spec ModelSpec, field weather.WindField, warnings *engine.Warnings) (engine.Model, error) {
+	var base engine.Model
+	switch spec.Type {
+	case "constant_rate":
+		base = engine.ConstantRate(spec.Rate)
+	case "parachute_descent":
+		if spec.SeaLevelRate <= 0 {
+			return nil, fmt.Errorf("parachute_descent requires positive sea_level_rate")
+		}
+		base = engine.ParachuteDescent(spec.SeaLevelRate)
+	case "piecewise":
+		segs := make([]engine.RateSegment, len(spec.Segments))
+		for i, s := range spec.Segments {
+			segs[i] = engine.RateSegment{Until: s.Until, Rate: s.Rate}
+		}
+		base = engine.Piecewise(segs)
+	case "wind":
+		if field == nil {
+			return nil, fmt.Errorf("wind model requires a loaded dataset")
+		}
+		return engine.WindTransport(field, warnings), nil
+	default:
+		return nil, fmt.Errorf("unknown model type %q", spec.Type)
+	}
+
+	if spec.IncludeWind {
+		if field == nil {
+			return nil, fmt.Errorf("include_wind requires a loaded dataset")
+		}
+		return engine.Sum(base, engine.WindTransport(field, warnings)), nil
+	}
+	return base, nil
+}
+
+func buildConstraints(specs []ConstraintSpec, elev engine.TerrainProvider) ([]engine.Constraint, error) {
+	out := make([]engine.Constraint, 0, len(specs))
+	for _, spec := range specs {
+		action, err := parseAction(spec.Action)
+		if err != nil {
+			return nil, err
+		}
+		var c engine.Constraint
+		switch spec.Type {
+		case "max_altitude":
+			c = engine.MaxAltitude{Limit: spec.Limit, On: action}
+		case "min_altitude":
+			c = engine.MinAltitude{Limit: spec.Limit, On: action}
+		case "max_time":
+			c = engine.MaxTime{Limit: spec.Limit, On: action}
+		case "terrain_contact":
+			if elev == nil {
+				return nil, fmt.Errorf("terrain_contact requires an elevation dataset")
+			}
+			c = engine.TerrainContact{Provider: elev, On: action}
+		default:
+			return nil, fmt.Errorf("unknown constraint type %q", spec.Type)
+		}
+		out = append(out, c)
+	}
+	return out, nil
+}
+
+func parseAction(s string) (engine.Action, error) {
+	switch s {
+	case "", "stop":
+		return engine.ActionStop, nil
+	case "fallback":
+		return engine.ActionFallback, nil
+	case "clip":
+		return engine.ActionClip, nil
+	default:
+		return 0, fmt.Errorf("unknown constraint action %q", s)
+	}
+}

internal/api/v2/types.go

@@ -0,0 +1,114 @@
+// Package v2 implements the new primary prediction endpoint, which accepts a
+// user-defined profile (chain of propagators with optional constraints) and
+// returns the resulting trajectory.
+//
+// Endpoint: POST /api/v2/prediction
+package v2
+
+import "time"
+
+// PredictionRequest is the request body for POST /api/v2/prediction.
+type PredictionRequest struct {
+	Launch    Launch    `json:"launch"`
+	Profile   []Stage   `json:"profile"`
+	Options   Options   `json:"options,omitempty"`
+	Direction string    `json:"direction,omitempty"` // "forward" (default) or "reverse"
+}
+
+// Launch is the initial state of the balloon (or, for reverse predictions,
+// the known landing point).
+type Launch struct {
+	Time      time.Time `json:"time"`
+	Latitude  float64   `json:"latitude"`
+	Longitude float64   `json:"longitude"`
+	Altitude  float64   `json:"altitude"`
+}
+
+// Stage is one entry in the propagator chain.
+type Stage struct {
+	Name        string           `json:"name"`
+	Model       ModelSpec        `json:"model"`
+	Constraints []ConstraintSpec `json:"constraints,omitempty"`
+	// FallbackIndex, when set, points to another stage in the same profile to
+	// transfer to on ActionFallback constraints. Optional.
+	FallbackIndex *int `json:"fallback_index,omitempty"`
+}
+
+// ModelSpec describes the per-stage propagation model.
+type ModelSpec struct {
+	// Type selects the model: "constant_rate", "parachute_descent", "piecewise", "wind".
+	Type string `json:"type"`
+	// Rate (m/s) for constant_rate.
+	Rate float64 `json:"rate,omitempty"`
+	// SeaLevelRate (m/s, positive) for parachute_descent.
+	SeaLevelRate float64 `json:"sea_level_rate,omitempty"`
+	// Segments for piecewise.
+	Segments []PiecewiseSegment `json:"segments,omitempty"`
+	// IncludeWind sums a WindTransport model into the resulting derivative,
+	// allowing the same stage to model both vertical motion and wind drift.
+	IncludeWind bool `json:"include_wind"`
+}
+
+// PiecewiseSegment is one entry in a piecewise rate schedule.
+type PiecewiseSegment struct {
+	Until float64 `json:"until"` // UNIX seconds; segment applies for t < Until
+	Rate  float64 `json:"rate"`  // m/s
+}
+
+// ConstraintSpec describes one constraint attached to a stage.
+type ConstraintSpec struct {
+	// Type: "max_altitude", "min_altitude", "max_time", "terrain_contact".
+	Type string `json:"type"`
+	// Limit is interpreted per Type: metres for altitude, UNIX seconds for time.
+	Limit float64 `json:"limit,omitempty"`
+	// Action: "stop" (default), "fallback", "clip".
+	Action string `json:"action,omitempty"`
+}
+
+// Options tweaks the integrator behaviour.
+type Options struct {
+	StepSeconds float64 `json:"step_seconds,omitempty"`
+	Tolerance   float64 `json:"tolerance,omitempty"`
+}
+
+// PredictionResponse is the response body for POST /api/v2/prediction.
+type PredictionResponse struct {
+	Stages     []StageResult    `json:"stages"`
+	Warnings   map[string]any   `json:"warnings,omitempty"`
+	Dataset    DatasetInfo      `json:"dataset"`
+	StartedAt  time.Time        `json:"started_at"`
+	CompletedAt time.Time       `json:"completed_at"`
+}
+
+// StageResult is the outcome of one stage.
+type StageResult struct {
+	Name       string            `json:"name"`
+	Outcome    string            `json:"outcome"`         // "stopped" | "fallback" | "continued"
+	Constraint string            `json:"constraint,omitempty"`
+	Trajectory []TrajectoryPoint `json:"trajectory"`
+}
+
+// TrajectoryPoint is one sampled point of the trajectory.
+type TrajectoryPoint struct {
+	Time      time.Time `json:"time"`
+	Latitude  float64   `json:"latitude"`
+	Longitude float64   `json:"longitude"`
+	Altitude  float64   `json:"altitude"`
+}
+
+// DatasetInfo identifies the dataset the prediction was computed against.
+type DatasetInfo struct {
+	Source string    `json:"source"`
+	Epoch  time.Time `json:"epoch"`
+}
+
+// ErrorResponse is the JSON error shape used by both v2 and admin endpoints.
+type ErrorResponse struct {
+	Error ErrorBody `json:"error"`
+}
+
+// ErrorBody is the error detail.
+type ErrorBody struct {
+	Type        string `json:"type"`
+	Description string `json:"description"`
+}