WIP: M-1 handler sentinel error mapping (checkpoint before branch cleanup)

Uncommitted migration work at the time of branch cleanup. Tagged as
checkpoint/m1-migration-wip so the commit survives git gc --prune=now.

Session context: Phase 3 Part B+C of the M-1 sentinel error migration
was in progress. 38 modified files, 4 new files (errors.go + errors_test.go
in internal/service/ and internal/api/handler/). Resume from this commit
via 'git checkout checkpoint/m1-migration-wip'.

internal/api/handler/export_handler_test.go

@@ -108,9 +108,17 @@ func TestExportPEM_Download(t *testing.T) {
 }
 
 func TestExportPEM_NotFound(t *testing.T) {
+	// M-1 (P2): wrap with service.ErrNotFound via %w so the handler's
+	// errToStatus choke point dispatches to 404 via errors.Is. Pre-M-1 this
+	// test used a raw `fmt.Errorf("certificate not found")` string and relied
+	// on the handler's strings.Contains(err.Error(), "not found") classifier
+	// — which was the same mechanism that silently misclassified transient DB
+	// failures whose text happened to include "not found" (see docblock on
+	// ExportPEM handler). Pinning the sentinel contract makes this test
+	// regression-proof against wrap-text changes.
 	mockSvc := &MockExportService{
 		ExportPEMFn: func(_ context.Context, _ string) (*service.ExportPEMResult, error) {
-			return nil, fmt.Errorf("certificate not found")
+			return nil, fmt.Errorf("%w: certificate", service.ErrNotFound)
 		},
 	}
 	h := NewExportHandler(mockSvc)
@@ -214,9 +222,11 @@ func TestExportPKCS12_EmptyPassword(t *testing.T) {
 }
 
 func TestExportPKCS12_NotFound(t *testing.T) {
+	// M-1 (P2): same sentinel migration as TestExportPEM_NotFound — see
+	// rationale there.
 	mockSvc := &MockExportService{
 		ExportPKCS12Fn: func(_ context.Context, _ string, _ string) ([]byte, error) {
-			return nil, fmt.Errorf("certificate not found")
+			return nil, fmt.Errorf("%w: certificate", service.ErrNotFound)
 		},
 	}
 	h := NewExportHandler(mockSvc)
@@ -231,6 +241,31 @@ func TestExportPKCS12_NotFound(t *testing.T) {
 	}
 }
 
+// TestExportPKCS12_Unprocessable pins the M-1 (P2) 422 contract: when the
+// service layer wraps a parse failure with service.ErrUnprocessable, the
+// handler's errToStatus choke point must dispatch to 422 Unprocessable
+// Entity. Pre-M-1 this was classified via a 2-term substring net
+// (`"cannot be parsed"|"no certificates found"`) at export.go:101, which
+// would have been silently broken by a message reword in service/export.go.
+// The new sentinel makes the dispatch survive message rewording.
+func TestExportPKCS12_Unprocessable(t *testing.T) {
+	mockSvc := &MockExportService{
+		ExportPKCS12Fn: func(_ context.Context, _ string, _ string) ([]byte, error) {
+			return nil, fmt.Errorf("%w: certificate data cannot be parsed as X.509: asn1 decode error", service.ErrUnprocessable)
+		},
+	}
+	h := NewExportHandler(mockSvc)
+
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/certificates/mc-test-1/export/pkcs12", nil)
+	w := httptest.NewRecorder()
+
+	h.ExportPKCS12(w, req)
+
+	if w.Code != http.StatusUnprocessableEntity {
+		t.Fatalf("expected 422, got %d", w.Code)
+	}
+}
+
 func TestExportPKCS12_ServiceError(t *testing.T) {
 	mockSvc := &MockExportService{
 		ExportPKCS12Fn: func(_ context.Context, _ string, _ string) ([]byte, error) {