Merged in feature/mutable-metadata1 (pull request #221)

M1, M2 and M3 complete

* M1, M2 and M3 complete

* review changes

* docs

* docs

api/queryAPI/fieldextractions.go

@@ -1,6 +1,7 @@
 package queryapi
 
 import (
+	"errors"
 	"fmt"
 	"log/slog"
 	"net/http"
@@ -10,6 +11,7 @@ import (
 	"queryorchestration/internal/fieldextraction"
 
 	"github.com/google/uuid"
+	"github.com/jackc/pgx/v5/pgconn"
 	"github.com/jackc/pgx/v5/pgtype"
 	"github.com/labstack/echo/v4"
 	openapi_types "github.com/oapi-codegen/runtime/types"
@@ -45,6 +47,24 @@ func (s *Controllers) CreateFieldExtraction(ctx echo.Context) error {
 	// Create field extraction via service
 	extraction, err := s.svc.FieldExtraction.CreateFieldExtraction(ctx.Request().Context(), input)
 	if err != nil {
+		// Milestone 2.5: map the new typed sentinels from the service
+		// layer plus the Postgres check_violation (Trigger 2 backstop)
+		// onto clean HTTP status codes before falling through to 500.
+		if errors.Is(err, fieldextraction.ErrDocumentNotFound) {
+			return echo.NewHTTPError(http.StatusNotFound, "document not found")
+		}
+		if errors.Is(err, fieldextraction.ErrMutualExclusivityViolation) {
+			return echo.NewHTTPError(http.StatusConflict,
+				"document is bound to a custom schema and cannot accept legacy field extractions")
+		}
+		var pgErr *pgconn.PgError
+		if errors.As(err, &pgErr) && pgErr.Code == "23514" {
+			// Trigger 2 fired. Defense in depth — service-layer guard
+			// already should have caught this, but if the lock path
+			// was bypassed (regression) the DB enforces the same 409.
+			return echo.NewHTTPError(http.StatusConflict,
+				"document is bound to a custom schema and cannot accept legacy field extractions")
+		}
 		slog.Error("failed to create field extraction", "error", err, "document_id", documentID)
 		return echo.NewHTTPError(http.StatusInternalServerError, "failed to create field extraction")
 	}