feat(sense): add reconciliation safety controls [T-012]

Sense/cmd/sense-api/main.go

@@ -15,8 +15,10 @@ import (
 	"yovision/sense/internal/auth"
 	"yovision/sense/internal/config"
 	"yovision/sense/internal/controlapi"
+	"yovision/sense/internal/metrics"
 	"yovision/sense/internal/mtx"
 	"yovision/sense/internal/onvif"
+	"yovision/sense/internal/orphan"
 	"yovision/sense/internal/probe"
 	"yovision/sense/internal/reconcile"
 	"yovision/sense/internal/store"
@@ -37,6 +39,14 @@ func run(logger *slog.Logger) error {
 	if err != nil {
 		return fmt.Errorf("load configuration: %w", err)
 	}
+	instanceID := cfg.InstanceID
+	if instanceID == "" {
+		instanceID, err = metrics.GenerateInstanceID()
+		if err != nil {
+			return err
+		}
+	}
+	registry := metrics.New(instanceID, version)
 	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
 	defer stop()
 
@@ -76,22 +86,36 @@ func run(logger *slog.Logger) error {
 		})
 	}
 	discovery := onvif.NewRouter(cameraAdapter, credentials)
-	reconciler := reconcile.New(repository, discovery, mediaClient)
+	reconciler := reconcile.NewWithOptions(repository, discovery, mediaClient, reconcile.Options{
+		InstanceID: instanceID, LeaseDuration: cfg.ReconcileLeaseDuration,
+		OperationTimeout: cfg.ReconcileOperationTimeout, Metrics: registry,
+	})
 	checker := probe.New(repository, mediaClient)
+	var orphanScanner *orphan.Manager
+	if cfg.OrphanScanEnabled {
+		orphanStore, ok := repository.(store.OrphanRepository)
+		if !ok {
+			return errors.New("selected repository does not support orphan scanning")
+		}
+		orphanScanner = orphan.New(orphanStore, mediaClient, instanceID, registry)
+	}
 	report := func(err error) {
 		// Domain and MediaMTX errors intentionally omit stream URIs and credentials.
 		logger.Warn("background convergence error", "error", err)
 	}
 	var background sync.WaitGroup
-	background.Add(2)
-	go func() {
-		defer background.Done()
-		reconciler.Run(ctx, cfg.ReconcileInterval, report)
-	}()
-	go func() {
-		defer background.Done()
-		checker.Run(ctx, cfg.ProbeInterval, report)
-	}()
+	startBackground := func(run func()) {
+		background.Add(1)
+		go func() {
+			defer background.Done()
+			run()
+		}()
+	}
+	startBackground(func() { reconciler.Run(ctx, cfg.ReconcileInterval, report) })
+	startBackground(func() { checker.Run(ctx, cfg.ProbeInterval, report) })
+	if orphanScanner != nil {
+		startBackground(func() { orphanScanner.Run(ctx, cfg.OrphanScanInterval, report) })
+	}
 
 	mux := http.NewServeMux()
 	mux.HandleFunc("GET /healthz", func(writer http.ResponseWriter, _ *http.Request) {
@@ -104,6 +128,9 @@ func run(logger *slog.Logger) error {
 		writer.WriteHeader(http.StatusOK)
 		_, _ = writer.Write([]byte(`{"status":"ready"}`))
 	})
+	if cfg.MetricsEnabled {
+		mux.Handle("GET /metrics", registry.Handler())
+	}
 	if cfg.ControlAPIEnabled {
 		mux.Handle("/api/v1/", controlHandler)
 	}
@@ -118,6 +145,7 @@ func run(logger *slog.Logger) error {
 	serverErrors := make(chan error, 1)
 	go func() {
 		logger.Info("Sense listening", "address", cfg.HTTPAddress, "version", version,
+			"instance_id", instanceID,
 			"control_api_enabled", cfg.ControlAPIEnabled)
 		serverErrors <- server.ListenAndServe()
 	}()

Sense/cmd/sense-orphan/main.go

@@ -0,0 +1,94 @@
+// sense-orphan is a local, PostgreSQL-backed operational command. Report is
+// read-only; apply requires a fresh scan ID, actor and exact confirmation.
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"flag"
+	"fmt"
+	"net/http"
+	"os"
+	"os/signal"
+	"strings"
+	"syscall"
+
+	"yovision/sense/internal/config"
+	"yovision/sense/internal/metrics"
+	"yovision/sense/internal/mtx"
+	"yovision/sense/internal/orphan"
+	"yovision/sense/internal/store"
+)
+
+func main() {
+	if err := run(); err != nil {
+		_, _ = fmt.Fprintln(os.Stderr, "sense-orphan failed:", err)
+		os.Exit(1)
+	}
+}
+
+func run() error {
+	mode := flag.String("mode", "report", "report or apply")
+	scanID := flag.String("scan-id", "", "fresh scan ID required by apply")
+	actor := flag.String("actor", "", "operator identifier required by apply")
+	confirm := flag.String("confirm", "", "exact confirmation: DELETE <scan-id>")
+	flag.Parse()
+
+	cfg, err := config.Load()
+	if err != nil {
+		return err
+	}
+	if !strings.EqualFold(strings.TrimSpace(cfg.DatabaseDriver), store.DriverPostgres) {
+		return errors.New("sense-orphan requires SENSE_DB_DRIVER=postgres")
+	}
+	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
+	defer stop()
+	repository, err := store.OpenPostgres(ctx, cfg.DatabaseDSN)
+	if err != nil {
+		return err
+	}
+	defer repository.Close()
+	media, err := mtx.NewClient(cfg.MediaMTXURL, &http.Client{Timeout: cfg.ReconcileOperationTimeout})
+	if err != nil {
+		return err
+	}
+	instanceID := cfg.InstanceID
+	if instanceID == "" {
+		instanceID, err = metrics.GenerateInstanceID()
+		if err != nil {
+			return err
+		}
+	}
+	manager := orphan.New(repository, media, instanceID, metrics.New(instanceID, "operator"))
+	encoder := json.NewEncoder(os.Stdout)
+	switch *mode {
+	case "report":
+		scan, err := manager.Report(ctx)
+		if err != nil {
+			return err
+		}
+		return encoder.Encode(struct {
+			ScanID        string `json:"scan_id"`
+			Observed      int    `json:"observed"`
+			OwnedStale    int    `json:"owned_stale"`
+			Unowned       int    `json:"unowned"`
+			SafetyAllowed bool   `json:"safety_allowed"`
+			SafetyReason  string `json:"safety_reason"`
+			ExpiresAt     string `json:"expires_at"`
+		}{
+			ScanID: scan.ID, Observed: scan.ObservedCount,
+			OwnedStale: scan.OwnedStaleCount, Unowned: scan.UnownedCount,
+			SafetyAllowed: scan.SafetyAllowed, SafetyReason: scan.SafetyReason,
+			ExpiresAt: scan.ExpiresAt.UTC().Format("2006-01-02T15:04:05Z07:00"),
+		})
+	case "apply":
+		result, err := manager.Apply(ctx, *scanID, *actor, *confirm)
+		if encodeErr := encoder.Encode(result); encodeErr != nil {
+			return encodeErr
+		}
+		return err
+	default:
+		return errors.New("mode must be report or apply")
+	}
+}